From 1374a9d5fd945bdccb571c91df7f32db72a13d79 Mon Sep 17 00:00:00 2001
From: comwanga <mwanga02717@gmail.com>
Date: Wed, 17 Jun 2026 18:35:10 +0300
Subject: [PATCH 1/7] docs(spec): breadcrumb navigation for nested dashboard
 pages

---
 ...2026-06-17-breadcrumb-navigation-design.md | 94 +++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md

diff --git a/docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md b/docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md
new file mode 100644
index 0000000..d708ae5
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md
@@ -0,0 +1,94 @@
+# Breadcrumb Navigation for Nested Dashboard Pages Design
+
+**Date:** 2026-06-17
+**Status:** Approved design (pending spec review)
+**Branch:** `feat/breadcrumb-nav` (off `main`)
+
+## Problem
+
+The dashboard has only top-level global navigation (sidebar / mobile bottom-tabs →
+Overview, Events, Settings). Once an organizer drills into an event's nested pages
+(`/dashboard/events/[eventId]` and its `attendees` / `configure` / `engine` children),
+there is **no upward or contextual navigation**: no breadcrumb trail and no "back to this
+event" link. The only ways back to the specific event are the browser back button or the
+sidebar (which lands on the top-level Events list, losing context). The Settings → Guide
+page is the lone exception, with an ad-hoc `← Back to Settings` link.
+
+## Goals
+
+- Every nested dashboard page shows where it is and lets the user climb back to its parent(s).
+- One reusable, accessible, responsive breadcrumb pattern across the app.
+- Minimal, low-risk change: a presentational component dropped onto each nested page.
+
+## Non-Goals
+
+- Wizard-style Previous/Next stepping through the setup flow (explicitly deferred).
+- Any change to the global sidebar / mobile tab bar.
+- Navigation on the public attendee pages (`/join/[slug]`, `/results/[allocationId]`) — these
+  are standalone landing pages and stay as-is.
+
+## Components
+
+### 1. `components/layout/breadcrumb.tsx` (new) — generic, presentational
+- Props: `items: { label: string; href?: string }[]`.
+- Renders `<nav aria-label="Breadcrumb">` containing an ordered list. Items with an `href`
+  render as Next `<Link>`s (`text-muted-foreground hover:text-foreground`); the **last** item
+  renders as plain text with `aria-current="page"` (muted, not a link) regardless of whether it
+  has an `href`.
+- Segments separated by a `ChevronRight` icon (lucide). Container is
+  `flex flex-wrap items-center gap-1 text-sm` so it wraps and never overflows on small screens.
+- Pure/presentational — no data fetching. Independently testable.
+
+### 2. `components/layout/event-breadcrumb.tsx` (new) — client wrapper
+- `"use client"`. Props: `{ eventId: string; current?: string }`.
+- Calls the existing `useEvent(eventId)` SWR hook to read the event title (already cached on
+  these pages — no additional network request in practice).
+- Builds the items array and renders `<Breadcrumb>`:
+  - Always starts with `{ label: "Events", href: "/dashboard/events" }`.
+  - Then the event: `{ label: title, href: "/dashboard/events/{eventId}" }`.
+  - If `current` is provided, appends `{ label: current }` as the leaf (the event segment stays
+    a link). If `current` is omitted, the event segment is the leaf (used on the event-detail
+    page itself) — rendered without an `href` so it becomes the `aria-current` leaf.
+- Title fallback while loading or if the event is missing: the literal string `"Event"`.
+
+### 3. Page integrations (one line each, at the top of the page content)
+- `app/dashboard/events/[eventId]/page.tsx` → `<EventBreadcrumb eventId={eventId} />`
+  (leaf = event title).
+- `app/dashboard/events/[eventId]/attendees/page.tsx` → `<EventBreadcrumb eventId={eventId} current="Attendees" />`.
+- `app/dashboard/events/[eventId]/configure/page.tsx` → `<EventBreadcrumb eventId={eventId} current="Configure" />`.
+  (This page is a server component; `EventBreadcrumb` is a client island rendered inside it.)
+- `app/dashboard/events/[eventId]/engine/page.tsx` → `<EventBreadcrumb eventId={eventId} current="Run Allocation" />`.
+- `app/dashboard/settings/guide/page.tsx` → replace the existing `← Back to Settings` link with
+  the **generic** `<Breadcrumb items={[{ label: "Settings", href: "/dashboard/settings" }, { label: "Guide" }]} />`
+  (no event fetch needed).
+
+The breadcrumb renders **above** each page's existing `<h1>` title block; the page titles stay.
+
+## Data Flow
+
+`useEvent(eventId)` (existing `hooks/use-events` SWR hook returning `{ event, isLoading }`) is the
+only data dependency, and only for `EventBreadcrumb`. The generic `Breadcrumb` is pure.
+
+## Error / Edge Handling
+
+- Event still loading or not found → title falls back to `"Event"`; the breadcrumb still renders
+  and remains navigable. The page's own loading/not-found UI is unchanged.
+- Long event titles: the breadcrumb wraps (flex-wrap); no truncation logic needed for v1.
+
+## Testing (Vitest, `tests/components/`)
+
+- `breadcrumb.test.tsx`:
+  - renders every segment's label;
+  - parent items (with `href`) are links pointing to the right path;
+  - the last item is **not** a link and carries `aria-current="page"`.
+- `event-breadcrumb.test.tsx` (mock `@/hooks/use-events` `useEvent`):
+  - shows the event title and the `current` leaf when `current` is set;
+  - when `current` is omitted, the event title is the leaf (no trailing segment);
+  - shows the `"Event"` fallback when `useEvent` returns no event.
+- Gates: `tsc --noEmit`, `npm run lint`, `npm test`, production `build`.
+
+## Out of Scope
+
+- Wizard Previous/Next navigation through Attendees → Configure → Run Allocation.
+- Truncation/ellipsis of very long titles (revisit only if it becomes a problem).
+- Public attendee pages and the global nav.

From 94120250a368e7b4a0cbe60edde454478288e916 Mon Sep 17 00:00:00 2001
From: comwanga <mwanga02717@gmail.com>
Date: Wed, 17 Jun 2026 18:36:19 +0300
Subject: [PATCH 2/7] =?UTF-8?q?docs(spec):=20breadcrumb=20polish=20?=
 =?UTF-8?q?=E2=80=94=20load=20skeleton,=20semantic=20ol,=20wrap=20gap-y?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...2026-06-17-breadcrumb-navigation-design.md | 24 ++++++++++++-------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md b/docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md
index d708ae5..4826ead 100644
--- a/docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md
+++ b/docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md
@@ -30,13 +30,16 @@ page is the lone exception, with an ad-hoc `← Back to Settings` link.
 ## Components
 
 ### 1. `components/layout/breadcrumb.tsx` (new) — generic, presentational
-- Props: `items: { label: string; href?: string }[]`.
-- Renders `<nav aria-label="Breadcrumb">` containing an ordered list. Items with an `href`
-  render as Next `<Link>`s (`text-muted-foreground hover:text-foreground`); the **last** item
-  renders as plain text with `aria-current="page"` (muted, not a link) regardless of whether it
-  has an `href`.
-- Segments separated by a `ChevronRight` icon (lucide). Container is
-  `flex flex-wrap items-center gap-1 text-sm` so it wraps and never overflows on small screens.
+- Props: `items: { label: React.ReactNode; href?: string }[]` (label is `ReactNode` so a
+  caller can pass a skeleton element, not just a string).
+- Renders semantic breadcrumb markup: `<nav aria-label="Breadcrumb"><ol>…</ol></nav>` with one
+  `<li>` per segment. Items with an `href` render as Next `<Link>`s
+  (`text-muted-foreground hover:text-foreground`); the **last** item renders as plain text with
+  `aria-current="page"` (muted, not a link) regardless of whether it has an `href`.
+- Segments separated by a `ChevronRight` icon (lucide), `aria-hidden`, inside the `<ol>` between
+  items. The `<ol>` is `flex flex-wrap items-center gap-x-1.5 gap-y-1 text-sm` — `flex-wrap` so it
+  never overflows on narrow screens, and an explicit **`gap-y-1`** so wrapped lines don't collide
+  vertically.
 - Pure/presentational — no data fetching. Independently testable.
 
 ### 2. `components/layout/event-breadcrumb.tsx` (new) — client wrapper
@@ -49,7 +52,12 @@ page is the lone exception, with an ad-hoc `← Back to Settings` link.
   - If `current` is provided, appends `{ label: current }` as the leaf (the event segment stays
     a link). If `current` is omitted, the event segment is the leaf (used on the event-detail
     page itself) — rendered without an `href` so it becomes the `aria-current` leaf.
-- Title fallback while loading or if the event is missing: the literal string `"Event"`.
+- **Event-title rendering (avoid the SWR flash / layout shift):**
+  - While `useEvent` is loading (`isLoading` true and no cached event), the event segment's
+    `label` is a **skeleton element** — `<span class="inline-block animate-pulse bg-muted rounded h-4 w-24 align-middle" />`
+    — not text, so swapping in the real title doesn't jump the layout.
+  - If loading finished but no event was found, fall back to the literal string `"Event"`.
+  - Otherwise use `event.title`.
 
 ### 3. Page integrations (one line each, at the top of the page content)
 - `app/dashboard/events/[eventId]/page.tsx` → `<EventBreadcrumb eventId={eventId} />`

From 7ac7c04f6ee112b12a99247809e2c31fae22100c Mon Sep 17 00:00:00 2001
From: comwanga <mwanga02717@gmail.com>
Date: Wed, 17 Jun 2026 18:38:39 +0300
Subject: [PATCH 3/7] docs(plan): breadcrumb navigation implementation plan

---
 .../plans/2026-06-17-breadcrumb-navigation.md | 423 ++++++++++++++++++
 1 file changed, 423 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-17-breadcrumb-navigation.md

diff --git a/docs/superpowers/plans/2026-06-17-breadcrumb-navigation.md b/docs/superpowers/plans/2026-06-17-breadcrumb-navigation.md
new file mode 100644
index 0000000..32f42eb
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-17-breadcrumb-navigation.md
@@ -0,0 +1,423 @@
+# Breadcrumb Navigation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add breadcrumb navigation to every nested dashboard page so users can see where they are and climb back to the parent event / section.
+
+**Architecture:** A generic presentational `Breadcrumb` component (semantic `<nav><ol>`, responsive wrap), plus a thin client `EventBreadcrumb` wrapper that reads the event title from the existing `useEvent` SWR hook (with a load skeleton to avoid layout shift). Both are dropped onto the four event pages and the guide page.
+
+**Tech Stack:** Next.js 16 (App Router), React 19, Tailwind v4, lucide-react, Vitest + Testing Library.
+
+**Spec:** `docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md`
+**Branch:** `feat/breadcrumb-nav` (already cut from `main`). Commit messages must NOT include any Co-Authored-By line.
+
+**Verified facts (do not re-derive):**
+- `hooks/use-events.ts` exports `useEvent(eventId: string | null)` returning `{ event, error, isLoading }`. `Event` has `{ id: string; title: string; ... }`.
+- Existing pages and their current top-level structure:
+  - `app/dashboard/events/[eventId]/page.tsx` (client) — has `eventId` (via `use(params)`), renders `<div className="space-y-6">` then a `<div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">` header. Early-returns on loading/not-found before the main return.
+  - `app/dashboard/events/[eventId]/attendees/page.tsx` (client) — has `eventId` and already calls `useEvent(eventId)`; renders `<div className="space-y-6"><div><h1 className="text-xl font-bold">Attendees</h1>…`.
+  - `app/dashboard/events/[eventId]/engine/page.tsx` (client) — has `eventId`; renders `<div className="space-y-6"><div><h1 className="text-xl font-bold">Allocation Engine</h1>…`.
+  - `app/dashboard/events/[eventId]/configure/page.tsx` (**server**, `async`) — has `eventId` (via `await params`); renders `<div className="space-y-6"><div><h1 className="text-xl font-bold">Configure Allocation</h1>…`. A client component (`EventBreadcrumb`) can be rendered inside it.
+  - `app/dashboard/settings/guide/page.tsx` (server) — currently has a `← Back to Settings` `<Link>` (imports `Link`, `ArrowLeft`); `Link`/`ArrowLeft` are used ONLY for that back link. `Image` and `GUIDE_STEPS` are used elsewhere.
+- Frontend tests run from `frontend/`: `npm test` (Vitest). Component tests live in `frontend/tests/components/`. Existing tests mock hooks via `vi.mock`. Heed `frontend/AGENTS.md` (modified Next.js 16) — this task uses only client components + existing hooks, no new Next routing APIs.
+
+---
+
+## File Structure
+
+**Create:**
+- `frontend/components/layout/breadcrumb.tsx` — generic presentational breadcrumb.
+- `frontend/components/layout/event-breadcrumb.tsx` — client wrapper resolving the event title.
+- `frontend/tests/components/breadcrumb.test.tsx`
+- `frontend/tests/components/event-breadcrumb.test.tsx`
+
+**Modify (one-line integrations):**
+- `frontend/app/dashboard/events/[eventId]/page.tsx`
+- `frontend/app/dashboard/events/[eventId]/attendees/page.tsx`
+- `frontend/app/dashboard/events/[eventId]/configure/page.tsx`
+- `frontend/app/dashboard/events/[eventId]/engine/page.tsx`
+- `frontend/app/dashboard/settings/guide/page.tsx` (replaces the ad-hoc back link)
+
+---
+
+## Task 1: Generic `Breadcrumb` component
+
+**Files:**
+- Create: `frontend/components/layout/breadcrumb.tsx`
+- Test: `frontend/tests/components/breadcrumb.test.tsx`
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `frontend/tests/components/breadcrumb.test.tsx`:
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { Breadcrumb } from "@/components/layout/breadcrumb";
+
+describe("Breadcrumb", () => {
+  it("renders all segment labels", () => {
+    render(<Breadcrumb items={[
+      { label: "Events", href: "/dashboard/events" },
+      { label: "My Event", href: "/dashboard/events/1" },
+      { label: "Attendees" },
+    ]} />);
+    expect(screen.getByText("Events")).toBeInTheDocument();
+    expect(screen.getByText("My Event")).toBeInTheDocument();
+    expect(screen.getByText("Attendees")).toBeInTheDocument();
+  });
+
+  it("renders parent items (with href, not last) as links", () => {
+    render(<Breadcrumb items={[
+      { label: "Events", href: "/dashboard/events" },
+      { label: "Attendees" },
+    ]} />);
+    expect(screen.getByRole("link", { name: "Events" })).toHaveAttribute("href", "/dashboard/events");
+  });
+
+  it("renders the last item as the current page, not a link", () => {
+    render(<Breadcrumb items={[
+      { label: "Events", href: "/dashboard/events" },
+      { label: "Attendees" },
+    ]} />);
+    expect(screen.queryByRole("link", { name: "Attendees" })).toBeNull();
+    expect(screen.getByText("Attendees")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("never links the last item even if it has an href", () => {
+    render(<Breadcrumb items={[
+      { label: "Events", href: "/dashboard/events" },
+      { label: "My Event", href: "/dashboard/events/1" },
+    ]} />);
+    expect(screen.queryByRole("link", { name: "My Event" })).toBeNull();
+    expect(screen.getByText("My Event")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("exposes a labelled breadcrumb nav", () => {
+    render(<Breadcrumb items={[{ label: "Events", href: "/dashboard/events" }, { label: "X" }]} />);
+    expect(screen.getByRole("navigation", { name: /breadcrumb/i })).toBeInTheDocument();
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd frontend && npm test -- breadcrumb.test`
+Expected: FAIL — cannot resolve `@/components/layout/breadcrumb`.
+
+- [ ] **Step 3: Implement the component**
+
+Create `frontend/components/layout/breadcrumb.tsx`:
+
+```tsx
+import { Fragment } from "react";
+import Link from "next/link";
+import { ChevronRight } from "lucide-react";
+
+export interface BreadcrumbItem {
+  label: React.ReactNode;
+  href?: string;
+}
+
+export function Breadcrumb({ items }: { items: BreadcrumbItem[] }) {
+  return (
+    <nav aria-label="Breadcrumb">
+      <ol className="flex flex-wrap items-center gap-x-1.5 gap-y-1 text-sm">
+        {items.map((item, i) => {
+          const isLast = i === items.length - 1;
+          return (
+            <Fragment key={i}>
+              <li className="flex items-center">
+                {item.href && !isLast ? (
+                  <Link
+                    href={item.href}
+                    className="text-muted-foreground hover:text-foreground transition-colors"
+                  >
+                    {item.label}
+                  </Link>
+                ) : (
+                  <span
+                    className={isLast ? "font-medium text-foreground" : "text-muted-foreground"}
+                    aria-current={isLast ? "page" : undefined}
+                  >
+                    {item.label}
+                  </span>
+                )}
+              </li>
+              {!isLast && (
+                <li aria-hidden className="flex items-center text-muted-foreground/50">
+                  <ChevronRight className="h-3.5 w-3.5" />
+                </li>
+              )}
+            </Fragment>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd frontend && npm test -- breadcrumb.test`
+Expected: PASS (5 passed).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/components/layout/breadcrumb.tsx frontend/tests/components/breadcrumb.test.tsx
+git commit -m "feat(ui): add generic Breadcrumb component"
+```
+
+---
+
+## Task 2: `EventBreadcrumb` client wrapper
+
+**Files:**
+- Create: `frontend/components/layout/event-breadcrumb.tsx`
+- Test: `frontend/tests/components/event-breadcrumb.test.tsx`
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `frontend/tests/components/event-breadcrumb.test.tsx`:
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
+import { useEvent } from "@/hooks/use-events";
+
+vi.mock("@/hooks/use-events", () => ({ useEvent: vi.fn() }));
+const mockUseEvent = useEvent as unknown as ReturnType<typeof vi.fn>;
+
+beforeEach(() => vi.clearAllMocks());
+
+describe("EventBreadcrumb", () => {
+  it("shows the event title (linked) and the current leaf", () => {
+    mockUseEvent.mockReturnValue({ event: { id: "e1", title: "Hackathon 2026" }, isLoading: false });
+    render(<EventBreadcrumb eventId="e1" current="Attendees" />);
+    expect(screen.getByRole("link", { name: "Hackathon 2026" })).toHaveAttribute("href", "/dashboard/events/e1");
+    expect(screen.getByText("Attendees")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("uses the event title as the leaf when no current is given", () => {
+    mockUseEvent.mockReturnValue({ event: { id: "e1", title: "Hackathon 2026" }, isLoading: false });
+    render(<EventBreadcrumb eventId="e1" />);
+    expect(screen.queryByRole("link", { name: "Hackathon 2026" })).toBeNull();
+    expect(screen.getByText("Hackathon 2026")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("falls back to 'Event' when the event is missing (loaded, none found)", () => {
+    mockUseEvent.mockReturnValue({ event: undefined, isLoading: false });
+    render(<EventBreadcrumb eventId="e1" current="Configure" />);
+    expect(screen.getByText("Event")).toBeInTheDocument();
+    expect(screen.getByText("Configure")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("shows a skeleton placeholder while loading", () => {
+    mockUseEvent.mockReturnValue({ event: undefined, isLoading: true });
+    render(<EventBreadcrumb eventId="e1" current="Attendees" />);
+    expect(screen.getByTestId("breadcrumb-title-skeleton")).toBeInTheDocument();
+    expect(screen.getByText("Attendees")).toBeInTheDocument();
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd frontend && npm test -- event-breadcrumb.test`
+Expected: FAIL — cannot resolve `@/components/layout/event-breadcrumb`.
+
+- [ ] **Step 3: Implement the wrapper**
+
+Create `frontend/components/layout/event-breadcrumb.tsx`:
+
+```tsx
+"use client";
+
+import { useEvent } from "@/hooks/use-events";
+import { Breadcrumb, type BreadcrumbItem } from "@/components/layout/breadcrumb";
+
+export function EventBreadcrumb({ eventId, current }: { eventId: string; current?: string }) {
+  const { event, isLoading } = useEvent(eventId);
+
+  // Avoid the SWR flash / layout shift on a hard refresh: render a fixed-size
+  // skeleton while the title loads, fall back to "Event" if it loaded but is
+  // missing, otherwise the real title.
+  const titleLabel: BreadcrumbItem["label"] =
+    isLoading && !event ? (
+      <span
+        data-testid="breadcrumb-title-skeleton"
+        aria-hidden
+        className="inline-block h-4 w-24 align-middle rounded bg-muted animate-pulse"
+      />
+    ) : (
+      event?.title ?? "Event"
+    );
+
+  const items: BreadcrumbItem[] = [
+    { label: "Events", href: "/dashboard/events" },
+    current
+      ? { label: titleLabel, href: `/dashboard/events/${eventId}` }
+      : { label: titleLabel },
+  ];
+  if (current) items.push({ label: current });
+
+  return <Breadcrumb items={items} />;
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd frontend && npm test -- event-breadcrumb.test`
+Expected: PASS (4 passed).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/components/layout/event-breadcrumb.tsx frontend/tests/components/event-breadcrumb.test.tsx
+git commit -m "feat(ui): add EventBreadcrumb wrapper (title via useEvent + load skeleton)"
+```
+
+---
+
+## Task 3: Integrate breadcrumbs into the pages
+
+**Files (modify):**
+- `frontend/app/dashboard/events/[eventId]/page.tsx`
+- `frontend/app/dashboard/events/[eventId]/attendees/page.tsx`
+- `frontend/app/dashboard/events/[eventId]/configure/page.tsx`
+- `frontend/app/dashboard/events/[eventId]/engine/page.tsx`
+- `frontend/app/dashboard/settings/guide/page.tsx`
+
+> No new unit tests here — these are one-line wirings of already-tested components. Coverage is the `tsc` + `lint` + `build` gates in Step 6.
+
+- [ ] **Step 1: Event detail page**
+
+In `frontend/app/dashboard/events/[eventId]/page.tsx`, add the import after the existing lucide import line (line 16, `import { Users, Settings, ... } from "lucide-react";`):
+
+```tsx
+import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
+```
+
+Then add the breadcrumb as the first child of the main return's outer `<div className="space-y-6">`, immediately before the header `<div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">`:
+
+```tsx
+      <EventBreadcrumb eventId={eventId} />
+```
+
+- [ ] **Step 2: Attendees page**
+
+In `frontend/app/dashboard/events/[eventId]/attendees/page.tsx`, add the import after the existing imports (e.g. after the `Skeleton` import):
+
+```tsx
+import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
+```
+
+Then make it the first child of the outer `<div className="space-y-6">` (before the `<div>` that holds `<h1>Attendees</h1>`):
+
+```tsx
+      <EventBreadcrumb eventId={eventId} current="Attendees" />
+```
+
+- [ ] **Step 3: Configure page**
+
+In `frontend/app/dashboard/events/[eventId]/configure/page.tsx`, add the import after the existing `ConfigForm` import:
+
+```tsx
+import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
+```
+
+Then make it the first child of the outer `<div className="space-y-6">` (before the `<div>` that holds `<h1>Configure Allocation</h1>`):
+
+```tsx
+      <EventBreadcrumb eventId={eventId} current="Configure" />
+```
+
+(`EventBreadcrumb` is a client component; rendering it inside this server component is fine.)
+
+- [ ] **Step 4: Engine page**
+
+In `frontend/app/dashboard/events/[eventId]/engine/page.tsx`, add the import after the existing imports (e.g. after the `ResultsGrid` import):
+
+```tsx
+import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
+```
+
+Then make it the first child of the outer `<div className="space-y-6">` (before the `<div>` that holds `<h1>Allocation Engine</h1>`):
+
+```tsx
+      <EventBreadcrumb eventId={eventId} current="Run Allocation" />
+```
+
+- [ ] **Step 5: Guide page — replace the ad-hoc back link with the shared Breadcrumb**
+
+In `frontend/app/dashboard/settings/guide/page.tsx`:
+
+Replace the first three import lines:
+```tsx
+import Image from "next/image";
+import Link from "next/link";
+import { ArrowLeft } from "lucide-react";
+import { GUIDE_STEPS } from "@/lib/guide-steps";
+```
+with:
+```tsx
+import Image from "next/image";
+import { GUIDE_STEPS } from "@/lib/guide-steps";
+import { Breadcrumb } from "@/components/layout/breadcrumb";
+```
+
+Replace the back-link block:
+```tsx
+        <Link href="/dashboard/settings" className="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground">
+          <ArrowLeft className="h-4 w-4" /> Back to Settings
+        </Link>
+```
+with:
+```tsx
+        <Breadcrumb items={[{ label: "Settings", href: "/dashboard/settings" }, { label: "Guide" }]} />
+```
+
+- [ ] **Step 6: Verify gates**
+
+Run: `cd frontend && npx tsc --noEmit`
+Expected: clean (no output).
+
+Run: `cd frontend && npm run lint`
+Expected: 0 errors. (A pre-existing `react-hooks/incompatible-library` warning in `registration-form.tsx` is unrelated and may remain.)
+
+Run: `cd frontend && npm test`
+Expected: all tests pass (the new breadcrumb tests + existing suite).
+
+Run: `cd frontend && npm run build`
+Expected: build succeeds (all dashboard routes compile).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add "frontend/app/dashboard/events/[eventId]/page.tsx" \
+        "frontend/app/dashboard/events/[eventId]/attendees/page.tsx" \
+        "frontend/app/dashboard/events/[eventId]/configure/page.tsx" \
+        "frontend/app/dashboard/events/[eventId]/engine/page.tsx" \
+        frontend/app/dashboard/settings/guide/page.tsx
+git commit -m "feat(ui): breadcrumbs on event pages + guide"
+```
+
+---
+
+## Final verification (after all tasks)
+
+- [ ] `cd frontend && npx tsc --noEmit && npm run lint && npm test && npm run build` → all green.
+- [ ] Manual sanity (optional): on a nested page (e.g. `…/engine`), the breadcrumb reads `Events / {title} / Run Allocation`; clicking `{title}` returns to the event, clicking `Events` returns to the list; at 360px width the trail wraps without overflow or vertical collision.
+- [ ] Then use **superpowers:finishing-a-development-branch** to open the PR to `main`.
+
+---
+
+## Self-Review notes (plan author)
+
+- **Spec coverage:** generic `Breadcrumb` with semantic `<nav><ol>`, `flex-wrap` + `gap-y-1`, last-item `aria-current` (Task 1); `EventBreadcrumb` reading `useEvent` with **load skeleton** + `"Event"` fallback + optional `current` leaf (Task 2); integration on all four event pages + guide replacement (Task 3). All three polish notes are implemented: skeleton-on-load (Task 2 Step 3), semantic `<ol>` (Task 1 Step 3), `gap-x-1.5 gap-y-1` wrap (Task 1 Step 3).
+- **Type consistency:** `BreadcrumbItem { label: React.ReactNode; href?: string }` defined in Task 1 and imported/used in Task 2; `EventBreadcrumb({ eventId, current? })` props match every call site in Task 3; skeleton `data-testid="breadcrumb-title-skeleton"` matches the Task 2 test.
+- **Placeholder scan:** none — every code step is complete.
+- **Privacy/scope:** no public pages or global nav touched; no backend changes.

From 35f1c68f5f9f2072788d249bbdb64a8f8fc74160 Mon Sep 17 00:00:00 2001
From: comwanga <mwanga02717@gmail.com>
Date: Wed, 17 Jun 2026 18:48:02 +0300
Subject: [PATCH 4/7] docs(spec,plan): pure EventBreadcrumb + Auto variant,
 Allocation label, decline icon field

---
 .../plans/2026-06-17-breadcrumb-navigation.md | 147 +++++++++++-------
 ...2026-06-17-breadcrumb-navigation-design.md |  85 ++++++----
 2 files changed, 151 insertions(+), 81 deletions(-)

diff --git a/docs/superpowers/plans/2026-06-17-breadcrumb-navigation.md b/docs/superpowers/plans/2026-06-17-breadcrumb-navigation.md
index 32f42eb..4d22fcf 100644
--- a/docs/superpowers/plans/2026-06-17-breadcrumb-navigation.md
+++ b/docs/superpowers/plans/2026-06-17-breadcrumb-navigation.md
@@ -172,12 +172,16 @@ git commit -m "feat(ui): add generic Breadcrumb component"
 
 ---
 
-## Task 2: `EventBreadcrumb` client wrapper
+## Task 2: Event breadcrumb variants (`EventBreadcrumb` pure + `EventBreadcrumbAuto` self-resolving)
 
 **Files:**
 - Create: `frontend/components/layout/event-breadcrumb.tsx`
 - Test: `frontend/tests/components/event-breadcrumb.test.tsx`
 
+Two variants share a private item-builder + skeleton: a **pure** `EventBreadcrumb` (the page
+passes the already-loaded `title`) and a **self-resolving** `EventBreadcrumbAuto` (reads the
+title via `useEvent`, for pages that don't otherwise load the event).
+
 - [ ] **Step 1: Write the failing tests**
 
 Create `frontend/tests/components/event-breadcrumb.test.tsx`:
@@ -185,7 +189,7 @@ Create `frontend/tests/components/event-breadcrumb.test.tsx`:
 ```tsx
 import { render, screen } from "@testing-library/react";
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
+import { EventBreadcrumb, EventBreadcrumbAuto } from "@/components/layout/event-breadcrumb";
 import { useEvent } from "@/hooks/use-events";
 
 vi.mock("@/hooks/use-events", () => ({ useEvent: vi.fn() }));
@@ -193,33 +197,45 @@ const mockUseEvent = useEvent as unknown as ReturnType<typeof vi.fn>;
 
 beforeEach(() => vi.clearAllMocks());
 
-describe("EventBreadcrumb", () => {
-  it("shows the event title (linked) and the current leaf", () => {
-    mockUseEvent.mockReturnValue({ event: { id: "e1", title: "Hackathon 2026" }, isLoading: false });
-    render(<EventBreadcrumb eventId="e1" current="Attendees" />);
+describe("EventBreadcrumb (pure)", () => {
+  it("links the title and marks the current leaf", () => {
+    render(<EventBreadcrumb eventId="e1" title="Hackathon 2026" current="Attendees" />);
     expect(screen.getByRole("link", { name: "Hackathon 2026" })).toHaveAttribute("href", "/dashboard/events/e1");
     expect(screen.getByText("Attendees")).toHaveAttribute("aria-current", "page");
   });
 
-  it("uses the event title as the leaf when no current is given", () => {
-    mockUseEvent.mockReturnValue({ event: { id: "e1", title: "Hackathon 2026" }, isLoading: false });
-    render(<EventBreadcrumb eventId="e1" />);
+  it("uses the title as the leaf when no current is given", () => {
+    render(<EventBreadcrumb eventId="e1" title="Hackathon 2026" />);
     expect(screen.queryByRole("link", { name: "Hackathon 2026" })).toBeNull();
     expect(screen.getByText("Hackathon 2026")).toHaveAttribute("aria-current", "page");
   });
 
-  it("falls back to 'Event' when the event is missing (loaded, none found)", () => {
-    mockUseEvent.mockReturnValue({ event: undefined, isLoading: false });
-    render(<EventBreadcrumb eventId="e1" current="Configure" />);
-    expect(screen.getByText("Event")).toBeInTheDocument();
+  it("shows a skeleton when title is undefined", () => {
+    render(<EventBreadcrumb eventId="e1" current="Attendees" />);
+    expect(screen.getByTestId("breadcrumb-title-skeleton")).toBeInTheDocument();
+    expect(screen.getByText("Attendees")).toBeInTheDocument();
+  });
+});
+
+describe("EventBreadcrumbAuto (self-resolving)", () => {
+  it("resolves the title and marks the current leaf", () => {
+    mockUseEvent.mockReturnValue({ event: { id: "e1", title: "Hackathon 2026" }, isLoading: false });
+    render(<EventBreadcrumbAuto eventId="e1" current="Configure" />);
+    expect(screen.getByRole("link", { name: "Hackathon 2026" })).toHaveAttribute("href", "/dashboard/events/e1");
     expect(screen.getByText("Configure")).toHaveAttribute("aria-current", "page");
   });
 
-  it("shows a skeleton placeholder while loading", () => {
+  it("shows a skeleton while loading", () => {
     mockUseEvent.mockReturnValue({ event: undefined, isLoading: true });
-    render(<EventBreadcrumb eventId="e1" current="Attendees" />);
+    render(<EventBreadcrumbAuto eventId="e1" current="Allocation" />);
     expect(screen.getByTestId("breadcrumb-title-skeleton")).toBeInTheDocument();
-    expect(screen.getByText("Attendees")).toBeInTheDocument();
+    expect(screen.getByText("Allocation")).toBeInTheDocument();
+  });
+
+  it("falls back to 'Event' when loaded with no event", () => {
+    mockUseEvent.mockReturnValue({ event: undefined, isLoading: false });
+    render(<EventBreadcrumbAuto eventId="e1" current="Configure" />);
+    expect(screen.getByText("Event")).toBeInTheDocument();
   });
 });
 ```
@@ -229,7 +245,7 @@ describe("EventBreadcrumb", () => {
 Run: `cd frontend && npm test -- event-breadcrumb.test`
 Expected: FAIL — cannot resolve `@/components/layout/event-breadcrumb`.
 
-- [ ] **Step 3: Implement the wrapper**
+- [ ] **Step 3: Implement both variants**
 
 Create `frontend/components/layout/event-breadcrumb.tsx`:
 
@@ -239,23 +255,20 @@ Create `frontend/components/layout/event-breadcrumb.tsx`:
 import { useEvent } from "@/hooks/use-events";
 import { Breadcrumb, type BreadcrumbItem } from "@/components/layout/breadcrumb";
 
-export function EventBreadcrumb({ eventId, current }: { eventId: string; current?: string }) {
-  const { event, isLoading } = useEvent(eventId);
-
-  // Avoid the SWR flash / layout shift on a hard refresh: render a fixed-size
-  // skeleton while the title loads, fall back to "Event" if it loaded but is
-  // missing, otherwise the real title.
-  const titleLabel: BreadcrumbItem["label"] =
-    isLoading && !event ? (
-      <span
-        data-testid="breadcrumb-title-skeleton"
-        aria-hidden
-        className="inline-block h-4 w-24 align-middle rounded bg-muted animate-pulse"
-      />
-    ) : (
-      event?.title ?? "Event"
-    );
-
+// Fixed-size placeholder so swapping in the real title never shifts the layout.
+const titleSkeleton = (
+  <span
+    data-testid="breadcrumb-title-skeleton"
+    aria-hidden
+    className="inline-block h-4 w-24 align-middle rounded bg-muted animate-pulse"
+  />
+);
+
+function buildItems(
+  eventId: string,
+  titleLabel: BreadcrumbItem["label"],
+  current?: string,
+): BreadcrumbItem[] {
   const items: BreadcrumbItem[] = [
     { label: "Events", href: "/dashboard/events" },
     current
@@ -263,21 +276,50 @@ export function EventBreadcrumb({ eventId, current }: { eventId: string; current
       : { label: titleLabel },
   ];
   if (current) items.push({ label: current });
+  return items;
+}
+
+// Pure presentation: the page supplies the title it already loaded. Renders a
+// skeleton until `title` is defined (e.g. a client page's first paint).
+export function EventBreadcrumb({
+  eventId,
+  title,
+  current,
+}: {
+  eventId: string;
+  title?: string;
+  current?: string;
+}) {
+  return <Breadcrumb items={buildItems(eventId, title ?? titleSkeleton, current)} />;
+}
 
-  return <Breadcrumb items={items} />;
+// Self-resolving: for pages that don't otherwise load the event (the engine
+// page and the server-rendered configure page). Skeleton while loading; "Event"
+// only as a rare loaded-but-missing fallback (the page itself 404s then).
+export function EventBreadcrumbAuto({
+  eventId,
+  current,
+}: {
+  eventId: string;
+  current?: string;
+}) {
+  const { event, isLoading } = useEvent(eventId);
+  const titleLabel: BreadcrumbItem["label"] =
+    isLoading && !event ? titleSkeleton : (event?.title ?? "Event");
+  return <Breadcrumb items={buildItems(eventId, titleLabel, current)} />;
 }
 ```
 
 - [ ] **Step 4: Run tests to verify they pass**
 
 Run: `cd frontend && npm test -- event-breadcrumb.test`
-Expected: PASS (4 passed).
+Expected: PASS (6 passed).
 
 - [ ] **Step 5: Commit**
 
 ```bash
 git add frontend/components/layout/event-breadcrumb.tsx frontend/tests/components/event-breadcrumb.test.tsx
-git commit -m "feat(ui): add EventBreadcrumb wrapper (title via useEvent + load skeleton)"
+git commit -m "feat(ui): add EventBreadcrumb (pure) + EventBreadcrumbAuto (self-resolving)"
 ```
 
 ---
@@ -293,7 +335,7 @@ git commit -m "feat(ui): add EventBreadcrumb wrapper (title via useEvent + load
 
 > No new unit tests here — these are one-line wirings of already-tested components. Coverage is the `tsc` + `lint` + `build` gates in Step 6.
 
-- [ ] **Step 1: Event detail page**
+- [ ] **Step 1: Event detail page** (has `event` post-guard → pure variant with `title`)
 
 In `frontend/app/dashboard/events/[eventId]/page.tsx`, add the import after the existing lucide import line (line 16, `import { Users, Settings, ... } from "lucide-react";`):
 
@@ -301,13 +343,13 @@ In `frontend/app/dashboard/events/[eventId]/page.tsx`, add the import after the
 import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
 ```
 
-Then add the breadcrumb as the first child of the main return's outer `<div className="space-y-6">`, immediately before the header `<div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">`:
+Then add the breadcrumb as the first child of the main return's outer `<div className="space-y-6">`, immediately before the header `<div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">`. `event` is guaranteed defined here (the page early-returns while loading / not-found):
 
 ```tsx
-      <EventBreadcrumb eventId={eventId} />
+      <EventBreadcrumb eventId={eventId} title={event.title} />
 ```
 
-- [ ] **Step 2: Attendees page**
+- [ ] **Step 2: Attendees page** (already has `useEvent` → pure variant; `event?.title` may be undefined on first paint → skeleton)
 
 In `frontend/app/dashboard/events/[eventId]/attendees/page.tsx`, add the import after the existing imports (e.g. after the `Skeleton` import):
 
@@ -318,37 +360,37 @@ import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
 Then make it the first child of the outer `<div className="space-y-6">` (before the `<div>` that holds `<h1>Attendees</h1>`):
 
 ```tsx
-      <EventBreadcrumb eventId={eventId} current="Attendees" />
+      <EventBreadcrumb eventId={eventId} title={event?.title} current="Attendees" />
 ```
 
-- [ ] **Step 3: Configure page**
+- [ ] **Step 3: Configure page** (server component, loads no event → self-resolving `Auto` variant)
 
 In `frontend/app/dashboard/events/[eventId]/configure/page.tsx`, add the import after the existing `ConfigForm` import:
 
 ```tsx
-import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
+import { EventBreadcrumbAuto } from "@/components/layout/event-breadcrumb";
 ```
 
 Then make it the first child of the outer `<div className="space-y-6">` (before the `<div>` that holds `<h1>Configure Allocation</h1>`):
 
 ```tsx
-      <EventBreadcrumb eventId={eventId} current="Configure" />
+      <EventBreadcrumbAuto eventId={eventId} current="Configure" />
 ```
 
-(`EventBreadcrumb` is a client component; rendering it inside this server component is fine.)
+(`EventBreadcrumbAuto` is a client component; rendering it inside this server component is fine.)
 
-- [ ] **Step 4: Engine page**
+- [ ] **Step 4: Engine page** (does not load the event → self-resolving `Auto` variant; leaf noun "Allocation")
 
 In `frontend/app/dashboard/events/[eventId]/engine/page.tsx`, add the import after the existing imports (e.g. after the `ResultsGrid` import):
 
 ```tsx
-import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
+import { EventBreadcrumbAuto } from "@/components/layout/event-breadcrumb";
 ```
 
 Then make it the first child of the outer `<div className="space-y-6">` (before the `<div>` that holds `<h1>Allocation Engine</h1>`):
 
 ```tsx
-      <EventBreadcrumb eventId={eventId} current="Run Allocation" />
+      <EventBreadcrumbAuto eventId={eventId} current="Allocation" />
 ```
 
 - [ ] **Step 5: Guide page — replace the ad-hoc back link with the shared Breadcrumb**
@@ -410,14 +452,15 @@ git commit -m "feat(ui): breadcrumbs on event pages + guide"
 ## Final verification (after all tasks)
 
 - [ ] `cd frontend && npx tsc --noEmit && npm run lint && npm test && npm run build` → all green.
-- [ ] Manual sanity (optional): on a nested page (e.g. `…/engine`), the breadcrumb reads `Events / {title} / Run Allocation`; clicking `{title}` returns to the event, clicking `Events` returns to the list; at 360px width the trail wraps without overflow or vertical collision.
+- [ ] Manual sanity (optional): on a nested page (e.g. `…/engine`), the breadcrumb reads `Events / {title} / Allocation`; clicking `{title}` returns to the event, clicking `Events` returns to the list; at 360px width the trail wraps without overflow or vertical collision.
 - [ ] Then use **superpowers:finishing-a-development-branch** to open the PR to `main`.
 
 ---
 
 ## Self-Review notes (plan author)
 
-- **Spec coverage:** generic `Breadcrumb` with semantic `<nav><ol>`, `flex-wrap` + `gap-y-1`, last-item `aria-current` (Task 1); `EventBreadcrumb` reading `useEvent` with **load skeleton** + `"Event"` fallback + optional `current` leaf (Task 2); integration on all four event pages + guide replacement (Task 3). All three polish notes are implemented: skeleton-on-load (Task 2 Step 3), semantic `<ol>` (Task 1 Step 3), `gap-x-1.5 gap-y-1` wrap (Task 1 Step 3).
-- **Type consistency:** `BreadcrumbItem { label: React.ReactNode; href?: string }` defined in Task 1 and imported/used in Task 2; `EventBreadcrumb({ eventId, current? })` props match every call site in Task 3; skeleton `data-testid="breadcrumb-title-skeleton"` matches the Task 2 test.
+- **Spec coverage:** generic `Breadcrumb` with semantic `<nav><ol>`, `flex-wrap` + `gap-y-1`, last-item `aria-current` (Task 1); **pure** `EventBreadcrumb({ eventId, title?, current? })` (skeleton when title undefined) + **self-resolving** `EventBreadcrumbAuto({ eventId, current? })` (load skeleton + `"Event"` fallback) (Task 2); integration — detail/attendees use the pure variant fed by their own event data, engine/configure use `Auto` (Task 3); guide uses the generic `Breadcrumb`.
+- **Review-driven adjustments folded in:** breadcrumbs are pure presentation where the page already has the title (detail, attendees) — no breadcrumb-initiated fetch; `Auto` self-resolves only where there's no other source (engine has no event load, configure is a server component). Skeleton (not a "Event"→title text swap) prevents flicker. Leaf noun is **"Allocation"** (not "Run Allocation"). No `icon` field — `label: ReactNode` already supports icon+text (YAGNI). Page `<h1>`s are preserved as primary headings.
+- **Type consistency:** `BreadcrumbItem { label: React.ReactNode; href?: string }` defined in Task 1, imported in Task 2; `EventBreadcrumb` takes `title?` (string), `EventBreadcrumbAuto` takes no title — call sites in Task 3 match (detail/attendees pass `title=`, engine/configure pass none); skeleton `data-testid="breadcrumb-title-skeleton"` matches both the pure and Auto tests.
 - **Placeholder scan:** none — every code step is complete.
 - **Privacy/scope:** no public pages or global nav touched; no backend changes.
diff --git a/docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md b/docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md
index 4826ead..cd7c33b 100644
--- a/docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md
+++ b/docs/superpowers/specs/2026-06-17-breadcrumb-navigation-design.md
@@ -30,8 +30,9 @@ page is the lone exception, with an ad-hoc `← Back to Settings` link.
 ## Components
 
 ### 1. `components/layout/breadcrumb.tsx` (new) — generic, presentational
-- Props: `items: { label: React.ReactNode; href?: string }[]` (label is `ReactNode` so a
-  caller can pass a skeleton element, not just a string).
+- Props: `items: { label: React.ReactNode; href?: string }[]`. `label` is `ReactNode` so a
+  caller can pass a skeleton element **or an icon + text** (e.g. `<><Settings/> Settings</>`) —
+  no separate `icon` field is needed (would be redundant API surface; YAGNI).
 - Renders semantic breadcrumb markup: `<nav aria-label="Breadcrumb"><ol>…</ol></nav>` with one
   `<li>` per segment. Items with an `href` render as Next `<Link>`s
   (`text-muted-foreground hover:text-foreground`); the **last** item renders as plain text with
@@ -42,35 +43,57 @@ page is the lone exception, with an ad-hoc `← Back to Settings` link.
   vertically.
 - Pure/presentational — no data fetching. Independently testable.
 
-### 2. `components/layout/event-breadcrumb.tsx` (new) — client wrapper
-- `"use client"`. Props: `{ eventId: string; current?: string }`.
-- Calls the existing `useEvent(eventId)` SWR hook to read the event title (already cached on
-  these pages — no additional network request in practice).
-- Builds the items array and renders `<Breadcrumb>`:
-  - Always starts with `{ label: "Events", href: "/dashboard/events" }`.
-  - Then the event: `{ label: title, href: "/dashboard/events/{eventId}" }`.
-  - If `current` is provided, appends `{ label: current }` as the leaf (the event segment stays
-    a link). If `current` is omitted, the event segment is the leaf (used on the event-detail
-    page itself) — rendered without an `href` so it becomes the `aria-current` leaf.
-- **Event-title rendering (avoid the SWR flash / layout shift):**
-  - While `useEvent` is loading (`isLoading` true and no cached event), the event segment's
-    `label` is a **skeleton element** — `<span class="inline-block animate-pulse bg-muted rounded h-4 w-24 align-middle" />`
-    — not text, so swapping in the real title doesn't jump the layout.
-  - If loading finished but no event was found, fall back to the literal string `"Event"`.
-  - Otherwise use `event.title`.
+### 2. `components/layout/event-breadcrumb.tsx` (new) — two event variants
+
+Breadcrumbs are presentation-first: pages that already hold the event title feed it in
+directly (no breadcrumb-initiated fetch). Only the two pages that have no other source for
+the title self-resolve it. Both variants share private `items(...)` and skeleton helpers and
+render the generic `<Breadcrumb>`.
+
+Shared item-building rule:
+- Always starts with `{ label: "Events", href: "/dashboard/events" }`.
+- Then the event segment. If `current` is provided, the event segment is a link
+  (`href: "/dashboard/events/{eventId}"`) and `{ label: current }` is appended as the leaf.
+  If `current` is omitted, the event segment is the leaf (used on the event-detail page) —
+  no `href`, so the generic component marks it `aria-current`.
+- The event-title label is a **skeleton element**
+  (`<span data-testid="breadcrumb-title-skeleton" aria-hidden class="inline-block h-4 w-24 align-middle rounded bg-muted animate-pulse" />`)
+  whenever the title is unavailable, so swapping in the real title never does a text-swap
+  flicker / layout jump.
+
+- **`EventBreadcrumb({ eventId, title?, current? })` — pure (no data fetching).**
+  Used by pages that already loaded the event (**event detail**, **attendees**). Renders the
+  skeleton when `title` is `undefined` (e.g. attendees' first paint before its `useEvent`
+  resolves), the real `title` otherwise. This is the component that satisfies "breadcrumbs are
+  pure presentation" for the pages where the data is already in hand.
+
+- **`EventBreadcrumbAuto({ eventId, current? })` — self-resolving (`"use client"`).**
+  Used only by the two pages that don't otherwise load the event: the **engine** page (loads
+  participants/allocations, not the event) and the **configure** page (a server component that
+  loads nothing). Calls `useEvent(eventId)`; shows the skeleton while `isLoading`, falls back to
+  the literal `"Event"` only if loading finished with no event (rare — the page itself 404s),
+  else `event.title`. Self-resolving here is the pragmatic choice: forcing purity would mean a
+  server-side fetch in Configure (extra round-trip + auth coupling) or a title-only fetch in
+  Engine — both strictly worse than this small encapsulated reader.
 
 ### 3. Page integrations (one line each, at the top of the page content)
-- `app/dashboard/events/[eventId]/page.tsx` → `<EventBreadcrumb eventId={eventId} />`
-  (leaf = event title).
-- `app/dashboard/events/[eventId]/attendees/page.tsx` → `<EventBreadcrumb eventId={eventId} current="Attendees" />`.
-- `app/dashboard/events/[eventId]/configure/page.tsx` → `<EventBreadcrumb eventId={eventId} current="Configure" />`.
-  (This page is a server component; `EventBreadcrumb` is a client island rendered inside it.)
-- `app/dashboard/events/[eventId]/engine/page.tsx` → `<EventBreadcrumb eventId={eventId} current="Run Allocation" />`.
+- `app/dashboard/events/[eventId]/page.tsx` (has `event` post-guard) →
+  `<EventBreadcrumb eventId={eventId} title={event.title} />` (leaf = event title).
+- `app/dashboard/events/[eventId]/attendees/page.tsx` (has `useEvent`) →
+  `<EventBreadcrumb eventId={eventId} title={event?.title} current="Attendees" />`.
+- `app/dashboard/events/[eventId]/engine/page.tsx` (no event load) →
+  `<EventBreadcrumbAuto eventId={eventId} current="Allocation" />`.
+- `app/dashboard/events/[eventId]/configure/page.tsx` (server component) →
+  `<EventBreadcrumbAuto eventId={eventId} current="Configure" />` (a client island inside the
+  server page).
 - `app/dashboard/settings/guide/page.tsx` → replace the existing `← Back to Settings` link with
   the **generic** `<Breadcrumb items={[{ label: "Settings", href: "/dashboard/settings" }, { label: "Guide" }]} />`
   (no event fetch needed).
 
-The breadcrumb renders **above** each page's existing `<h1>` title block; the page titles stay.
+The breadcrumb renders **above** each page's existing `<h1>` title block; **the page `<h1>`
+remains the primary heading — it is not shrunk or removed because the breadcrumb shows the title.**
+The leaf segment uses the noun **"Allocation"** (not "Run Allocation") for consistency with
+`Attendees` / `Configure` / `Guide`.
 
 ## Data Flow
 
@@ -89,10 +112,14 @@ only data dependency, and only for `EventBreadcrumb`. The generic `Breadcrumb` i
   - renders every segment's label;
   - parent items (with `href`) are links pointing to the right path;
   - the last item is **not** a link and carries `aria-current="page"`.
-- `event-breadcrumb.test.tsx` (mock `@/hooks/use-events` `useEvent`):
-  - shows the event title and the `current` leaf when `current` is set;
-  - when `current` is omitted, the event title is the leaf (no trailing segment);
-  - shows the `"Event"` fallback when `useEvent` returns no event.
+- `event-breadcrumb.test.tsx`:
+  - **`EventBreadcrumb` (pure, no mock needed):** with `title` set + `current`, the title is a
+    link and `current` is the `aria-current` leaf; with `title` set and no `current`, the title
+    is the leaf; with `title` undefined, the skeleton (`data-testid="breadcrumb-title-skeleton"`)
+    renders.
+  - **`EventBreadcrumbAuto` (mock `@/hooks/use-events` `useEvent`):** shows the resolved title +
+    `current` leaf when loaded; shows the skeleton while `isLoading`; falls back to `"Event"` when
+    loaded with no event.
 - Gates: `tsc --noEmit`, `npm run lint`, `npm test`, production `build`.
 
 ## Out of Scope

From 66541ce8a4a2a91747727a424ccf24949706afae Mon Sep 17 00:00:00 2001
From: comwanga <mwanga02717@gmail.com>
Date: Wed, 17 Jun 2026 18:52:43 +0300
Subject: [PATCH 5/7] feat(ui): add generic Breadcrumb component

---
 frontend/components/layout/breadcrumb.tsx     | 46 ++++++++++++++++++
 frontend/tests/components/breadcrumb.test.tsx | 47 +++++++++++++++++++
 2 files changed, 93 insertions(+)
 create mode 100644 frontend/components/layout/breadcrumb.tsx
 create mode 100644 frontend/tests/components/breadcrumb.test.tsx

diff --git a/frontend/components/layout/breadcrumb.tsx b/frontend/components/layout/breadcrumb.tsx
new file mode 100644
index 0000000..28c5563
--- /dev/null
+++ b/frontend/components/layout/breadcrumb.tsx
@@ -0,0 +1,46 @@
+import { Fragment } from "react";
+import Link from "next/link";
+import { ChevronRight } from "lucide-react";
+
+export interface BreadcrumbItem {
+  label: React.ReactNode;
+  href?: string;
+}
+
+export function Breadcrumb({ items }: { items: BreadcrumbItem[] }) {
+  return (
+    <nav aria-label="Breadcrumb">
+      <ol className="flex flex-wrap items-center gap-x-1.5 gap-y-1 text-sm">
+        {items.map((item, i) => {
+          const isLast = i === items.length - 1;
+          return (
+            <Fragment key={i}>
+              <li className="flex items-center">
+                {item.href && !isLast ? (
+                  <Link
+                    href={item.href}
+                    className="text-muted-foreground hover:text-foreground transition-colors"
+                  >
+                    {item.label}
+                  </Link>
+                ) : (
+                  <span
+                    className={isLast ? "font-medium text-foreground" : "text-muted-foreground"}
+                    aria-current={isLast ? "page" : undefined}
+                  >
+                    {item.label}
+                  </span>
+                )}
+              </li>
+              {!isLast && (
+                <li aria-hidden className="flex items-center text-muted-foreground/50">
+                  <ChevronRight className="h-3.5 w-3.5" />
+                </li>
+              )}
+            </Fragment>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}
diff --git a/frontend/tests/components/breadcrumb.test.tsx b/frontend/tests/components/breadcrumb.test.tsx
new file mode 100644
index 0000000..39ec4a1
--- /dev/null
+++ b/frontend/tests/components/breadcrumb.test.tsx
@@ -0,0 +1,47 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { Breadcrumb } from "@/components/layout/breadcrumb";
+
+describe("Breadcrumb", () => {
+  it("renders all segment labels", () => {
+    render(<Breadcrumb items={[
+      { label: "Events", href: "/dashboard/events" },
+      { label: "My Event", href: "/dashboard/events/1" },
+      { label: "Attendees" },
+    ]} />);
+    expect(screen.getByText("Events")).toBeInTheDocument();
+    expect(screen.getByText("My Event")).toBeInTheDocument();
+    expect(screen.getByText("Attendees")).toBeInTheDocument();
+  });
+
+  it("renders parent items (with href, not last) as links", () => {
+    render(<Breadcrumb items={[
+      { label: "Events", href: "/dashboard/events" },
+      { label: "Attendees" },
+    ]} />);
+    expect(screen.getByRole("link", { name: "Events" })).toHaveAttribute("href", "/dashboard/events");
+  });
+
+  it("renders the last item as the current page, not a link", () => {
+    render(<Breadcrumb items={[
+      { label: "Events", href: "/dashboard/events" },
+      { label: "Attendees" },
+    ]} />);
+    expect(screen.queryByRole("link", { name: "Attendees" })).toBeNull();
+    expect(screen.getByText("Attendees")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("never links the last item even if it has an href", () => {
+    render(<Breadcrumb items={[
+      { label: "Events", href: "/dashboard/events" },
+      { label: "My Event", href: "/dashboard/events/1" },
+    ]} />);
+    expect(screen.queryByRole("link", { name: "My Event" })).toBeNull();
+    expect(screen.getByText("My Event")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("exposes a labelled breadcrumb nav", () => {
+    render(<Breadcrumb items={[{ label: "Events", href: "/dashboard/events" }, { label: "X" }]} />);
+    expect(screen.getByRole("navigation", { name: /breadcrumb/i })).toBeInTheDocument();
+  });
+});

From 347b4a1d2f17bdbe4ca1ae84826ec0ef44780d4c Mon Sep 17 00:00:00 2001
From: comwanga <mwanga02717@gmail.com>
Date: Wed, 17 Jun 2026 18:55:37 +0300
Subject: [PATCH 6/7] feat(ui): add EventBreadcrumb (pure) +
 EventBreadcrumbAuto (self-resolving)

---
 .../components/layout/event-breadcrumb.tsx    | 58 +++++++++++++++++++
 .../components/event-breadcrumb.test.tsx      | 51 ++++++++++++++++
 2 files changed, 109 insertions(+)
 create mode 100644 frontend/components/layout/event-breadcrumb.tsx
 create mode 100644 frontend/tests/components/event-breadcrumb.test.tsx

diff --git a/frontend/components/layout/event-breadcrumb.tsx b/frontend/components/layout/event-breadcrumb.tsx
new file mode 100644
index 0000000..2d214a1
--- /dev/null
+++ b/frontend/components/layout/event-breadcrumb.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import { useEvent } from "@/hooks/use-events";
+import { Breadcrumb, type BreadcrumbItem } from "@/components/layout/breadcrumb";
+
+// Fixed-size placeholder so swapping in the real title never shifts the layout.
+const titleSkeleton = (
+  <span
+    data-testid="breadcrumb-title-skeleton"
+    aria-hidden
+    className="inline-block h-4 w-24 align-middle rounded bg-muted animate-pulse"
+  />
+);
+
+function buildItems(
+  eventId: string,
+  titleLabel: BreadcrumbItem["label"],
+  current?: string,
+): BreadcrumbItem[] {
+  const items: BreadcrumbItem[] = [
+    { label: "Events", href: "/dashboard/events" },
+    current
+      ? { label: titleLabel, href: `/dashboard/events/${eventId}` }
+      : { label: titleLabel },
+  ];
+  if (current) items.push({ label: current });
+  return items;
+}
+
+// Pure presentation: the page supplies the title it already loaded. Renders a
+// skeleton until `title` is defined (e.g. a client page's first paint).
+export function EventBreadcrumb({
+  eventId,
+  title,
+  current,
+}: {
+  eventId: string;
+  title?: string;
+  current?: string;
+}) {
+  return <Breadcrumb items={buildItems(eventId, title ?? titleSkeleton, current)} />;
+}
+
+// Self-resolving: for pages that don't otherwise load the event (the engine
+// page and the server-rendered configure page). Skeleton while loading; "Event"
+// only as a rare loaded-but-missing fallback (the page itself 404s then).
+export function EventBreadcrumbAuto({
+  eventId,
+  current,
+}: {
+  eventId: string;
+  current?: string;
+}) {
+  const { event, isLoading } = useEvent(eventId);
+  const titleLabel: BreadcrumbItem["label"] =
+    isLoading && !event ? titleSkeleton : (event?.title ?? "Event");
+  return <Breadcrumb items={buildItems(eventId, titleLabel, current)} />;
+}
diff --git a/frontend/tests/components/event-breadcrumb.test.tsx b/frontend/tests/components/event-breadcrumb.test.tsx
new file mode 100644
index 0000000..5240b12
--- /dev/null
+++ b/frontend/tests/components/event-breadcrumb.test.tsx
@@ -0,0 +1,51 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { EventBreadcrumb, EventBreadcrumbAuto } from "@/components/layout/event-breadcrumb";
+import { useEvent } from "@/hooks/use-events";
+
+vi.mock("@/hooks/use-events", () => ({ useEvent: vi.fn() }));
+const mockUseEvent = useEvent as unknown as ReturnType<typeof vi.fn>;
+
+beforeEach(() => vi.clearAllMocks());
+
+describe("EventBreadcrumb (pure)", () => {
+  it("links the title and marks the current leaf", () => {
+    render(<EventBreadcrumb eventId="e1" title="Hackathon 2026" current="Attendees" />);
+    expect(screen.getByRole("link", { name: "Hackathon 2026" })).toHaveAttribute("href", "/dashboard/events/e1");
+    expect(screen.getByText("Attendees")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("uses the title as the leaf when no current is given", () => {
+    render(<EventBreadcrumb eventId="e1" title="Hackathon 2026" />);
+    expect(screen.queryByRole("link", { name: "Hackathon 2026" })).toBeNull();
+    expect(screen.getByText("Hackathon 2026")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("shows a skeleton when title is undefined", () => {
+    render(<EventBreadcrumb eventId="e1" current="Attendees" />);
+    expect(screen.getByTestId("breadcrumb-title-skeleton")).toBeInTheDocument();
+    expect(screen.getByText("Attendees")).toBeInTheDocument();
+  });
+});
+
+describe("EventBreadcrumbAuto (self-resolving)", () => {
+  it("resolves the title and marks the current leaf", () => {
+    mockUseEvent.mockReturnValue({ event: { id: "e1", title: "Hackathon 2026" }, isLoading: false });
+    render(<EventBreadcrumbAuto eventId="e1" current="Configure" />);
+    expect(screen.getByRole("link", { name: "Hackathon 2026" })).toHaveAttribute("href", "/dashboard/events/e1");
+    expect(screen.getByText("Configure")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("shows a skeleton while loading", () => {
+    mockUseEvent.mockReturnValue({ event: undefined, isLoading: true });
+    render(<EventBreadcrumbAuto eventId="e1" current="Allocation" />);
+    expect(screen.getByTestId("breadcrumb-title-skeleton")).toBeInTheDocument();
+    expect(screen.getByText("Allocation")).toBeInTheDocument();
+  });
+
+  it("falls back to 'Event' when loaded with no event", () => {
+    mockUseEvent.mockReturnValue({ event: undefined, isLoading: false });
+    render(<EventBreadcrumbAuto eventId="e1" current="Configure" />);
+    expect(screen.getByText("Event")).toBeInTheDocument();
+  });
+});

From 5e51cd5db6e0785fa45f7e440cab9f38c9c9ae1e Mon Sep 17 00:00:00 2001
From: comwanga <mwanga02717@gmail.com>
Date: Wed, 17 Jun 2026 19:42:57 +0300
Subject: [PATCH 7/7] feat(ui): breadcrumbs on event pages + guide

---
 frontend/app/dashboard/events/[eventId]/attendees/page.tsx | 2 ++
 frontend/app/dashboard/events/[eventId]/configure/page.tsx | 2 ++
 frontend/app/dashboard/events/[eventId]/engine/page.tsx    | 2 ++
 frontend/app/dashboard/events/[eventId]/page.tsx           | 2 ++
 frontend/app/dashboard/settings/guide/page.tsx             | 7 ++-----
 5 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/frontend/app/dashboard/events/[eventId]/attendees/page.tsx b/frontend/app/dashboard/events/[eventId]/attendees/page.tsx
index 16297bf..a27fe8c 100644
--- a/frontend/app/dashboard/events/[eventId]/attendees/page.tsx
+++ b/frontend/app/dashboard/events/[eventId]/attendees/page.tsx
@@ -5,6 +5,7 @@ import { useEvent } from "@/hooks/use-events";
 import { AttendeesTable } from "@/components/attendees/attendees-table";
 import { QRDisplay } from "@/components/attendees/qr-display";
 import { Skeleton } from "@/components/ui/skeleton";
+import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
 
 export default function AttendeesPage({ params }: { params: Promise<{ eventId: string }> }) {
   const { eventId } = use(params);
@@ -12,6 +13,7 @@ export default function AttendeesPage({ params }: { params: Promise<{ eventId: s
 
   return (
     <div className="space-y-6">
+      <EventBreadcrumb eventId={eventId} title={event?.title} current="Attendees" />
       <div>
         <h1 className="text-xl font-bold">Attendees</h1>
         <p className="text-sm text-muted-foreground">Manage participants and share the registration QR code</p>
diff --git a/frontend/app/dashboard/events/[eventId]/configure/page.tsx b/frontend/app/dashboard/events/[eventId]/configure/page.tsx
index 234a45c..39838ec 100644
--- a/frontend/app/dashboard/events/[eventId]/configure/page.tsx
+++ b/frontend/app/dashboard/events/[eventId]/configure/page.tsx
@@ -1,9 +1,11 @@
 import { ConfigForm } from "@/components/configure/config-form";
+import { EventBreadcrumbAuto } from "@/components/layout/event-breadcrumb";
 
 export default async function ConfigurePage({ params }: { params: Promise<{ eventId: string }> }) {
   const { eventId } = await params;
   return (
     <div className="space-y-6">
+      <EventBreadcrumbAuto eventId={eventId} current="Configure" />
       <div>
         <h1 className="text-xl font-bold">Configure Allocation</h1>
         <p className="text-sm text-muted-foreground">Set balancing weights and role constraints</p>
diff --git a/frontend/app/dashboard/events/[eventId]/engine/page.tsx b/frontend/app/dashboard/events/[eventId]/engine/page.tsx
index 81762dc..916ef43 100644
--- a/frontend/app/dashboard/events/[eventId]/engine/page.tsx
+++ b/frontend/app/dashboard/events/[eventId]/engine/page.tsx
@@ -7,6 +7,7 @@ import { useSession } from "next-auth/react";
 import { fetchAPI } from "@/lib/api";
 import { RunPanel } from "@/components/engine/run-panel";
 import { ResultsGrid } from "@/components/engine/results-grid";
+import { EventBreadcrumbAuto } from "@/components/layout/event-breadcrumb";
 import type { Allocation } from "@/hooks/use-allocation";
 
 export default function EnginePage({ params }: { params: Promise<{ eventId: string }> }) {
@@ -41,6 +42,7 @@ export default function EnginePage({ params }: { params: Promise<{ eventId: stri
 
   return (
     <div className="space-y-6">
+      <EventBreadcrumbAuto eventId={eventId} current="Allocation" />
       <div>
         <h1 className="text-xl font-bold">Allocation Engine</h1>
         <p className="text-sm text-muted-foreground">Generate balanced teams from registered participants</p>
diff --git a/frontend/app/dashboard/events/[eventId]/page.tsx b/frontend/app/dashboard/events/[eventId]/page.tsx
index 2283f62..06b2eb1 100644
--- a/frontend/app/dashboard/events/[eventId]/page.tsx
+++ b/frontend/app/dashboard/events/[eventId]/page.tsx
@@ -14,6 +14,7 @@ import {
   Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle,
 } from "@/components/ui/dialog";
 import { Users, Settings, Zap, ArrowRight, Archive, Trash2, Calendar } from "lucide-react";
+import { EventBreadcrumb } from "@/components/layout/event-breadcrumb";
 
 export default function EventPage({ params }: { params: Promise<{ eventId: string }> }) {
   const { eventId } = use(params);
@@ -77,6 +78,7 @@ export default function EventPage({ params }: { params: Promise<{ eventId: strin
 
   return (
     <div className="space-y-6">
+      <EventBreadcrumb eventId={eventId} title={event.title} />
       <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
         <div>
           <h1 className="text-2xl font-bold tracking-tight">{event.title}</h1>
diff --git a/frontend/app/dashboard/settings/guide/page.tsx b/frontend/app/dashboard/settings/guide/page.tsx
index 6991ffd..81e5455 100644
--- a/frontend/app/dashboard/settings/guide/page.tsx
+++ b/frontend/app/dashboard/settings/guide/page.tsx
@@ -1,15 +1,12 @@
 import Image from "next/image";
-import Link from "next/link";
-import { ArrowLeft } from "lucide-react";
 import { GUIDE_STEPS } from "@/lib/guide-steps";
+import { Breadcrumb } from "@/components/layout/breadcrumb";
 
 export default function GuidePage() {
   return (
     <div className="space-y-8 max-w-3xl">
       <div>
-        <Link href="/dashboard/settings" className="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground">
-          <ArrowLeft className="h-4 w-4" /> Back to Settings
-        </Link>
+        <Breadcrumb items={[{ label: "Settings", href: "/dashboard/settings" }, { label: "Guide" }]} />
         <h1 className="text-2xl font-bold tracking-tight mt-2">How SquadSync works</h1>
         <p className="text-sm text-muted-foreground mt-1">A quick walkthrough from sign-in to published teams.</p>
       </div>