@damiangilgonzalez/harness 1.3.7

package/skills/article-writing/scripts/verify.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural + banlist lint for an `article-writing` draft.
+#
+# Usage: scripts/verify.sh path/to/article.md
+#
+# Read-only. Checks the on-page surface and banned phrasing of a single
+# article markdown file. It is a lint of STRUCTURE and PHRASING, not a
+# judge of whether the content is good — that is the capability eval's job.
+#
+# Exit 0 = all hard checks pass (or nothing to check). Exit 1 = a hard
+# check failed. Warnings never fail the run.
+#
+# The file is expected to carry, in YAML front-matter or a clearly
+# labelled block, a `title:` and `meta_description:` line, plus a JSON-LD
+# block (```json or <script type="application/ld+json">).
+
+set -u
+
+TARGET="${1:-}"
+
+# --- No target / empty target: pass cleanly, never a false failure. -------
+if [ -z "$TARGET" ]; then
+  echo "verify.sh: no article path given — nothing to check. PASS"
+  exit 0
+fi
+if [ ! -f "$TARGET" ]; then
+  echo "verify.sh: '$TARGET' is not a file — nothing to check. PASS"
+  exit 0
+fi
+if [ ! -s "$TARGET" ]; then
+  echo "verify.sh: '$TARGET' is empty — nothing to check. PASS"
+  exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BANLIST_FILE="$SCRIPT_DIR/../references/ai-tell-banlist.md"
+
+fail=0
+warn=0
+pass() { printf 'PASS  %s\n' "$1"; }
+bad()  { printf 'FAIL  %s\n' "$1"; fail=1; }
+note() { printf 'WARN  %s\n' "$1"; warn=1; }
+
+# --- 1. Title length ------------------------------------------------------
+# Grab the first `title:` value (front-matter or labelled block).
+title_line="$(grep -i -m1 -E '^[[:space:]]*title[[:space:]]*:' "$TARGET" || true)"
+if [ -z "$title_line" ]; then
+  note "no 'title:' line found — cannot check title length"
+else
+  title_val="$(printf '%s' "$title_line" | sed -E 's/^[[:space:]]*[Tt][Ii][Tt][Ll][Ee][[:space:]]*:[[:space:]]*//; s/^["'\'']//; s/["'\''][[:space:]]*$//')"
+  tlen=${#title_val}
+  if [ "$tlen" -ge 50 ] && [ "$tlen" -le 60 ]; then
+    pass "title is $tlen chars (50-60 band)"
+  elif [ "$tlen" -ge 45 ] && [ "$tlen" -le 65 ]; then
+    note "title is $tlen chars (outside 50-60, inside 45-65 tolerance)"
+  else
+    bad "title is $tlen chars (target 50-60): \"$title_val\""
+  fi
+fi
+
+# --- 2. Meta description length ------------------------------------------
+meta_line="$(grep -i -m1 -E '^[[:space:]]*(meta_description|meta|description)[[:space:]]*:' "$TARGET" || true)"
+if [ -z "$meta_line" ]; then
+  note "no 'meta_description:' line found — cannot check meta length"
+else
+  meta_val="$(printf '%s' "$meta_line" | sed -E 's/^[[:space:]]*[A-Za-z_]+[[:space:]]*:[[:space:]]*//; s/^["'\'']//; s/["'\''][[:space:]]*$//')"
+  mlen=${#meta_val}
+  if [ "$mlen" -ge 140 ] && [ "$mlen" -le 160 ]; then
+    pass "meta description is $mlen chars (140-160 band)"
+  elif [ "$mlen" -ge 120 ] && [ "$mlen" -le 170 ]; then
+    note "meta description is $mlen chars (outside 140-160, inside 120-170 tolerance)"
+  else
+    bad "meta description is $mlen chars (target 140-160)"
+  fi
+fi
+
+# --- 3. Exactly one H1, at least two H2s ----------------------------------
+h1_count="$(grep -c -E '^# [^#]' "$TARGET" || true)"
+h2_count="$(grep -c -E '^## [^#]' "$TARGET" || true)"
+if [ "$h1_count" -eq 1 ]; then
+  pass "exactly one H1"
+else
+  bad "found $h1_count H1 headings (need exactly 1)"
+fi
+if [ "$h2_count" -ge 2 ]; then
+  pass "$h2_count H2 headings (>=2)"
+else
+  bad "found $h2_count H2 headings (need >=2)"
+fi
+
+# --- 4. JSON-LD present with Article/BlogPosting; FAQPage if FAQ exists ----
+has_jsonld=0
+grep -q -E 'application/ld\+json' "$TARGET" && has_jsonld=1
+grep -q -E '"@type"[[:space:]]*:[[:space:]]*"(Article|BlogPosting)"' "$TARGET" && has_jsonld=1
+if grep -q -E '"@type"[[:space:]]*:[[:space:]]*"(Article|BlogPosting)"' "$TARGET"; then
+  pass "JSON-LD has @type Article/BlogPosting"
+elif [ "$has_jsonld" -eq 1 ]; then
+  bad "JSON-LD block present but no @type Article/BlogPosting"
+else
+  bad "no JSON-LD block with @type Article/BlogPosting found"
+fi
+
+# FAQ section present? (English / Catalan / Spanish heading)
+if grep -q -i -E '^#{1,3}[[:space:]].*(faq|preguntes|preguntas|frequently asked)' "$TARGET"; then
+  if grep -q -E '"@type"[[:space:]]*:[[:space:]]*"FAQPage"' "$TARGET"; then
+    pass "FAQ section has matching FAQPage JSON-LD"
+  else
+    bad "FAQ section present but no FAQPage JSON-LD"
+  fi
+fi
+
+# --- 5. At least one internal-link slot (relative / site path) ------------
+# Markdown link whose target is not an absolute external http(s) URL.
+if grep -q -E '\]\((/|\.{1,2}/|#)[^)]*\)' "$TARGET"; then
+  pass "internal-link slot present"
+else
+  note "no internal-link slot found (target 3-5 contextual internal links)"
+fi
+
+# --- 6. AI-tell / fluff banlist scan -------------------------------------
+if [ ! -f "$BANLIST_FILE" ]; then
+  note "banlist file not found at $BANLIST_FILE — skipping phrase scan"
+else
+  # Extract the fenced ```text BANLIST block: lines between the first
+  # ```text after the '## BANLIST' header and the next ``` fence.
+  banlist="$(awk '
+    /^## BANLIST/      { insec=1; next }
+    insec && /^```text/ { infence=1; next }
+    infence && /^```/   { infence=0; insec=0; next }
+    infence            { print }
+  ' "$BANLIST_FILE")"
+
+  hits=0
+  while IFS= read -r phrase; do
+    [ -z "$phrase" ] && continue
+    # strip a trailing comma-only token nuance; match literal, case-insensitive
+    if matches="$(grep -i -n -F -- "$phrase" "$TARGET")"; then
+      while IFS= read -r m; do
+        [ -z "$m" ] && continue
+        printf 'BANNED  "%s"  -> %s\n' "$phrase" "$m"
+        hits=$((hits + 1))
+      done <<< "$matches"
+    fi
+  done <<< "$banlist"
+
+  if [ "$hits" -eq 0 ]; then
+    pass "banlist scan clean (0 matches)"
+  else
+    bad "banlist scan found $hits AI-tell/fluff match(es) — rewrite the lines above"
+  fi
+fi
+
+# --- Summary --------------------------------------------------------------
+echo "---"
+if [ "$fail" -ne 0 ]; then
+  echo "verify.sh: FAIL (one or more hard checks failed)"
+  exit 1
+fi
+if [ "$warn" -ne 0 ]; then
+  echo "verify.sh: PASS with warnings"
+else
+  echo "verify.sh: PASS"
+fi
+exit 0

package/skills/astro/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: astro
+description: "Use when building a content-driven or marketing site with Astro 6: static-first pages, islands and partial hydration, content collections, server islands, per-route on-demand rendering, deploy adapters, and Astro 5→6 migration. NOT app-router React with server actions and heavy client interactivity (that is `nextjs`)."
+tags: [astro, ssg, islands, content-collections, partial-hydration, marketing-site, frameworks]
+recommends: [landing-copy, seo-geo, vercel, cloudflare, netlify]
+origin: risco
+---
+
+# Astro 6 — static-first sites, islands, content collections
+
+## The prime directive
+
+**Ship zero client JavaScript by default. Hydrate the smallest possible surface, as late as you can
+get away with.** An `.astro` component renders to HTML at build time and ships *no* runtime; every
+island is a bundle the visitor downloads, parses, and executes. Content and marketing sites win on
+TTFB/LCP and Lighthouse, not on React-everywhere. If you find yourself adding `client:load` to make
+a page "work," stop — the page already works; you are adding interactivity, and interactivity is the
+expensive exception, not the default.
+
+## First: detect the project version
+
+Astro 6.0 is stable ([released 2026-03-10](https://astro.build/blog/astro-6/)); the Astro 5 line is
+still production-ready. Do not mix advice across majors — read `package.json` → the `astro` version
+before advising. What v6 changes, per the
+[upgrade-to-v6 guide](https://docs.astro.build/en/guides/upgrade-to/v6/):
+
+- **Node `22.12.0` or higher is required** (18 and 20 are dropped) — check the actual runtime.
+- Content config lives at `src/content.config.ts`. The legacy `src/content/config.ts` path is
+  **removed**, not merely discouraged, and the old auto-detection (`legacy.collections`) is gone.
+  The `legacy.collectionsBackwardsCompat` escape hatch is a migration crutch, not a supported layout.
+- **Vite 7** and **Zod 4** for content schemas — `z` is imported from `astro/zod`, **not**
+  `astro:content` (see Content collections below).
+- **Live Content Collections**, the **Fonts API** and the **CSP API** are stable.
+- The Rust compiler succeeding the Go one is *experimental* — do not rely on or configure it in
+  production advice.
+
+## Decision table — what kind of thing is this?
+
+Pick the cheapest row that satisfies the requirement. Read top-down; stop at the first match.
+
+| Need                                                   | Use                                      | Why                                                        |
+| ------------------------------------------------------ | ---------------------------------------- | ---------------------------------------------------------- |
+| Pure content, no interactivity                         | `.astro` component, static               | Renders to HTML at build, ships **0 KB** JS                |
+| One small interactive widget                           | UI-framework component + `client:*`      | Hydrate just that island; the rest stays static            |
+| Per-request personalization on a mostly-static page    | server island (`server:defer`)           | Static CDN page + one deferred fragment, no full SSR       |
+| Whole route needs request data on every load           | `export const prerender = false` + adapter | Opt that one route into on-demand rendering              |
+| Many static routes generated from data                 | `getStaticPaths()`                       | Build-time fan-out, still fully static                     |
+
+## Rendering model
+
+Default: **every page is prerendered to static HTML** at build time. You opt *into* dynamism per
+route — never the other way around.
+
+```astro
+---
+// src/pages/dashboard.astro — opt this ONE route into on-demand (SSR) rendering.
+// Requires a configured adapter (Vercel/Netlify/Cloudflare/Node). Everything else stays static.
+export const prerender = false;
+const user = await getUser(Astro.request); // runs per request
+---
+<h1>Hello {user.name}</h1>
+```
+
+```astro
+---
+// src/pages/blog/[slug].astro — many STATIC routes generated from data at build time.
+import { getCollection } from "astro:content";
+
+export async function getStaticPaths() {
+  const posts = await getCollection("blog");
+  return posts.map((post) => ({ params: { slug: post.id }, props: { post } }));
+}
+const { post } = Astro.props;
+---
+<h1>{post.data.title}</h1>
+```
+
+In Astro 6 the dev server runs the **production runtime** (Vite 7 Environment API), so dev no longer
+diverges from prod on Cloudflare/Bun/Deno — fewer "works in dev, breaks on deploy" surprises. Adapter
+choice per platform → `references/deploy-and-integrations.md`.
+
+## Islands & client directives
+
+A `client:*` directive turns a framework component into a hydrated island. Choose the **latest**
+directive that still feels instant to the user — never default to `client:load`.
+
+| Directive               | Hydrates when                       | Use for                                              |
+| ----------------------- | ----------------------------------- | ---------------------------------------------------- |
+| `client:load`           | Immediately on page load            | Above-the-fold, must-be-interactive-now controls     |
+| `client:idle`           | On `requestIdleCallback`            | Important but not first-paint-critical widgets       |
+| `client:visible`        | When it scrolls into view (IO)      | Below-the-fold carousels, comment boxes, maps        |
+| `client:media={query}`  | When a media query matches          | Mobile-only menu, desktop-only panel                 |
+| `client:only="react"`   | Client-only, **no SSR HTML**        | Components that crash during SSR (browser-only deps)  |
+
+```astro
+---
+import Carousel from "../components/Carousel.tsx";
+---
+<!-- Bad: a below-the-fold carousel paying for JS at first paint -->
+<Carousel client:load />
+
+<!-- Good: defer its bundle until the user actually scrolls to it -->
+<Carousel client:visible />
+```
+
+`client:only` gotcha: it **skips SSR entirely**, so the component produces no server HTML (expect a
+flash/layout shift) and you **must** name the framework (`client:only="react"`) — Astro can't infer
+it without the server render. Reach for it only when SSR genuinely breaks; otherwise prefer
+`client:visible`.
+
+## Content collections (Content Layer)
+
+Type-safe content lives in a single config file. The path is load-bearing:
+
+```typescript
+// src/content.config.ts  ← v6 path. NOT src/content/config.ts (legacy path removed in v6)
+import { defineCollection } from "astro:content";
+import { z } from "astro/zod"; // v6: z moved OUT of astro:content into astro/zod (Zod 4)
+import { glob } from "astro/loaders";
+
+const blog = defineCollection({
+  // glob() sources files from anywhere; `id` comes from the filename minus extension
+  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/data/blog" }),
+  schema: z.object({
+    title: z.string(),
+    pubDate: z.coerce.date(),
+    draft: z.boolean().default(false),
+    tags: z.array(z.string()).default([]),
+  }),
+});
+
+export const collections = { blog };
+```
+
+Query and render in a page. `render()` is now a standalone call (not `entry.render()`):
+
+```astro
+---
+// src/pages/blog/[slug].astro
+import { getCollection, getEntry, render } from "astro:content";
+
+export async function getStaticPaths() {
+  const posts = await getCollection("blog", ({ data }) => !data.draft);
+  return posts.map((post) => ({ params: { slug: post.id }, props: { post } }));
+}
+const { post } = Astro.props;
+const { Content } = await render(post);
+---
+<article><h1>{post.data.title}</h1><Content /></article>
+```
+
+Built-in loaders are `glob()` (many files) and `file()` (one JSON/YAML array). Custom and CMS
+loaders, Zod 4 schema patterns, collection references, Live Content Collections (real-time data with
+no rebuild, stable in v6), querying and MDX details → `references/content-layer.md`.
+
+## Server islands
+
+When most of a page is static and CDN-cacheable but **one fragment** is per-visitor, use a server
+island instead of turning the whole route into SSR. The page ships static; the island is fetched
+and rendered after first paint.
+
+```astro
+---
+// src/components/UserGreeting.astro — rendered on demand, deferred after the static shell
+const user = await getUserFromCookie(Astro.request);
+---
+<span>Welcome back, {user.name}</span>
+```
+
+```astro
+---
+import UserGreeting from "../components/UserGreeting.astro";
+---
+<header>
+  <!-- static page, one deferred personalized fragment with a placeholder while it loads -->
+  <UserGreeting server:defer>
+    <span slot="fallback">Welcome</span>
+  </UserGreeting>
+</header>
+```
+
+This beats full SSR when: the page is otherwise cacheable on a CDN, and only a small slice depends on
+the request. You keep static LCP and personalize without making every request hit the origin.
+
+## Integrations & setup
+
+Use `astro add` so it patches `astro.config.mjs` and installs peers in one step:
+
+```bash
+npx astro add react mdx sitemap
+```
+
+- **Tailwind 4** wires through the official **Vite plugin** (`@tailwindcss/vite`), not the legacy
+  `@astrojs/tailwind` integration (that path was for Tailwind 3).
+- **Fonts API** (stable in v6) self-hosts and optimizes fonts from `astro.config.mjs` — no manual
+  `@font-face`.
+- **CSP API** (stable in v6) emits a Content-Security-Policy with hashes for your inline
+  scripts/styles.
+
+Adapter recipes per platform, hybrid rendering, env handling, SSR endpoints (`src/pages/api/*.ts`)
+and the Fonts/CSP config → `references/deploy-and-integrations.md`.
+
+## Performance rules
+
+- Images: always `<Image>`/`<Picture>` from `astro:assets` — automatic width/height, format, and
+  lazy-loading kill CLS and over-sized payloads. Never a raw `<img>` for local assets.
+- Never global-hydrate: there is no "make the page interactive" switch; hydrate per island.
+- View transitions: add `<ClientRouter />` from `astro:transitions` to the `<head>` for SPA-like
+  navigation without an SPA. Prefetch links with the `prefetch` config/attribute.
+
+## Astro 5 → 6 migration checklist
+
+Run the codemod first, then verify each item:
+
+```bash
+npx @astrojs/upgrade
+```
+
+- [ ] Node runtime is **`22.12.0`+** (CI image, local, deploy target).
+- [ ] Dependencies on **Vite 7** (Vite v7.0; custom Vite plugins/config may need updates).
+- [ ] Schema `z` import moved: **`import { z } from "astro/zod"`** — `z` and `astro:schema` are gone
+      from `astro:content`. Then review for **Zod 4** breaking changes.
+- [ ] Content config renamed to **`src/content.config.ts`** (delete `src/content/config.ts`; the
+      legacy path is removed, not just deprecated).
+- [ ] Full guide (dated 2026): `docs.astro.build/en/guides/upgrade-to/v6`.
+
+## Anti-patterns
+
+| Anti-pattern                                             | Reality                                                                     |
+| -------------------------------------------------------- | --------------------------------------------------------------------------- |
+| "Add `client:load` so the page works"                    | An `.astro` page already works statically; you're shipping JS for nothing   |
+| "`client:load` everywhere, simplest"                     | Pick `client:visible`/`idle`/`media`; first-paint JS is the LCP killer       |
+| "Make the whole route SSR to personalize the header"     | Use a server island (`server:defer`); keep the page static & CDN-cached     |
+| "`src/content/config.ts` worked before, keep it"         | v6 removed that path (LegacyContentConfigError) — must be `src/content.config.ts` |
+| "`fetch()` the CMS inside the `.astro` frontmatter"      | Write a content-collection loader so content is typed, cached, and queryable |
+| "Pull in React just to render this static markup"        | Static markup is an `.astro` component — 0 KB, no framework runtime          |
+| "Skip the Zod schema, content is just frontmatter"       | Untyped content = silent build-time drift; the schema is the contract        |
+| "`client:only` without the framework name"               | It can't infer the framework with no SSR — must be `client:only="react"`     |
+| "Use the old `@astrojs/tailwind` for Tailwind 4"         | Tailwind 4 wires through `@tailwindcss/vite`; the old integration is v3-era  |
+
+## Verify
+
+`bash scripts/verify.sh` from the Astro project root — grep-based, needs no install. It **FAILS** if
+a v6 project still has `src/content/config.ts` instead of `src/content.config.ts`, **WARNS** on
+over-hydration smells (many `client:load`, or `client:only` with no framework string), **CHECKS**
+that content schemas import from `astro:content`, and — only if the `astro` binary resolves —
+optionally runs `npx astro check`. On an empty or clean tree it prints OK and exits 0; warnings are
+advisory and never fail the run.
+
+## See Also
+
+- `../nextjs/SKILL.md` — when the project is really an app-router React app with server actions and
+  heavy client interactivity, not a content/marketing site.
+- `../landing-copy/SKILL.md` and `../seo-geo/SKILL.md` — this skill builds the site; those write the
+  copy and decide the SEO/structured-data strategy that fills it.
+- `../vercel/SKILL.md`, `../netlify/SKILL.md`, `../cloudflare/SKILL.md` — platform mechanics (DNS,
+  env, build settings) once the code and adapter are ready.

package/skills/astro/evals/README.md

@@ -0,0 +1,3 @@
+# astro evals
+
+Trigger and capability checks for Astro content and marketing sites.

package/skills/astro/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: astro
+
+should_trigger:
+  - prompt: "Build an Astro blog with content collections."
+    why: "Astro content collections and static-first pages are core to the skill."
+  - prompt: "Make this widget hydrate only when it scrolls into view in Astro."
+    why: "Partial hydration/client directives are Astro-specific."
+  - prompt: "Use a server island to personalize a static Astro page."
+    why: "Server islands and static-plus-dynamic composition belong here."
+  - prompt: "Migrate this project from Astro 5 to Astro 6."
+    why: "Astro version migration and v6 content config are skill-specific."
+  - prompt: "Quiero una web de marketing rapida con Astro y cero JS innecesario."
+    why: "Spanish marketing site with Astro and zero-JS directive triggers this skill."
+
+should_not_trigger:
+  - prompt: "Implement a Next.js server action with App Router."
+    route_to: "nextjs"
+    why: "Next.js RSC/App Router is not Astro."
+  - prompt: "Write conversion copy for this landing page."
+    route_to: "landing-copy"
+    why: "Copywriting belongs to landing-copy; Astro may implement it later."
+  - prompt: "Configure Cloudflare DNS and workers."
+    route_to: "cloudflare"
+    why: "Platform configuration is the Cloudflare skill."
+  - prompt: "Design the visual system for this marketing page."
+    route_to: "design"
+    why: "Visual design belongs to design."
+  - prompt: "Write the hooks and state logic for this React island."
+    route_to: "react"
+    why: "The component-internals (hooks/state) of a React island are React's job; Astro only decides whether and how the island hydrates (client:* directive), not its internal logic — the closest near-miss sibling."
+
+capability:
+  - scenario: "A user wants an Astro 6 marketing site with a static blog, one interactive pricing calculator, and per-request personalization."
+    must_include:
+      - "Keeps the default static/zero-client-JS model and hydrates only the calculator island."
+      - "Chooses the appropriate client directive such as client:visible/client:idle instead of client:load by habit."
+      - "Uses content collections for typed blog/content data."
+      - "Uses server islands or per-route on-demand rendering only for request-specific personalization."
+      - "Checks Astro major version and Node/runtime requirements before giving migration advice."
+      - "Routes copy, SEO, deploy-platform details to their matching skills when needed."
+      - "Explains that interactivity is the exception, not the default."

package/skills/astro/references/content-layer.md

@@ -0,0 +1,118 @@
+# Content Layer — loaders, schemas, querying
+
+The Content Layer (stable since Astro 5.0) sources content from anywhere through **loaders** and
+gives you type-safe, queryable collections. Config lives in `src/content.config.ts` (v6 path; the
+legacy `src/content/config.ts` location is removed in v6, per the
+[upgrade-to-v6 guide](https://docs.astro.build/en/guides/upgrade-to/v6/)).
+
+## defineCollection: loader + schema
+
+A collection is `defineCollection({ loader, schema })`. The loader produces entries; the schema (Zod
+4) validates and types their `data`.
+
+```typescript
+// src/content.config.ts
+import { defineCollection, reference } from "astro:content";
+import { z } from "astro/zod"; // v6: z is imported from astro/zod, not astro:content
+import { glob, file } from "astro/loaders";
+
+// glob() — many files, one entry per file. `id` = path minus base & extension.
+const blog = defineCollection({
+  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/data/blog" }),
+  schema: ({ image }) =>
+    z.object({
+      title: z.string(),
+      description: z.string().max(160),
+      pubDate: z.coerce.date(),
+      updated: z.coerce.date().optional(),
+      draft: z.boolean().default(false),
+      cover: image(), // astro:assets image, validated at build
+      author: reference("authors"), // cross-collection reference
+      tags: z.array(z.string()).default([]),
+    }),
+});
+
+// file() — ONE structured file (JSON/YAML) holding an array of entries.
+const authors = defineCollection({
+  loader: file("./src/data/authors.json"), // each object needs an `id`
+  schema: z.object({ id: z.string(), name: z.string(), url: z.string().url().optional() }),
+});
+
+export const collections = { blog, authors };
+```
+
+## Zod 4 notes (Astro 6)
+
+In Astro 6 you import `z` from **`astro/zod`** (it is **Zod 4**); `z` was removed from `astro:content`
+and the old `astro:schema` alias is gone — both consolidate into `astro/zod`. Source:
+[upgrade-to-v6 guide](https://docs.astro.build/en/guides/upgrade-to/v6/) and the
+[Astro 6.0 release post, 2026-03-10](https://astro.build/blog/astro-6/). When migrating from v5:
+
+- Replace `import { z } from "astro:content"` with `import { z } from "astro/zod"` (and any
+  `astro:schema` import likewise). `defineCollection`, `reference`, `getCollection`, etc. still come
+  from `astro:content`.
+- `z.coerce.date()` for ISO date strings in frontmatter — unchanged, still the right call.
+- Review any custom error-map / `.refine()` usage and string-format helpers; Zod 4 changed some
+  error shapes and deprecated a few v3 APIs. Run a build and read the validation errors.
+- `image()` (injected via the `({ image }) => ...` schema form) validates and optimizes local images
+  referenced in frontmatter.
+
+## Querying & rendering
+
+```astro
+---
+import { getCollection, getEntry, render } from "astro:content";
+
+// All non-draft posts, newest first
+const posts = (await getCollection("blog", ({ data }) => !data.draft))
+  .sort((a, b) => b.data.pubDate.getTime() - a.data.pubDate.getTime());
+
+// A single entry by id
+const post = await getEntry("blog", "hello-world");
+
+// Resolve a reference() to the full entry
+const author = post ? await getEntry(post.data.author) : undefined;
+
+// Render Markdown/MDX body to a component (standalone render(), not entry.render())
+const { Content, headings } = await render(posts[0]);
+---
+<h2>{author?.data.name}</h2>
+<Content />
+```
+
+## Custom & CMS loaders
+
+When content comes from an API/CMS rather than files, write an inline loader or use a community one
+(`@ascorbic/*`, Storyblok, Contentful, etc.). The contract: return an array of objects each with an
+`id`, validated by the same `schema`.
+
+```typescript
+// src/content.config.ts — minimal inline loader fetching from a headless CMS at build time
+const products = defineCollection({
+  loader: async () => {
+    const res = await fetch("https://cms.example.com/api/products");
+    const items = await res.json();
+    return items.map((p: any) => ({ id: String(p.id), ...p })); // each entry needs an `id`
+  },
+  schema: z.object({ id: z.string(), name: z.string(), price: z.number() }),
+});
+```
+
+For incremental/syncing loaders that cache between builds, implement the full loader object
+(`{ name, load(context) }`) and use `context.store` — see
+`docs.astro.build/en/reference/content-loader-reference`.
+
+## Live Content Collections (stable in Astro 6)
+
+Stable as of the [Astro 6.0 release, 2026-03-10](https://astro.build/blog/astro-6/). Live collections
+fetch **at request time** instead of build time, so data stays fresh without a rebuild — ideal for
+inventory, prices, or anything that changes between deploys on an otherwise static site. They use a
+separate `src/live.config.ts` and `getLiveCollection`/`getLiveEntry`. Use them only for genuinely
+live data; build-time `glob()`/`file()` collections stay faster and cacheable for everything stable.
+Reference: [Live Content Collections guide](https://docs.astro.build/en/guides/content-collections/).
+
+## MDX
+
+`npx astro add mdx` enables `.mdx` in the same `glob()` pattern. MDX lets a content file import and
+render components (including hydrated islands with `client:*`). Keep islands inside MDX rare and
+deferred for the same reason as everywhere else: they ship JS.