+```
+
+Replace the opening `` tag (the first two lines through the closing `>`) with:
+
+```handlebars
+
+```
+
+`{{slug}}` is single-brace (Handlebars HTML-escapes by default) — safe for any post slug since slugs are restricted to URL-safe characters by Ghost.
+
+- [ ] **Step 2: Build and lint**
+
+```
+npx gulp build
+npm run test
+```
+
+- [ ] **Step 3: Manually verify in browser**
+
+Reload any page that renders `post-card.hbs` (e.g. `http://localhost:2368/`). Open DevTools, inspect any `.feed-card`, confirm `data-slug=""` is present.
+
+- [ ] **Step 4: Commit**
+
+```
+git add partials/post-card.hbs
+git commit -m "feat(post-card): expose slug as data attribute for related-posts JS"
+```
+
+---
+
+## Task 4: Create `assets/js/related-posts.js` Alpine component
+
+**Files:**
+
+- Create: `assets/js/related-posts.js`
+
+The orchestration component. ~140 lines total. Reads the source post's metadata from `data-*` attributes on its own root element, reads SSR cards via `[data-slug]` query, fires one Typesense `searchSimilar` call, then either replaces the SSR cards with Typesense-ranked cards (topping up from SSR if Typesense returned < 3) or leaves them untouched on failure / empty response / identical-set short-circuit.
+
+Includes a `buildCardElement(hit)` helper that mirrors `partials/post-card.hbs` structure — see Task 3's data-slug change and the spec's "Card-building contract" section.
+
+- [ ] **Step 1: Create `assets/js/related-posts.js`**
+
+```javascript
+// Alpine component for the bottom-of-article "You might also like…" widget.
+// Used by partials/related.hbs.
+//
+// Reads the source post's id, title, and excerpt from data-* attributes
+// on its own root element ($el.dataset). Fires one Typesense searchSimilar
+// call, then merges the response with the SSR cards already in the DOM:
+//
+// - If Typesense returns 3 hits and they differ from the SSR slugs:
+// replace the grid contents with 3 cards (reusing SSR DOM where slug
+// matches, building new DOM via buildCardElement() otherwise).
+// - If Typesense returns 1-2 hits: render those, then top up from SSR
+// cards (skipping duplicates) until 3.
+// - If Typesense returns 0 / fails / aborts / matches the SSR set:
+// do nothing — SSR cards stay.
+//
+// IMPORTANT: buildCardElement() below mirrors partials/post-card.hbs.
+// If post-card.hbs changes shape, mirror the change here too.
+
+import { searchSimilar } from "./typesense-search.js";
+
+const TARGET_COUNT = 3;
+const QUERY_MAX_CHARS = 500; // keeps Typesense URL well under 8KB
+
+export default function relatedPosts() {
+ return {
+ async init() {
+ const root = this.$el;
+ const grid = root.querySelector(".related-feed");
+ if (!grid) return;
+
+ const source = {
+ id: root.dataset.postId || "",
+ title: root.dataset.postTitle || "",
+ excerpt: root.dataset.postExcerpt || "",
+ };
+
+ // Nothing to query with — leave SSR cards alone.
+ if (!source.title && !source.excerpt) return;
+
+ const ssrCards = Array.from(
+ grid.querySelectorAll(".feed-card[data-slug]"),
+ ).map((el) => ({ slug: el.dataset.slug, el }));
+
+ const query = `${source.title}\n${source.excerpt}`
+ .trim()
+ .slice(0, QUERY_MAX_CHARS);
+
+ let hits;
+ try {
+ hits = await searchSimilar(query, {
+ excludeId: source.id,
+ limit: TARGET_COUNT,
+ });
+ } catch (err) {
+ if (err.name !== "AbortError") {
+ console.warn("related-posts: Typesense search failed", err);
+ }
+ return; // SSR cards stay
+ }
+
+ // Defensive: drop any hit matching the source post (in case
+ // filter_by didn't work for some reason).
+ hits = hits.filter((h) => h.slug !== source.id && h.slug);
+
+ if (hits.length === 0) return; // SSR cards stay
+
+ // Equal-set short-circuit (any order): skip DOM swap to avoid
+ // a visible re-layout flash for the common case where the SSR
+ // fallback already had the right posts.
+ const hitSlugs = hits.map((h) => h.slug).sort();
+ const ssrSlugs = ssrCards.map((c) => c.slug).sort();
+ if (
+ hitSlugs.length === ssrSlugs.length &&
+ hitSlugs.every((s, i) => s === ssrSlugs[i])
+ ) {
+ return;
+ }
+
+ // Build the final card list: Typesense hits first (reusing SSR
+ // DOM where slugs match), then top up with SSR cards not yet
+ // included, until TARGET_COUNT.
+ const finalEls = [];
+ const usedSlugs = new Set();
+ for (const hit of hits) {
+ const ssr = ssrCards.find((c) => c.slug === hit.slug);
+ finalEls.push(ssr ? ssr.el : buildCardElement(hit));
+ usedSlugs.add(hit.slug);
+ }
+ for (const ssr of ssrCards) {
+ if (finalEls.length >= TARGET_COUNT) break;
+ if (!usedSlugs.has(ssr.slug)) {
+ finalEls.push(ssr.el);
+ usedSlugs.add(ssr.slug);
+ }
+ }
+
+ grid.replaceChildren(...finalEls);
+ },
+ };
+}
+
+// IMPORTANT: this builder mirrors partials/post-card.hbs. Keep the structure
+// (article > div.flex > optional img + div.grow > primary tag span + title +
+// excerpt + date / stretch-link anchor) byte-equivalent (modulo data
+// attributes specific to the filter feature, which related-posts doesn't
+// need).
+function buildCardElement(hit) {
+ const article = document.createElement("article");
+ article.className =
+ "feed-card post rounded-lg shadow-2xl m-auto w-full max-w-2xl md:max-w-full lg:h-full hover:shadow-md hover:border-opacity-0 transform hover:-translate-y-1 transition-all duration-200";
+ article.dataset.slug = hit.slug || "";
+
+ const inner = document.createElement("div");
+ inner.className =
+ "flex flex-col cursor-pointer h-full rounded-xl overflow-hidden md:flex-row md:h-80 lg:flex-col lg:h-full";
+ inner.setAttribute("onclick", `location.href='${hit.url || "#"}'`);
+
+ if (hit.feature_image) {
+ const img = document.createElement("img");
+ img.className =
+ "object-cover m-0 h-full md:aspect-[9/5] lg:h-auto lg:aspect-[15/8]";
+ img.src = hit.feature_image;
+ img.alt = hit.title || "";
+ inner.appendChild(img);
+ }
+
+ const body = document.createElement("div");
+ body.className = "grow bg-white px-3 pt-3 pb-5 relative";
+
+ // Primary tag = first non-routing tag (routing tags start with "hash-").
+ const primaryTag = pickPrimaryTag(hit);
+ if (primaryTag) {
+ const tagSpan = document.createElement("span");
+ tagSpan.className = "single-meta-item single-meta-tag";
+ const tagAnchor = document.createElement("a");
+ tagAnchor.className = `post-tag post-tag-${primaryTag.slug} text-lg uppercase font-extrabold`;
+ tagAnchor.href = `/tag/${primaryTag.slug}/`;
+ tagAnchor.textContent = primaryTag.name;
+ tagSpan.appendChild(tagAnchor);
+ body.appendChild(tagSpan);
+ } else {
+ const noTag = document.createElement("span");
+ noTag.className = "text-lg uppercase font-extrabold";
+ noTag.textContent = "[No tag]";
+ body.appendChild(noTag);
+ }
+
+ const titleEl = document.createElement("p");
+ titleEl.className = "text-2xl font-bold my-2";
+ titleEl.textContent = hit.title || "";
+ body.appendChild(titleEl);
+
+ const excerptEl = document.createElement("p");
+ excerptEl.className = "text-xl my-1 line-clamp-4";
+ excerptEl.textContent = hit.excerpt || "";
+ body.appendChild(excerptEl);
+
+ const spacer = document.createElement("div");
+ spacer.className = "h-8";
+ body.appendChild(spacer);
+
+ const dateWrap = document.createElement("div");
+ dateWrap.className = "text-xl absolute right-4 bottom-4";
+ const clockIcon = document.createElement("i");
+ clockIcon.className = "far fa-clock";
+ dateWrap.appendChild(clockIcon);
+ if (hit.published_at) {
+ const date = new Date(hit.published_at);
+ const timeEl = document.createElement("time");
+ timeEl.dateTime = date.toISOString().split("T")[0];
+ timeEl.textContent =
+ " " +
+ date.toLocaleDateString("en-GB", {
+ day: "numeric",
+ month: "short",
+ year: "numeric",
+ });
+ dateWrap.appendChild(timeEl);
+ }
+ body.appendChild(dateWrap);
+
+ inner.appendChild(body);
+
+ const stretchAnchor = document.createElement("a");
+ stretchAnchor.href = hit.url || "#";
+ const stretchSpan = document.createElement("span");
+ stretchSpan.className = "stretch-link";
+ stretchAnchor.appendChild(stretchSpan);
+ inner.appendChild(stretchAnchor);
+
+ article.appendChild(inner);
+ return article;
+}
+
+// First non-hash-prefixed tag from the parallel tags.name / tags.slug arrays.
+// Returns null if all tags are routing tags or arrays are missing/empty.
+function pickPrimaryTag(hit) {
+ const names = hit["tags.name"] || hit.tags || [];
+ const slugs = hit["tags.slug"] || [];
+ for (let i = 0; i < slugs.length; i++) {
+ if (slugs[i] && !slugs[i].startsWith("hash-")) {
+ return { name: names[i] || slugs[i], slug: slugs[i] };
+ }
+ }
+ return null;
+}
+```
+
+- [ ] **Step 2: Build and lint**
+
+```
+npx gulp build
+npm run test
+```
+
+The bundle will now actually include `typesense-search.js` (it's imported here). Build should succeed.
+
+- [ ] **Step 3: Commit**
+
+```
+git add assets/js/related-posts.js
+git commit -m "feat(related): add Alpine component with Typesense fetch + card builder"
+```
+
+---
+
+## Task 5: Wrap `partials/related.hbs` with the Alpine component
+
+**Files:**
+
+- Modify: `partials/related.hbs` (whole file replaced)
+
+Wrap the existing `` with `x-data="relatedPosts"`. Add `data-post-id`, `data-post-title`, `data-post-excerpt` so the JS can read the source post's metadata. Move the `{{#if related}}` gate so it only suppresses the inner `{{#foreach}}` — the wrapper itself always renders so the JS can populate it from Typesense even when SSR returns 0 cards (rare: post with no shared-tag matches).
+
+- [ ] **Step 1: Replace `partials/related.hbs` with the updated content**
+
+Replace the entire file with:
+
+```handlebars
+{{!-- Bottom-of-article "You might also like…" widget.
+ The SSR {{#get}} block below renders 3 tag-matched cards as the
+ no-JS baseline AND as a topup pool for the JS-side Typesense
+ enhancement (see assets/js/related-posts.js). --}}
+
+```
+
+Notes:
+
+- The `` is now the Alpine root — `$el.dataset.postId` etc. read off it.
+- `data-post-title` and `data-post-excerpt` use Handlebars HTML-attribute escaping (handles quotes, ampersands, etc. correctly — safer than a `` injecting `{{@custom.typesense_*}}`. (Same block as Feature 1; will collide trivially on merge.) |
+| `package.json` | Modify | Add `config.custom.typesense_host`, `typesense_api_key`, `typesense_collection`. (Same as Feature 1; will collide trivially on merge.) |
+| `README.md` | Modify | Add the Typesense Search section. (Same as Feature 1; trivial conflict.) |
+
+**Untouched:**
+
+- `post.hbs` — the `{{#if @custom.show_related_posts}}{{> related}}{{/if}}` block already does the right thing.
+- `assets/css/` — Tailwind utilities only, applied inline in the JS card builder.
+- `partials/post-filter-list.hbs` and any other listing partial — orthogonal.
+
+## Data flow
+
+State (per Alpine instance, one per article view):
+
+```
+source : { id: string, title: string, excerpt: string } // from $el.dataset
+ssrCards : Array<{ slug: string, el: HTMLElement }> // from SSR DOM
+typesenseHits : Array<{ slug, title, excerpt, feature_image, url, primary_tag, published_at }> | null
+ // null = fetch in progress or not started
+```
+
+Pipeline (one shot, on init):
+
+```
+init()
+ ↓ source = { id: $el.dataset.postId, title: $el.dataset.postTitle, excerpt: $el.dataset.postExcerpt }
+ ↓ ssrCards = grid.querySelectorAll('.feed-card[data-slug]')
+ ↓ if (!source.title && !source.excerpt) return // nothing to query with
+ ↓
+ fetch Typesense with q = (title + "\n" + excerpt).slice(0, 500)
+ filter_by = id:!=
+ include_fields = slug,title,excerpt,feature_image,url,tags,published_at
+ per_page = 3
+ ↓
+ if fetch fails OR returns 0 hits:
+ return // SSR cards stay
+ ↓
+ if hits.slugs.sort() == ssrCards.slugs.sort():
+ return // identical set, skip DOM swap (no flash)
+ ↓
+ finalCards = []
+ for hit in hits:
+ ssr = ssrCards.find(c => c.slug === hit.slug)
+ finalCards.push(ssr ? ssr.el : buildCardElement(hit))
+ for ssr in ssrCards:
+ if finalCards.length >= 3: break
+ if !finalCards.includes(ssr.el): finalCards.push(ssr.el)
+ ↓
+ grid.replaceChildren(...finalCards)
+```
+
+## Card-building contract
+
+`buildCardElement(hit)` produces DOM byte-equivalent to what `partials/post-card.hbs` emits, modulo:
+
+- No `data-tags` / `data-tag-names` (those are filter-page concerns; `related-posts.js` doesn't use them).
+- The `data-slug="{{slug}}"` IS preserved.
+- `data-title` and `data-published-at` from Feature 1 are NOT added (filter-page only).
+
+Required Typesense fields per hit:
+
+- `slug` (string) — DOM identity / dedup
+- `title` (string) — heading
+- `excerpt` (string) — body copy (line-clamped to 4)
+- `feature_image` (string | null) — `![]()
` src; if null, the `![]()
` is omitted
+- `url` (string) — anchor href
+- `tags` (array of objects with `name`, `slug`, `url`) — first one becomes the primary-tag chip
+- `published_at` (number, Unix ms) — formatted client-side as `D MMM YYYY` to match `{{date format="D MMM YYYY"}}`
+
+Verified against schema probe done earlier (collection `ghost`, 283 documents): all fields present.
+
+**Cross-file maintenance:** comments in both `partials/post-card.hbs` and `assets/js/related-posts.js` point at each other. If either changes structure, the comment is the breadcrumb.
+
+## Failure modes and edge cases
+
+| Case | Behavior |
+| ---------------------------------------------------- | --------------------------------------------------------------------------- |
+| Typesense unreachable / 5xx / malformed JSON | Silent. SSR cards stay. `console.warn` for ops debugging. |
+| AbortError (in-flight aborted by navigation) | Silent. No DOM mutation. |
+| Typesense returns 0 hits | SSR cards stay. |
+| Typesense returns 1-2 hits | Render those, top up from SSR cards skipping duplicates. |
+| Typesense returns the current post (despite filter) | Defensive client-side filter: drop hits where `slug === source.slug`. |
+| Top-3 Typesense slugs == top-3 SSR slugs (any order) | No DOM mutation. Avoids re-layout flash. |
+| Empty SSR baseline (post has no tag overlap) | Wrapper still rendered; JS populates if Typesense succeeds. |
+| Post with no excerpt | Query is just title. Acceptable. |
+| Long title + long excerpt | Query capped at 500 chars (`q.slice(0, 500)`). |
+| `@custom.show_related_posts` = false | `post.hbs` doesn't include the partial. Zero work happens. |
+| Missing `window.__TYPESENSE_CONFIG__` | Wrapper falls back to in-file defaults. Same defaults as Feature 1. |
+| `feature_image` empty in Typesense response | `![]()
` element omitted (mirrors `{{#if feature_image}}` in post-card.hbs). |
+| `tags` array empty | Primary tag span shows "[No tag]" (mirrors `{{else}}` in post-card.hbs). |
+
+## Network traffic
+
+- **Per page load on a post:** one Typesense request (~500 bytes out, ~1-3 KB in for 3 hits with full fields). Plus one CORS preflight on first request from each origin. Total ~5 KB per article view.
+- **Per page load on a non-post (homepage, listings):** zero — `partials/related.hbs` only renders inside `{{#is "post"}}` in `post.hbs`.
+- Fits well within the spec acceptable budget; comparable to or lighter than the SSR widget's existing Ghost server-side `{{#get}}` cost (which it does not eliminate, but does add to).
+
+## Accessibility
+
+- Existing `` heading preserved.
+- `