@grove-dev/astro 0.3.4 → 0.4.0

package/dist/lib/index.d.ts

@@ -23,4 +23,5 @@ export * from "./search.js";
 export * from "./scores.js";
 export * from "./taxonomy-counts.js";
 export * from "./display.js";
+export * from "./load-collections.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC"}

package/dist/lib/index.js

@@ -23,4 +23,5 @@ export * from "./search.js";
 export * from "./scores.js";
 export * from "./taxonomy-counts.js";
 export * from "./display.js";
+export * from "./load-collections.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC"}

package/dist/lib/load-collections.d.ts

@@ -0,0 +1,12 @@
+import type { Collection } from "@grove-dev/core";
+/**
+ * Load all `Collection` YAML files from `<cwd>/data/collections/*.yml`.
+ *
+ * Returns an empty array if the directory does not exist, so callers can
+ * safely render an empty/loading state without having to guard each
+ * invocation site. Parse errors and other unexpected failures are NOT
+ * swallowed — they surface so real problems (malformed YAML, permission
+ * errors, etc.) are visible instead of silently producing empty output.
+ */
+export declare function loadCollections(cwd: string): Promise<Collection[]>;
+//# sourceMappingURL=load-collections.d.ts.map

package/dist/lib/load-collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-collections.d.ts","sourceRoot":"","sources":["../../src/lib/load-collections.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAkBxE"}

package/dist/lib/load-collections.js

@@ -0,0 +1,34 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+/**
+ * Load all `Collection` YAML files from `<cwd>/data/collections/*.yml`.
+ *
+ * Returns an empty array if the directory does not exist, so callers can
+ * safely render an empty/loading state without having to guard each
+ * invocation site. Parse errors and other unexpected failures are NOT
+ * swallowed — they surface so real problems (malformed YAML, permission
+ * errors, etc.) are visible instead of silently producing empty output.
+ */
+export async function loadCollections(cwd) {
+    const dir = resolve(cwd, "data/collections");
+    let files;
+    try {
+        files = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const f of files.filter((f) => f.endsWith(".yml"))) {
+        const raw = parseYaml(await readFile(join(dir, f), "utf8"));
+        if (!raw || typeof raw !== "object") {
+            throw new Error(`Invalid collection YAML: ${f}`);
+        }
+        out.push(raw);
+    }
+    return out;
+}
+//# sourceMappingURL=load-collections.js.map

package/dist/lib/load-collections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-collections.js","sourceRoot":"","sources":["../../src/lib/load-collections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAG1C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW;IAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;IAC7C,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAChE,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QACxD,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC5D,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,EAAE,CAAC,CAAC;QACnD,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,GAAiB,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grove-dev/astro",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "type": "module",
   "description": "Composable Astro UI, data adapters, and integration for Grove directories.",
   "license": "MIT",
@@ -54,7 +54,8 @@
     "astro": "^7.1.3",
     "marked": "^18.0.0",
     "sanitize-html": "^2.17.5",
-    "@grove-dev/core": "0.3.4"
+    "yaml": "^2.9.0",
+    "@grove-dev/core": "0.4.0"
   },
   "peerDependencies": {
     "astro": "^6.0.0 || ^7.0.0"

package/src/components/CollectionIndex.astro

@@ -0,0 +1,72 @@
+---
+/**
+ * CollectionIndex — renders a grid of every collection defined in
+ * `data/collections/*.yml`. Each card links to the collection's
+ * detail page and shows the entry count.
+ *
+ * Consumes a `CollectionIndexModel` produced by
+ * `getCollectionIndexModel`. Generic: no blueprint-specific copy.
+ */
+import Container from "../layouts/Container.astro";
+import type { CollectionIndexModel } from "../server/collections.js";
+
+interface Props {
+  model: CollectionIndexModel;
+  title?: string;
+  description?: string;
+  class?: string;
+}
+
+const {
+  model,
+  title = "Collections",
+  description = "Curated and generated directories of related items.",
+  class: className = "",
+} = Astro.props;
+---
+
+<section class={`py-12 sm:py-16 ${className}`}>
+  <Container>
+    <header class="mb-6">
+      <span class="text-2xs font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">
+        Browse
+      </span>
+      <h1 class="m-0 mt-1 text-[1.875rem] sm:text-[2.125rem] font-semibold tracking-tight text-ink-900 dark:text-ink-100">
+        {title}
+      </h1>
+      <p class="m-0 mt-2 max-w-[64ch] text-[0.9375rem] text-ink-500 dark:text-ink-400">
+        {description}
+      </p>
+    </header>
+
+    {model.collections.length === 0 ? (
+      <p class="rounded-md border border-dashed border-ink-200 bg-white p-6 text-sm text-ink-500 dark:border-ink-800 dark:bg-ink-950 dark:text-ink-400">
+        No collections yet.
+      </p>
+    ) : (
+      <ul class="m-0 grid list-none grid-cols-1 gap-3 p-0 sm:grid-cols-2 lg:grid-cols-3">
+        {model.collections.map((c) => (
+          <li class="m-0 p-0">
+            <a
+              href={c.url}
+              class="flex h-full flex-col gap-2 rounded-md border border-ink-200 bg-white p-5 transition-colors hover:border-ink-400 dark:border-ink-800 dark:bg-ink-950 dark:hover:border-ink-600"
+            >
+              <span class="text-2xs font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">
+                {c.kind === "curated" ? "Curated" : "Generated"}
+              </span>
+              <span class="text-[1.0625rem] font-semibold tracking-tight text-ink-900 dark:text-ink-100">
+                {c.title}
+              </span>
+              <span class="text-[0.875rem] text-ink-500 dark:text-ink-400">
+                {c.description}
+              </span>
+              <span class="mt-auto pt-2 text-2xs font-medium text-ink-500 dark:text-ink-400">
+                {c.count} {c.count === 1 ? "item" : "items"} →
+              </span>
+            </a>
+          </li>
+        ))}
+      </ul>
+    )}
+  </Container>
+</section>

package/src/components/CollectionPage.astro

@@ -0,0 +1,89 @@
+---
+/**
+ * CollectionPage — renders a single curated/generated collection.
+ *
+ * Consumes a `CollectionPageModel` produced by `getCollectionPageModel`.
+ * Renders the header (title, description, editorial notes), the
+ * matched entries via `CollectionRow`, and a related-collections
+ * section.
+ *
+ * Generic: no blueprint-specific copy. The `eyebrow` prop lets the
+ * consumer pick a label (e.g. "Curated" or "Generated").
+ */
+import CollectionRow from "./CollectionRow.astro";
+import Container from "../layouts/Container.astro";
+import type { CollectionPageModel } from "../server/collections.js";
+
+interface Props {
+  model: CollectionPageModel;
+  eyebrow?: string;
+  class?: string;
+}
+
+const {
+  model,
+  eyebrow = "Collection",
+  class: className = "",
+} = Astro.props;
+---
+
+<section class={`py-12 sm:py-16 ${className}`}>
+  <Container>
+    <header class="mb-6">
+      <span class="text-2xs font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">
+        {eyebrow}
+      </span>
+      <h1 class="m-0 mt-1 text-[1.875rem] sm:text-[2.125rem] font-semibold tracking-tight text-ink-900 dark:text-ink-100">
+        {model.collection.title}
+      </h1>
+      <p class="m-0 mt-2 max-w-[64ch] text-[0.9375rem] text-ink-500 dark:text-ink-400">
+        {model.collection.description}
+      </p>
+      {model.collection.introduction && (
+        <p class="m-0 mt-3 max-w-[64ch] text-[0.9375rem] text-ink-700 dark:text-ink-300">
+          {model.collection.introduction}
+        </p>
+      )}
+      {model.collection.selectionNote && (
+        <p class="m-0 mt-3 max-w-[64ch] text-[0.875rem] font-medium text-ink-700 dark:text-ink-300">
+          <span class="text-2xs font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">Selection criteria · </span>
+          {model.collection.selectionNote}
+        </p>
+      )}
+    </header>
+
+    {model.isEmpty ? (
+      <p class="rounded-md border border-dashed border-ink-200 bg-white p-6 text-sm text-ink-500 dark:border-ink-800 dark:bg-ink-950 dark:text-ink-400">
+        This collection is currently empty.
+      </p>
+    ) : (
+      <ul class="m-0 flex list-none flex-col gap-3 p-0">
+        {model.entries.map((entry, i) => (
+          <li class="m-0 p-0">
+            <CollectionRow entry={entry} eager={i < 2} />
+          </li>
+        ))}
+      </ul>
+    )}
+
+    {model.related.length > 0 && (
+      <section class="mt-12 border-t border-ink-200 pt-8 dark:border-ink-800">
+        <h2 class="m-0 text-[1.125rem] font-semibold tracking-tight text-ink-900 dark:text-ink-100">
+          Related collections
+        </h2>
+        <ul class="m-0 mt-3 flex list-none flex-col gap-2 p-0">
+          {model.related.map((r) => (
+            <li>
+              <a
+                href={r.url}
+                class="text-sm text-ink-700 transition-colors hover:text-ink-900 dark:text-ink-300 dark:hover:text-ink-100"
+              >
+                {r.title} →
+              </a>
+            </li>
+          ))}
+        </ul>
+      </section>
+    )}
+  </Container>
+</section>

package/src/components/CollectionRow.astro

@@ -0,0 +1,109 @@
+---
+/**
+ * CollectionRow — a single entry inside a curated/generated collection.
+ *
+ * Mirrors `IndexRow`'s visual rhythm (avatar, header, description, dl
+ * stats, footer links) but consumes the lighter `CollectionEntry`
+ * shape directly. The existing `IndexRow` is tightly coupled to
+ * `IndexRecord` (which carries `kind`, `repoUrl`, `github`, `bestFor`,
+ * etc.) — collections only have a subset of those fields, so a
+ * dedicated row keeps the contract clean.
+ *
+ * Generic: no blueprint-specific copy. Visual style mirrors IndexRow
+ * so a collection page sitting next to the directory index reads as
+ * the same site.
+ */
+import type { CollectionEntry } from "@grove-dev/core";
+import { formatStars, formatRelative } from "@grove-dev/astro";
+
+interface Props {
+  entry: CollectionEntry;
+  eager?: boolean;
+  class?: string;
+}
+
+const { entry, eager = false, class: className = "" } = Astro.props;
+
+const initials = entry.title
+  .split(/\s+/)
+  .map((word) => word[0])
+  .filter(Boolean)
+  .slice(0, 2)
+  .join("")
+  .toUpperCase();
+const stack = entry.stack ?? "—";
+const stars = entry.stars ?? null;
+const pushedAt = entry.pushedAt ?? null;
+const category = entry.categories?.[0];
+---
+
+<article
+  class={`rounded-[calc(var(--radius)+0.25rem)] border border-ink-200 bg-white shadow-none transition-colors hover:bg-secondary dark:border-ink-800 dark:bg-ink-950 dark:hover:bg-ink-900 group relative flex flex-col gap-3 p-4 ${className}`}
+>
+  <header class="flex items-start gap-3">
+    <a
+      href={entry.url}
+      class="relative z-10 flex shrink-0"
+      aria-label={`Open ${entry.title} details`}
+    >
+      <span class="flex h-11 w-11 items-center justify-center rounded-md border border-ink-200 bg-ink-50 text-sm font-semibold text-ink-700 dark:border-ink-800 dark:bg-ink-900/60 dark:text-ink-300">
+        {initials || "·"}
+      </span>
+    </a>
+    <div class="min-w-0 flex-1">
+      <div class="flex flex-wrap items-baseline gap-x-2 gap-y-0.5">
+        <h3 class="m-0 text-[1.0625rem] font-semibold tracking-tight text-ink-900 dark:text-ink-100">
+          <a href={entry.url} class="relative z-10 hover:underline">{entry.title}</a>
+        </h3>
+        {category && (
+          <span class="text-2xs font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">
+            {category}
+          </span>
+        )}
+      </div>
+      <div class="flex flex-wrap items-center gap-x-1.5 text-2xs text-ink-500 dark:text-ink-400">
+        <span class="font-mono">{stack}</span>
+        {entry.platform?.length ? (
+          <>
+            <span class="text-ink-300 dark:text-ink-700">·</span>
+            <span>{entry.platform.slice(0, 3).join(", ")}</span>
+          </>
+        ) : null}
+        {entry.license ? (
+          <>
+            <span class="text-ink-300 dark:text-ink-700">·</span>
+            <span>{entry.license}</span>
+          </>
+        ) : null}
+      </div>
+    </div>
+  </header>
+
+  <p class="m-0 line-clamp-2 text-[0.8125rem] leading-relaxed text-ink-600 dark:text-ink-300">
+    {entry.description}
+  </p>
+
+  <dl class="grid grid-cols-3 gap-x-3 text-2xs">
+    <div class="flex items-baseline gap-1.5">
+      <dt class="font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">Stars</dt>
+      <dd class="font-mono text-ink-700 dark:text-ink-300">{formatStars(stars) ?? "—"}</dd>
+    </div>
+    <div class="flex items-baseline gap-1.5">
+      <dt class="font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">Updated</dt>
+      <dd class="font-mono text-ink-700 dark:text-ink-300">{formatRelative(pushedAt) ?? "—"}</dd>
+    </div>
+    <div class="flex items-baseline gap-1.5">
+      <dt class="font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">License</dt>
+      <dd class="font-mono text-ink-700 dark:text-ink-300">{entry.license ?? "—"}</dd>
+    </div>
+  </dl>
+
+  <footer class="relative z-10 mt-1 flex items-center gap-2 border-t border-ink-100 pt-2 text-2xs dark:border-ink-900">
+    <a
+      href={entry.url}
+      class="inline-flex h-8 cursor-pointer items-center justify-center gap-1.5 rounded-[var(--radius)] border border-transparent px-3 text-sm font-medium leading-none no-underline outline-none transition-colors focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/35 border-border bg-secondary text-foreground hover:bg-accent px-2 text-2xs"
+    >
+      View details →
+    </a>
+  </footer>
+</article>

package/src/components/CollectionTeaser.astro

@@ -0,0 +1,81 @@
+---
+/**
+ * CollectionTeaser — homepage-friendly subset of `CollectionIndex`.
+ * Renders a horizontal grid of 2-3 collection cards with a "View all"
+ * link in the header. Generic: no blueprint copy.
+ */
+import Container from "../layouts/Container.astro";
+import type { CollectionTeaserModel } from "../server/collections.js";
+
+interface Props {
+  model: CollectionTeaserModel;
+  title?: string;
+  description?: string;
+  viewAllHref?: string;
+  viewAllLabel?: string;
+  class?: string;
+}
+
+const {
+  model,
+  title = "Featured collections",
+  description = "Hand-picked and auto-generated groupings of related items.",
+  viewAllHref = "/collections/",
+  viewAllLabel = "View all collections",
+  class: className = "",
+} = Astro.props;
+---
+
+<section class={`py-12 sm:py-16 ${className}`}>
+  <Container>
+    <div class="mb-6 flex flex-wrap items-end justify-between gap-3">
+      <div>
+        <span class="text-2xs font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">
+          Collections
+        </span>
+        <h2 class="m-0 mt-1 text-[1.5rem] sm:text-[1.625rem] font-semibold tracking-tight text-ink-900 dark:text-ink-100">
+          {title}
+        </h2>
+        <p class="m-0 mt-2 max-w-[60ch] text-[0.9375rem] text-ink-500 dark:text-ink-400">
+          {description}
+        </p>
+      </div>
+      {viewAllHref && (
+        <a
+          href={viewAllHref}
+          class="hidden shrink-0 pb-2 text-2xs font-medium text-ink-500 transition-colors hover:text-ink-900 sm:inline dark:text-ink-400 dark:hover:text-ink-100"
+        >
+          {viewAllLabel} →
+        </a>
+      )}
+    </div>
+
+    {model.collections.length === 0 ? (
+      <p class="m-0 text-sm text-ink-500 dark:text-ink-400">
+        No collections yet.
+      </p>
+    ) : (
+      <div class="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
+        {model.collections.map((c) => (
+          <a
+            href={c.url}
+            class="flex flex-col gap-2 rounded-md border border-ink-200 bg-white p-5 transition-colors hover:border-ink-400 dark:border-ink-800 dark:bg-ink-950 dark:hover:border-ink-600"
+          >
+            <span class="text-2xs font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">
+              {c.kind === "curated" ? "Curated" : "Generated"}
+            </span>
+            <span class="text-[1.0625rem] font-semibold tracking-tight text-ink-900 dark:text-ink-100">
+              {c.title}
+            </span>
+            <span class="text-[0.875rem] text-ink-500 dark:text-ink-400">
+              {c.description}
+            </span>
+            <span class="mt-auto pt-2 text-2xs font-medium text-ink-500 dark:text-ink-400">
+              {c.count} {c.count === 1 ? "item" : "items"} →
+            </span>
+          </a>
+        ))}
+      </div>
+    )}
+  </Container>
+</section>

package/src/components/CurationGrid.astro

@@ -27,9 +27,9 @@ const columns = [
   >
     {columns.map((column) => (
       <div class="rounded-[calc(var(--radius)+0.25rem)] border-0 bg-muted shadow-none transition-colors p-5">
-        <h3 class="m-0 text-sm font-semibold uppercase tracking-wider text-ink-500 dark:text-ink-400">
+        <h2 class="m-0 text-sm font-semibold uppercase tracking-wider text-ink-500 dark:text-ink-400">
           {column.title}
-        </h3>
+        </h2>
         <ul class="mt-3 mb-0 flex list-disc flex-col gap-1.5 pl-5">
           {column.items.map((item) => (
             <li class="text-sm text-ink-700 dark:text-ink-200">{item}</li>

package/src/components/GroveDocumentHead.astro

@@ -0,0 +1,28 @@
+---
+import type { PageDocument } from "@grove-dev/core";
+interface Props {
+  document: PageDocument;
+}
+const { document: doc } = Astro.props;
+---
+<title>{doc.metadata.title}</title>
+<meta name="description" content={doc.metadata.description} />
+<meta name="robots" content={doc.metadata.robots} />
+<link rel="canonical" href={doc.identity.canonical.toString()} />
+{doc.identity.hreflang?.map((lang) => (
+  <link rel="alternate" hreflang={lang} href={doc.identity.canonical.toString()} />
+))}
+<meta property="og:title" content={doc.metadata.openGraph.title} />
+<meta property="og:description" content={doc.metadata.openGraph.description} />
+<meta property="og:url" content={doc.metadata.openGraph.url} />
+<meta property="og:image" content={doc.metadata.openGraph.image} />
+<meta property="og:type" content={doc.metadata.openGraph.type} />
+{doc.metadata.openGraph.siteName && (
+  <meta property="og:site_name" content={doc.metadata.openGraph.siteName} />
+)}
+<meta name="twitter:card" content={doc.metadata.twitter.card} />
+{doc.metadata.twitter.site && <meta name="twitter:site" content={doc.metadata.twitter.site} />}
+{doc.metadata.twitter.creator && <meta name="twitter:creator" content={doc.metadata.twitter.creator} />}
+{doc.structuredData.map((node) => (
+  <script type="application/ld+json" set:html={JSON.stringify(node)} />
+))}

package/src/components/Hero.astro

@@ -230,7 +230,6 @@ const trustStats: { value: string; label: string }[] = [
       {quickFilters.length > 0 && (
         <p
           class="mt-2 text-2xs text-ink-500 dark:text-ink-400 m-0"
-          aria-hidden="true"
         >
           Try{" "}
           {quickFilters.map((f, i) => (

package/src/components/IndexRow.astro

@@ -69,9 +69,9 @@ const curated = Boolean(item.curation?.reviewed || (project && (project.bestFor.
   <p class="m-0 line-clamp-2 text-[0.8125rem] leading-relaxed text-ink-600 dark:text-ink-300">{item.description}</p>
 
   <dl class="grid grid-cols-3 gap-x-3 text-2xs">
-    <div class="flex items-baseline gap-1.5"><dt class="font-medium uppercase tracking-wider text-ink-500">Stars</dt><dd class="font-mono text-ink-700 dark:text-ink-300">{formatStars(stars) ?? "—"}</dd></div>
-    <div class="flex items-baseline gap-1.5"><dt class="font-medium uppercase tracking-wider text-ink-500">Updated</dt><dd class="font-mono text-ink-700 dark:text-ink-300">{formatRelative(updatedAt)}</dd></div>
-    <div class="flex items-baseline gap-1.5"><dt class="font-medium uppercase tracking-wider text-ink-500">License</dt><dd class="font-mono text-ink-700 dark:text-ink-300">{license ?? "—"}</dd></div>
+    <div class="flex items-baseline gap-1.5"><dt class="font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">Stars</dt><dd class="font-mono text-ink-700 dark:text-ink-300">{formatStars(stars) ?? "—"}</dd></div>
+    <div class="flex items-baseline gap-1.5"><dt class="font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">Updated</dt><dd class="font-mono text-ink-700 dark:text-ink-300">{formatRelative(updatedAt)}</dd></div>
+    <div class="flex items-baseline gap-1.5"><dt class="font-medium uppercase tracking-wider text-ink-500 dark:text-ink-400">License</dt><dd class="font-mono text-ink-700 dark:text-ink-300">{license ?? "—"}</dd></div>
   </dl>
 
   {showChips && (platforms.length > 0 || stacks.length > 0) && (

package/src/components/ItemCard.astro

@@ -148,13 +148,7 @@ const category = (item as { category?: string }).category;
   class={`rounded-[calc(var(--radius)+0.25rem)] border-0 bg-muted shadow-none transition-colors hover:bg-secondary group relative flex h-full flex-col gap-3 p-4 ${className}`}
 >
   {/* Top row: logo + name + (optional) status + curated mark. */}
-  <header class="relative z-10 flex items-start gap-3">
-    <a
-      href={detailHref}
-      aria-label={`Open ${name} details`}
-      class="absolute inset-0 z-0 rounded-lg"
-    ></a>
-
+  <header class="flex items-start gap-3">
     {logoUrl ? (
       <img
         src={logoUrl}
@@ -178,11 +172,10 @@ const category = (item as { category?: string }).category;
       <h3
         class="m-0 truncate text-[0.9375rem] font-semibold tracking-tight text-ink-900 group-hover:underline dark:text-ink-100"
       >
-        {/* Name → detail page (not GitHub repo). Stacks above the
-            stretched link via z-index. */}
+        {/* Name → detail page (not GitHub repo). */}
         <a
           href={detailHref}
-          class="relative z-10 text-inherit no-underline"
+          class="inline-flex min-h-6 min-w-6 items-center text-inherit no-underline"
         >
           {name}
         </a>
@@ -198,7 +191,7 @@ const category = (item as { category?: string }).category;
                 data-event="external_repo_click"
                 data-event-source="card_owner"
                 data-event-item={slug}
-                class="relative z-10 font-mono text-ink-500 hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100"
+                class="font-mono text-ink-500 hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100"
               >
                 {/* `data-event` and `data-event-*` are forwarding hooks
                     for downstream analytics. Sites wire their own
@@ -210,7 +203,7 @@ const category = (item as { category?: string }).category;
                     "detail_owner" | "detail_view_github" | "detail_homepage"
                     | "detail_distribution"), and `data-event-item` is
                     the record slug. */}
-                <span class="text-ink-400 dark:text-ink-500">@</span>{owner}{repo ? <span class="text-ink-400 dark:text-ink-500">/{repo}</span> : ""}
+                <span class="text-ink-400">@</span>{owner}{repo ? <span class="text-ink-400">/{repo}</span> : ""}
               </a>
               <span class="mx-1 text-ink-300 dark:text-ink-700">·</span>
               {category}
@@ -252,7 +245,7 @@ const category = (item as { category?: string }).category;
   {/* Description */}
   {item.description && (
     <p
-      class="relative z-10 m-0 line-clamp-2 text-[0.8125rem] leading-relaxed text-ink-500 dark:text-ink-400"
+      class="m-0 line-clamp-2 text-[0.8125rem] leading-relaxed text-ink-500 dark:text-ink-400"
     >
       {item.description}
     </p>
@@ -261,7 +254,7 @@ const category = (item as { category?: string }).category;
   {/* Metadata row: stars · updated · license — the three signals
       that answer "is this alive and usable?" at a glance. */}
   {showMeta && (
-    <div class="relative z-10 flex flex-wrap items-center gap-x-3 gap-y-1 text-2xs text-ink-500 dark:text-ink-400">
+    <div class="flex flex-wrap items-center gap-x-3 gap-y-1 text-2xs text-ink-500 dark:text-ink-400">
       {starsLabel !== null && (
         <span class="inline-flex items-center gap-1" title={`${stars ?? 0} stars on GitHub`}>
           <svg viewBox="0 0 16 16" width="11" height="11" aria-hidden="true" fill="currentColor" class="text-amber-500">
@@ -288,7 +281,7 @@ const category = (item as { category?: string }).category;
 
   {/* Platform + stack chips, pushed to the bottom. */}
   {showChips && (
-    <div class="relative z-10 mt-auto flex flex-col gap-1.5">
+    <div class="mt-auto flex flex-col gap-1.5">
       {visiblePlatforms.length > 0 && (
         <div class="flex flex-wrap items-center gap-1.5">
           {visiblePlatforms.map((p) => (
@@ -298,7 +291,7 @@ const category = (item as { category?: string }).category;
             </span>
           ))}
           {platformOverflow > 0 && (
-            <span class="inline-flex min-h-5 items-center justify-center gap-1 rounded-full border border-transparent bg-secondary px-2 py-0.5 align-middle text-xs font-medium leading-none text-secondary-foreground text-ink-400 dark:text-ink-500">+{platformOverflow}</span>
+            <span class="inline-flex min-h-5 items-center justify-center gap-1 rounded-full border border-transparent bg-secondary px-2 py-0.5 align-middle text-xs font-medium leading-none text-secondary-foreground text-ink-400">+{platformOverflow}</span>
           )}
         </div>
       )}
@@ -311,7 +304,7 @@ const category = (item as { category?: string }).category;
             </span>
           ))}
           {stackOverflow > 0 && (
-            <span class="inline-flex min-h-5 items-center justify-center gap-1 rounded-full border border-transparent bg-secondary px-2 py-0.5 align-middle text-xs font-medium leading-none text-secondary-foreground !bg-muted !text-muted-foreground text-ink-400 dark:text-ink-500">+{stackOverflow}</span>
+            <span class="inline-flex min-h-5 items-center justify-center gap-1 rounded-full border border-transparent bg-secondary px-2 py-0.5 align-middle text-xs font-medium leading-none text-secondary-foreground !bg-muted !text-muted-foreground text-ink-400">+{stackOverflow}</span>
           )}
         </div>
       )}
@@ -319,7 +312,7 @@ const category = (item as { category?: string }).category;
   )}
 
   {/* Footer row: View repo + Details links. */}
-  <footer class="relative z-10 mt-1 flex items-center justify-between gap-2 border-t border-ink-100 pt-2 text-2xs dark:border-ink-900">
+  <footer class="mt-1 flex items-center justify-between gap-2 border-t border-ink-100 pt-2 text-2xs dark:border-ink-900">
     {externalHref && (
       <a
         href={externalHref}
@@ -328,7 +321,7 @@ const category = (item as { category?: string }).category;
         data-event="external_repo_click"
         data-event-source="card_view_repo"
         data-event-item={slug}
-        class="relative z-10 inline-flex items-center gap-1 font-medium text-ink-700 transition-colors hover:text-ink-900 dark:text-ink-300 dark:hover:text-ink-100"
+        class="inline-flex items-center gap-1 font-medium text-ink-700 transition-colors hover:text-ink-900 dark:text-ink-300 dark:hover:text-ink-100"
       >
         {repoHref ? "View repo" : "Visit source"}
         <svg viewBox="0 0 16 16" width="10" height="10" aria-hidden="true" fill="currentColor">
@@ -339,7 +332,7 @@ const category = (item as { category?: string }).category;
     )}
     <a
       href={detailHref}
-      class="relative z-10 inline-flex items-center gap-1 font-medium text-ink-500 transition-colors hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100"
+      class="inline-flex items-center gap-1 font-medium text-ink-500 transition-colors hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100"
     >
       Details →
     </a>

package/src/components/RefinePanel.astro

@@ -99,7 +99,7 @@ const groups: RenderedFilterGroup[] = baseGroups
   }));
 ---
 
-<section class:list={["flex flex-wrap items-center gap-2", className]} role="toolbar" aria-label="Filter items">
+<div class:list={["flex flex-wrap items-center gap-2", className]} role="toolbar" aria-label="Filter items">
     {groups.map((group) => <FilterGroupMenu {...group} />)}
 
     {!hide.includes("sort") && (
@@ -113,7 +113,7 @@ const groups: RenderedFilterGroup[] = baseGroups
         </svg>
       </label>
     )}
-</section>
+</div>
 
 <script is:inline define:vars={{ pathPrefix }}>
   (() => {

package/src/layouts/Footer.astro

@@ -170,9 +170,9 @@ const resolvedLicenseLine = licenseLine ?? site.footer?.license;
 
     {columns.map((column) => (
       <div>
-        <h4 class="mb-3 text-2xs font-semibold uppercase tracking-wider text-ink-900 dark:text-ink-100">
+        <h2 class="mb-3 text-2xs font-semibold uppercase tracking-wider text-ink-900 dark:text-ink-100">
           {column.heading}
-        </h4>
+        </h2>
         <ul class="m-0 flex list-none flex-col gap-2 p-0">
           {column.items.map((item) => (
             <li>

package/src/lib/index.ts

@@ -24,3 +24,4 @@ export * from "./search.js";
 export * from "./scores.js";
 export * from "./taxonomy-counts.js";
 export * from "./display.js";
+export * from "./load-collections.js";

package/src/lib/load-collections.ts

@@ -0,0 +1,33 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { Collection } from "@grove-dev/core";
+
+/**
+ * Load all `Collection` YAML files from `<cwd>/data/collections/*.yml`.
+ *
+ * Returns an empty array if the directory does not exist, so callers can
+ * safely render an empty/loading state without having to guard each
+ * invocation site. Parse errors and other unexpected failures are NOT
+ * swallowed — they surface so real problems (malformed YAML, permission
+ * errors, etc.) are visible instead of silently producing empty output.
+ */
+export async function loadCollections(cwd: string): Promise<Collection[]> {
+  const dir = resolve(cwd, "data/collections");
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+  const out: Collection[] = [];
+  for (const f of files.filter((f) => f.endsWith(".yml"))) {
+    const raw = parseYaml(await readFile(join(dir, f), "utf8"));
+    if (!raw || typeof raw !== "object") {
+      throw new Error(`Invalid collection YAML: ${f}`);
+    }
+    out.push(raw as Collection);
+  }
+  return out;
+}

package/src/server/collections.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, it } from "vitest";
+import {
+  recordsToCollectionEntries,
+  getCollectionPageModel,
+  getCollectionIndexModel,
+  getCollectionTeaserModel,
+} from "./collections.js";
+import type { Collection, CollectionEntry } from "@grove-dev/core";
+
+describe("recordsToCollectionEntries", () => {
+  it("maps a full record to a CollectionEntry", () => {
+    const records = [
+      {
+        slug: "crewai",
+        name: "CrewAI",
+        description: "Agent framework",
+        stack: "python",
+        stacks: ["python"],
+        platforms: ["linux", "macos"],
+        license: "MIT",
+        visibility: "keep",
+        stars: 100,
+        pushedAt: "2026-01-15T00:00:00Z",
+        lastCommitAt: "2026-02-01T00:00:00Z",
+        category: "agents",
+        tags: ["multi-agent", "automation"],
+        scores: { curation: 0.8, activity: 0.7 },
+      },
+    ];
+    const entries = recordsToCollectionEntries(records as never, { routeSlug: "projects" });
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      slug: "crewai",
+      title: "CrewAI",
+      description: "Agent framework",
+      url: "/projects/crewai/",
+      stack: "python",
+      platform: ["linux", "macos"],
+      license: "MIT",
+      status: "keep",
+      stars: 100,
+      pushedAt: "2026-01-15T00:00:00Z",
+      curationScore: 0.8,
+      activityScore: 0.7,
+      categories: expect.arrayContaining(["agents", "multi-agent", "automation"]),
+    });
+  });
+
+  it("filters out hidden records", () => {
+    const records = [
+      { slug: "a", name: "A", visibility: "keep" },
+      { slug: "b", name: "B", visibility: "hide" },
+    ];
+    const entries = recordsToCollectionEntries(records as never, { routeSlug: "projects" });
+    expect(entries.map((e) => e.slug)).toEqual(["a"]);
+  });
+
+  it("falls back to stacks[0] when stack is missing", () => {
+    const records = [{ slug: "x", name: "X", stacks: ["node"] }];
+    const entries = recordsToCollectionEntries(records as never, { routeSlug: "projects" });
+    expect(entries[0].stack).toBe("node");
+  });
+
+  it("prefers lastCommitAt when pushedAt is missing", () => {
+    const records = [{ slug: "x", name: "X", lastCommitAt: "2026-03-01T00:00:00Z" }];
+    const entries = recordsToCollectionEntries(records as never, { routeSlug: "projects" });
+    expect(entries[0].pushedAt).toBe("2026-03-01T00:00:00Z");
+  });
+
+  it("deduplicates categories when category is also in tags", () => {
+    const records = [{ slug: "x", name: "X", category: "agents", tags: ["agents", "x"] }];
+    const entries = recordsToCollectionEntries(records as never, { routeSlug: "projects" });
+    expect(entries[0].categories).toEqual(["agents", "x"]);
+  });
+
+  it("defaults routeSlug to 'projects' when not provided", () => {
+    const records = [{ slug: "x", name: "X" }];
+    const entries = recordsToCollectionEntries(records as never, {});
+    expect(entries[0].url).toBe("/projects/x/");
+  });
+});
+
+const collection: Collection = {
+  slug: "top-ai-agents",
+  kind: "curated",
+  title: "Top AI Agents",
+  description: "Best agent frameworks.",
+  query: { stacks: ["python"] },
+  ranking: { preset: "quality" },
+  seo: { index: true },
+  editorial: { selectionNote: "Ranked by activity and curation." },
+};
+
+const otherCollection: Collection = {
+  slug: "top-tools",
+  kind: "curated",
+  title: "Top Tools",
+  description: "All tools.",
+  query: { stacks: ["python"] },
+  ranking: { preset: "recency" },
+  seo: { index: true },
+};
+
+const emptyCollection: Collection = {
+  slug: "no-matches",
+  kind: "curated",
+  title: "No Matches",
+  description: "Won't match anything.",
+  query: { stacks: ["rust"] },
+  ranking: { preset: "recency" },
+  seo: { index: true },
+};
+
+const entries: CollectionEntry[] = [
+  {
+    slug: "crewai",
+    title: "CrewAI",
+    description: "Agent framework",
+    url: "/projects/crewai/",
+    stack: "python",
+    curationScore: 0.9,
+    activityScore: 0.8,
+  },
+  {
+    slug: "dify",
+    title: "Dify",
+    description: "LLM platform",
+    url: "/projects/dify/",
+    stack: "python",
+    curationScore: 0.7,
+    activityScore: 0.6,
+  },
+  {
+    slug: "flowise",
+    title: "Flowise",
+    description: "Node tool",
+    url: "/projects/flowise/",
+    stack: "node",
+    curationScore: 0.5,
+    activityScore: 0.4,
+  },
+];
+
+describe("getCollectionPageModel", () => {
+  it("returns ranked entries filtered by query", () => {
+    const model = getCollectionPageModel(collection, entries, [collection, otherCollection]);
+    expect(model.total).toBe(2);
+    expect(model.isEmpty).toBe(false);
+    expect(model.entries.map((e) => e.slug)).toEqual(["crewai", "dify"]);
+  });
+
+  it("exposes editorial selection note", () => {
+    const model = getCollectionPageModel(collection, entries, [collection]);
+    expect(model.collection.selectionNote).toBe("Ranked by activity and curation.");
+  });
+
+  it("returns related collections (max 4)", () => {
+    const model = getCollectionPageModel(collection, entries, [collection, otherCollection]);
+    expect(model.related).toHaveLength(1);
+    expect(model.related[0].slug).toBe("top-tools");
+  });
+
+  it("reports empty when no entries match", () => {
+    const model = getCollectionPageModel(emptyCollection, entries, [collection, otherCollection]);
+    expect(model.isEmpty).toBe(true);
+  });
+});
+
+describe("getCollectionIndexModel", () => {
+  it("counts entries per collection", () => {
+    const model = getCollectionIndexModel([collection, otherCollection], entries);
+    expect(model.total).toBe(2);
+    expect(model.collections).toHaveLength(2);
+    const agentCol = model.collections.find((c) => c.slug === "top-ai-agents");
+    expect(agentCol?.count).toBe(2);
+    expect(agentCol?.url).toBe("/collections/top-ai-agents/");
+  });
+});
+
+describe("getCollectionTeaserModel", () => {
+  it("respects the limit", () => {
+    const model = getCollectionTeaserModel([collection, otherCollection], entries, 1);
+    expect(model.collections).toHaveLength(1);
+  });
+
+  it("uses the project's route slug for entry URLs", () => {
+    const model = getCollectionTeaserModel([collection], entries, 5);
+    expect(model.collections[0].count).toBe(2);
+  });
+});

package/src/server/collections.ts

@@ -0,0 +1,197 @@
+import type { Collection, CollectionEntry } from "@grove-dev/core";
+import { findRelated, runCollection } from "@grove-dev/core";
+import { readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+interface RouteHint {
+  routeSlug?: string;
+  blueprintConfig?: { routeSlug?: string };
+}
+
+interface RawRecord {
+  slug?: string;
+  name?: string;
+  title?: string;
+  description?: string;
+  stack?: string;
+  stacks?: string[];
+  platforms?: string[];
+  license?: string;
+  visibility?: string;
+  stars?: number;
+  pushedAt?: string;
+  lastCommitAt?: string;
+  category?: string;
+  tags?: string[];
+  scores?: { curation?: number; activity?: number };
+}
+
+/**
+ * Map a list of full records (shape produced by `records.json`) to
+ * the lightweight `CollectionEntry` shape consumed by `runCollection`.
+ *
+ * - Skips records with `visibility === "hide"` — they should never
+ *   appear in any collection.
+ * - Combines `category` and `tags` into a `categories` array (deduplicated).
+ * - Falls back to `stacks[0]` when `stack` is missing.
+ * - Prefers `pushedAt`; falls back to `lastCommitAt`.
+ * - Constructs `url` as `${routeSlug}/${slug}/` so the value points
+ *   back to the consumer's detail page.
+ */
+export function recordsToCollectionEntries(
+  records: RawRecord[],
+  site: RouteHint,
+): CollectionEntry[] {
+  const routeSlug = site.routeSlug ?? site.blueprintConfig?.routeSlug ?? "projects";
+  const out: CollectionEntry[] = [];
+  for (const r of records) {
+    if (r.visibility === "hide") continue;
+    if (!r.slug) continue;
+    const categories = [
+      ...(r.category ? [r.category] : []),
+      ...(r.tags ?? []),
+    ].filter((value, index, self) => self.indexOf(value) === index);
+    out.push({
+      slug: r.slug,
+      title: r.name ?? r.title ?? r.slug,
+      description: r.description ?? "",
+      url: `/${routeSlug}/${r.slug}/`,
+      stack: r.stack ?? r.stacks?.[0],
+      platform: r.platforms,
+      license: r.license,
+      status: r.visibility,
+      stars: r.stars,
+      pushedAt: r.pushedAt ?? r.lastCommitAt,
+      curationScore: r.scores?.curation,
+      activityScore: r.scores?.activity,
+      categories: categories.length > 0 ? categories : undefined,
+    });
+  }
+  return out;
+}
+
+// ── Collection view-models ──────────────────────────────────────
+//
+// A Collection is a curated or generated grouping of records
+// (see `@grove-dev/core`'s `runCollection` engine). These view-models
+// produce the input the `CollectionPage`, `CollectionIndex`, and
+// `CollectionTeaser` components consume.
+
+export interface CollectionPageModel {
+  collection: {
+    slug: string;
+    title: string;
+    description: string;
+    kind: "curated" | "generated";
+    selectionNote?: string;
+    introduction?: string;
+  };
+  total: number;
+  isEmpty: boolean;
+  entries: CollectionEntry[];
+  related: Array<{ slug: string; title: string; url: string }>;
+}
+
+export interface CollectionIndexModel {
+  total: number;
+  collections: Array<{
+    slug: string;
+    title: string;
+    description: string;
+    kind: "curated" | "generated";
+    count: number;
+    url: string;
+  }>;
+}
+
+export interface CollectionTeaserModel {
+  total: number;
+  collections: CollectionIndexModel["collections"];
+}
+
+export function getCollectionPageModel(
+  collection: Collection,
+  entries: CollectionEntry[],
+  allCollections: Collection[],
+): CollectionPageModel {
+  const result = runCollection(collection, entries);
+  const related = findRelated(collection, allCollections, 4).map((c) => ({
+    slug: c.slug,
+    title: c.title,
+    url: `/collections/${c.slug}/`,
+  }));
+  return {
+    collection: {
+      slug: collection.slug,
+      title: collection.title,
+      description: collection.description,
+      kind: collection.kind,
+      selectionNote: collection.editorial?.selectionNote,
+      introduction: collection.editorial?.introduction,
+    },
+    total: result.entries.length,
+    isEmpty: result.isEmpty,
+    entries: result.entries,
+    related,
+  };
+}
+
+export function getCollectionIndexModel(
+  collections: Collection[],
+  entries: CollectionEntry[],
+): CollectionIndexModel {
+  return {
+    total: collections.length,
+    collections: collections.map((c) => {
+      const result = runCollection(c, entries);
+      return {
+        slug: c.slug,
+        title: c.title,
+        description: c.description,
+        kind: c.kind,
+        count: result.entries.length,
+        url: `/collections/${c.slug}/`,
+      };
+    }),
+  };
+}
+
+export function getCollectionTeaserModel(
+  collections: Collection[],
+  entries: CollectionEntry[],
+  limit = 3,
+): CollectionTeaserModel {
+  const full = getCollectionIndexModel(collections, entries);
+  return {
+    total: full.total,
+    collections: full.collections.slice(0, limit),
+  };
+}
+
+/**
+ * Load all `Collection` YAML files from `<cwd>/data/collections/*.yml`.
+ *
+ * Returns an empty array if the directory does not exist. Parse
+ * errors are NOT swallowed — they surface so real problems
+ * (malformed YAML, permission errors) are not hidden.
+ */
+export async function loadCollections(cwd: string): Promise<Collection[]> {
+  const dir = resolve(cwd, "data/collections");
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+  const out: Collection[] = [];
+  for (const f of files.filter((f) => f.endsWith(".yml"))) {
+    const raw = parseYaml(await readFile(join(dir, f), "utf8"));
+    if (!raw || typeof raw !== "object") {
+      throw new Error(`Invalid collection YAML: ${f}`);
+    }
+    out.push(raw as Collection);
+  }
+  return out;
+}

package/src/server/index.ts

@@ -1,2 +1,3 @@
 export * from "./directory.js";
 export * from "./models.js";
+export * from "./collections.js";