@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/api-design/references/versioning-and-evolution.md

@@ -0,0 +1,49 @@
+# Versioning & evolution
+
+Default posture: **evolve additively, version rarely.** A version is a fork of your client base — earn it.
+
+## Breaking vs non-breaking matrix
+
+| Change | Breaking? | Notes |
+|---|---|---|
+| Add a new optional response field | No | clients ignore unknown fields if you told them to |
+| Add a new endpoint | No | nothing existing changes |
+| Add a new optional query/body param | No | old requests still valid |
+| Add a new enum value | No* | *only if clients were told to tolerate unknown values; otherwise breaking |
+| Loosen a validation rule | No | previously-rejected input now accepted |
+| Remove or rename a field | **Yes** | clients reading it break |
+| Change a field's type or format | **Yes** | `string` → `object`, date format change, etc. |
+| Make an optional field required | **Yes** | old requests start failing |
+| Tighten validation (narrower accepted range) | **Yes** | previously-valid input now rejected |
+| Change a status code for a case | **Yes** | client branching breaks |
+| Change an error `type` URI for a case | **Yes** | clients branch on `type` |
+| Change pagination/cursor semantics | **Yes** | in-flight pagination breaks |
+
+Design hint: tell clients up front to **ignore unknown fields and tolerate unknown enum values** ("must-ignore" / robustness rule). That single contract clause turns many would-be breaking changes into additive ones.
+
+## Three versioning mechanisms
+
+| Mechanism | Example | Pros | Cons |
+|---|---|---|---|
+| **URL path** | `/v1/projects` | visible, cacheable, browser-testable, expected by most clients | version leaks into every URL; "v" is coarse-grained |
+| **Header / media type** | `Accept: application/vnd.acme.v2+json` | clean URLs, content-negotiated | harder to test/cache, easy to forget, opaque to humans |
+| **Query param** | `/projects?version=2` | trivial to add | pollutes URLs, easy to omit, muddies caching |
+
+**Default to URL path for public APIs.** Reserve header/media-type versioning for internal APIs where tooling controls the header. Don't mix mechanisms.
+
+## Deprecation & sunset workflow
+
+1. Ship the successor (new field/endpoint/version) additively.
+2. Mark the old surface deprecated in responses:
+
+```http
+Deprecation: true
+Sunset: Sat, 31 Oct 2026 23:59:59 GMT
+Link: <https://api.acme.com/v2/projects>; rel="successor-version"
+```
+
+3. Document the migration and the sunset date; notify known integrators.
+4. Hold the deprecated surface working until the `Sunset` date — give clients real time (months, not days, for public APIs).
+5. After sunset, return `410 Gone` for the removed surface (not `404`) so clients learn it was intentional.
+
+Keep the deprecation window generous and the messaging programmatic — clients should learn from headers, not from breakage.

package/skills/shared/api-design/scripts/verify.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# verify.sh — read-only check of an API-design artifact (OpenAPI 3.1 spec).
+#
+# The api-design skill emits its contract as an OpenAPI document. This script
+# finds candidate spec files under a target dir, validates they parse and carry
+# the required OpenAPI keys, and emits non-fatal warnings for the design
+# anti-patterns it can detect statically. It never writes anything.
+#
+# Usage:   verify.sh [TARGET_DIR]   (default: current directory)
+# Exit:    0  no spec found (soft-pass) OR all found specs valid
+#          1  a spec file is present but invalid/unparseable
+#
+# Soft-pass on a clean/empty target: a design may live only in a doc.
+
+set -uo pipefail
+
+TARGET="${1:-.}"
+fail=0
+
+note()  { printf '  - %s\n' "$1"; }
+warn()  { printf '  ! %s\n' "$1"; }
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify(api-design): target '$TARGET' is not a directory — nothing to check."
+  exit 0
+fi
+
+# Collect candidate OpenAPI files (read-only). Tolerate no matches.
+# Portable to bash 3.2 (macOS default): no mapfile; newline-delimited list.
+specs=()
+while IFS= read -r f; do
+  [ -n "$f" ] && specs+=("$f")
+done < <(
+  find "$TARGET" \
+    \( -name 'openapi.yaml' -o -name 'openapi.yml' -o -name 'openapi.json' \
+       -o -name '*.openapi.yaml' -o -name '*.openapi.yml' -o -name '*.openapi.json' \) \
+    -type f 2>/dev/null
+)
+
+if [ "${#specs[@]}" -eq 0 ]; then
+  echo "verify(api-design): no OpenAPI spec found under '$TARGET' — soft-pass (design may be in-doc only)."
+  exit 0
+fi
+
+# Choose a linter if available; else fall back to a structural check.
+LINTER=""
+if command -v redocly >/dev/null 2>&1; then
+  LINTER="redocly"
+elif command -v spectral >/dev/null 2>&1; then
+  LINTER="spectral"
+fi
+
+# Structural fallback: parse + required keys, using whatever is on PATH.
+parse_check() {
+  local f="$1"
+  case "$f" in
+    *.json)
+      if command -v jq >/dev/null 2>&1; then
+        jq -e 'has("openapi") and has("info") and has("paths")' "$f" >/dev/null 2>&1
+        return $?
+      fi
+      ;;
+    *.yaml|*.yml)
+      if command -v python3 >/dev/null 2>&1; then
+        python3 - "$f" <<'PY' >/dev/null 2>&1
+import sys
+try:
+    import yaml
+except Exception:
+    sys.exit(2)  # no yaml lib -> can't check, treat as inconclusive
+with open(sys.argv[1]) as fh:
+    d = yaml.safe_load(fh)
+sys.exit(0 if isinstance(d, dict) and all(k in d for k in ("openapi", "info", "paths")) else 1)
+PY
+        local rc=$?
+        [ "$rc" -eq 2 ] && return 3   # inconclusive
+        return $rc
+      fi
+      ;;
+  esac
+  return 3  # inconclusive: no suitable parser on PATH
+}
+
+# Static anti-pattern warnings (grep-based, never fatal).
+antipattern_scan() {
+  local f="$1"
+  if grep -Eiq '"?/[A-Za-z0-9_]*(get|create|update|delete|fetch|list)[A-Za-z0-9_]*"?[[:space:]]*:' "$f"; then
+    warn "verb-like path segment(s) detected — paths should be nouns; HTTP methods are the verbs."
+  fi
+  if grep -Eq '(/[A-Za-z0-9_/{}]*)+[[:space:]]*:' "$f" && ! grep -Eiq 'cursor|limit|offset|first|after|page' "$f"; then
+    warn "no pagination params (cursor/limit/offset) found — list endpoints should paginate."
+  fi
+  if ! grep -Eiq 'problem\+json|"4[0-9][0-9]"|default[[:space:]]*:' "$f"; then
+    warn "no 4xx / default error responses found — every operation should define an error response (RFC 9457)."
+  fi
+}
+
+echo "verify(api-design): checking ${#specs[@]} spec file(s) under '$TARGET'"
+[ -n "$LINTER" ] && echo "  using linter: $LINTER"
+
+for f in "${specs[@]}"; do
+  echo "* $f"
+  ok=1
+  if [ -n "$LINTER" ]; then
+    if [ "$LINTER" = "redocly" ]; then
+      redocly lint "$f" >/dev/null 2>&1 || ok=0
+    else
+      spectral lint "$f" >/dev/null 2>&1 || ok=0
+    fi
+    if [ "$ok" -eq 0 ]; then
+      # Linter unhappy: confirm with structural parse before failing hard.
+      parse_check "$f"; pc=$?
+      if [ "$pc" -eq 0 ]; then
+        warn "$LINTER reported issues but the spec parses and has required keys — review lint output."
+      else
+        note "spec is invalid per $LINTER."
+        fail=1
+        continue
+      fi
+    fi
+  else
+    parse_check "$f"; pc=$?
+    case "$pc" in
+      0) : ;;  # valid
+      3) warn "no parser on PATH (jq/python3+pyyaml) — skipped structural validation." ;;
+      *) note "spec does not parse or is missing required keys (openapi/info/paths)."; fail=1; continue ;;
+    esac
+  fi
+  antipattern_scan "$f"
+done
+
+if [ "$fail" -ne 0 ]; then
+  echo "verify(api-design): FAIL — one or more specs are invalid."
+  exit 1
+fi
+
+echo "verify(api-design): OK (warnings, if any, are advisory)."
+exit 0

package/skills/shared/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: ai-hub
+---
+
+# 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/shared/astro/evals/README.md

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

package/skills/shared/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 App Router / React Server Components 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/shared/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.