From 08c1ad2c34376f062b2fc0d3e9d7fbf3007f53ee Mon Sep 17 00:00:00 2001
From: Yibei Chen <yibeichan@gmail.com>
Date: Wed, 29 Apr 2026 09:30:33 -0400
Subject: [PATCH 1/3] feat: add Frequently Asked Questions section to home page

Adds an FAQ section below the existing intro and section buttons on
the home page. Maintainers manage the content via a single data file
(data/faq.yaml); a new rn-faq Hugo shortcode renders each entry as
an HTML5 <details> element so accordion semantics, keyboard
operability, and screen-reader announcement come from the browser
without any JS framework.

- data/faq.yaml: 7 starter questions covering what ReproNim is, who
  it's for, getting started, tools, participation, help/office hours,
  and the fellowship. Schema documented in a header comment.
- layouts/shortcodes/rn-faq.html: rendering loop with anchor id
  generation, validation warnings (warnf) for malformed entries,
  scoped styles that honor light/dark themes, and a small inline
  script that opens the targeted entry on hash-based deep links.
- content/_index.md: invokes {{< rn-faq >}} after rn-buttons.
- CONTRIBUTING.md: short pointer to data/faq.yaml for FAQ edits.
- specs/001-faq-section/: full spec, plan, research, data model,
  contract, quickstart, tasks, and quality checklist.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CONTRIBUTING.md                               |   4 +
 content/_index.md                             |   2 +
 data/faq.yaml                                 |  66 ++++++
 layouts/shortcodes/rn-faq.html                | 128 +++++++++++
 .../checklists/requirements.md                |  37 +++
 .../contracts/faq-shortcode.md                | 113 ++++++++++
 specs/001-faq-section/data-model.md           |  75 +++++++
 specs/001-faq-section/plan.md                 |  83 +++++++
 specs/001-faq-section/quickstart.md           |  86 +++++++
 specs/001-faq-section/research.md             | 165 ++++++++++++++
 specs/001-faq-section/spec.md                 | 122 ++++++++++
 specs/001-faq-section/tasks.md                | 211 ++++++++++++++++++
 12 files changed, 1092 insertions(+)
 create mode 100644 data/faq.yaml
 create mode 100644 layouts/shortcodes/rn-faq.html
 create mode 100644 specs/001-faq-section/checklists/requirements.md
 create mode 100644 specs/001-faq-section/contracts/faq-shortcode.md
 create mode 100644 specs/001-faq-section/data-model.md
 create mode 100644 specs/001-faq-section/plan.md
 create mode 100644 specs/001-faq-section/quickstart.md
 create mode 100644 specs/001-faq-section/research.md
 create mode 100644 specs/001-faq-section/spec.md
 create mode 100644 specs/001-faq-section/tasks.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 965698d8..1e48043b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -45,6 +45,10 @@ Every time you add commits to the Pull Request, Netlify will automatically updat
 
 Once approved, a maintainer will merge your PR. If your changes need revision, follow their instructions and update your PR.
 
+## Editing the home page FAQ
+
+The Frequently Asked Questions section on the home page is generated from a single data file: [`data/faq.yaml`](./data/faq.yaml). To add, edit, reorder, or remove a question, edit that file directly via the GitHub web UI (no template or layout changes are needed for ordinary content edits). The file's header comment documents the schema; for a longer walkthrough see [`specs/001-faq-section/quickstart.md`](./specs/001-faq-section/quickstart.md).
+
 ## Local Development
 
 To set up a local development environment:
diff --git a/content/_index.md b/content/_index.md
index 9c9a9855..3decc47e 100644
--- a/content/_index.md
+++ b/content/_index.md
@@ -62,3 +62,5 @@ A national biotechnology development center dedicated to developing tools and se
         subtitle="Why reproducible neuroimaging" 
     >}}
 {{< /rn-buttons >}}
+
+{{< rn-faq >}}
diff --git a/data/faq.yaml b/data/faq.yaml
new file mode 100644
index 00000000..693139f1
--- /dev/null
+++ b/data/faq.yaml
@@ -0,0 +1,66 @@
+# Home page Frequently Asked Questions
+#
+# Each item under `entries:` becomes one expandable question on the home page.
+# Order in this list = order on the page. To add, edit, or remove a question,
+# just edit this file and commit.
+#
+# Schema:
+#   - question: Short question text (plain text, ends with "?").
+#     answer:   |
+#       Multi-line Markdown answer. Use the "|" pipe so newlines and
+#       lists are preserved. Links and **emphasis** work normally.
+#     id:       (optional) explicit URL anchor for deep-linking, e.g.
+#               "fellowship-apply". Use lowercase, kebab-case. If you set
+#               this once, you can later reword the question without
+#               breaking external links to it.
+#
+# Anchors auto-generated from the question (when no `id:` is set) take the
+# form "faq-<slugified-question>", e.g. "faq-how-do-i-get-started". Share
+# https://repronim.org/#faq-how-do-i-get-started to deep-link directly.
+#
+# Detailed maintainer guide: specs/001-faq-section/quickstart.md
+
+entries:
+  - question: What is ReproNim?
+    answer: |
+      ReproNim is a national biotechnology development center dedicated to
+      developing tools and services that increase efficiency, rigor,
+      reproducibility, transparency, and FAIRness in neuroimaging. See the
+      [About page](/about/) for the center's history, team, and mission.
+
+  - question: Who is ReproNim for?
+    answer: |
+      Researchers, students, data managers, and institutions working with
+      neuroimaging data — at any stage of a project. If you produce, share,
+      analyze, or steward MRI/EEG/MEG datasets and want to make that work
+      more reproducible, ReproNim's tools and guidance are aimed at you.
+
+  - question: How do I get started?
+    answer: |
+      The [Getting Started](/resources/getting-started/) page is the best
+      entry point. From there you can branch into specific
+      [tools](/resources/tools/) and [tutorials](/resources/) depending on
+      what you're trying to do.
+
+  - question: Where can I find ReproNim's tools?
+    answer: |
+      All recommended tools are catalogued on the
+      [Tools page](/resources/tools/), with links to documentation, tutorials,
+      and community help forums for each one.
+
+  - question: How can I participate in the ReproNim community?
+    answer: |
+      Visit the [Participate page](/participate/) for current opportunities —
+      working groups, hackathons, webinars, and ways to contribute to ongoing
+      projects.
+
+  - question: Where can I get help or attend office hours?
+    answer: |
+      Email [info@repronim.org](mailto:info@repronim.org) anytime. Virtual
+      drop-in office hours run on the first Thursday of every month — see the
+      [Help page](/help/) for details and additional support resources.
+
+  - question: How do I apply to the ReproNim Fellowship?
+    answer: |
+      Application timelines, eligibility, and current cycle details live on
+      the [Fellowship page](/fellowship/).
diff --git a/layouts/shortcodes/rn-faq.html b/layouts/shortcodes/rn-faq.html
new file mode 100644
index 00000000..48f825b4
--- /dev/null
+++ b/layouts/shortcodes/rn-faq.html
@@ -0,0 +1,128 @@
+{{- with site.Data.faq -}}
+{{- with .entries -}}
+{{- $seen := slice -}}
+<section class="rn-faq" aria-labelledby="rn-faq-heading">
+  <h2 id="rn-faq-heading">Frequently Asked Questions</h2>
+
+  {{- range $i, $entry := . }}
+    {{- $q := $entry.question | default "" -}}
+    {{- $a := $entry.answer | default "" -}}
+    {{- if not $q -}}
+      {{- warnf "rn-faq: skipping entry %d — missing or empty 'question' field" $i -}}
+    {{- else if not $a -}}
+      {{- warnf "rn-faq: skipping entry %q — missing or empty 'answer' field" $q -}}
+    {{- else -}}
+      {{- $rawId := "" -}}
+      {{- with $entry.id -}}
+        {{- $rawId = . -}}
+      {{- end -}}
+      {{- $id := "" -}}
+      {{- if $rawId -}}
+        {{- $idPattern := `^[a-z0-9][a-z0-9-]*$` -}}
+        {{- if findRE $idPattern $rawId -}}
+          {{- $id = $rawId -}}
+        {{- else -}}
+          {{- warnf "rn-faq: id %q for question %q is invalid (must match %s); falling back to auto-generated slug" $rawId $q $idPattern -}}
+          {{- $id = printf "faq-%s" (urlize $q) -}}
+        {{- end -}}
+      {{- else -}}
+        {{- $id = printf "faq-%s" (urlize $q) -}}
+      {{- end -}}
+      {{- /* duplicate-id detection: append -2, -3, ... if needed */ -}}
+      {{- $finalId := $id -}}
+      {{- $n := 2 -}}
+      {{- range $seen -}}
+        {{- if eq . $finalId -}}
+          {{- $finalId = printf "%s-%d" $id $n -}}
+          {{- $n = add $n 1 -}}
+        {{- end -}}
+      {{- end -}}
+      {{- if ne $finalId $id -}}
+        {{- warnf "rn-faq: duplicate anchor for question %q — using %q. Consider setting an explicit 'id:' field in data/faq.yaml." $q $finalId -}}
+      {{- end -}}
+      {{- $seen = $seen | append $finalId }}
+  <details class="rn-faq-item" id="{{ $finalId }}">
+    <summary>{{ $q }}</summary>
+    <div class="rn-faq-answer">
+      {{ $a | markdownify }}
+    </div>
+  </details>
+    {{- end -}}
+  {{- end }}
+
+  <style>
+    .rn-faq {
+      margin-top: 2.5rem;
+      margin-bottom: 1.5rem;
+      text-align: left;
+    }
+    .rn-faq h2#rn-faq-heading {
+      text-align: left;
+      margin-bottom: 1rem;
+    }
+    .rn-faq-item {
+      border-top: 1px solid rgba(127, 127, 127, 0.3);
+      padding: 0.75rem 0;
+    }
+    .rn-faq-item:last-of-type {
+      border-bottom: 1px solid rgba(127, 127, 127, 0.3);
+    }
+    .rn-faq-item > summary {
+      cursor: pointer;
+      font-weight: 600;
+      list-style: none;
+      padding: 0.25rem 0;
+      position: relative;
+      padding-right: 1.5rem;
+    }
+    .rn-faq-item > summary::-webkit-details-marker {
+      display: none;
+    }
+    .rn-faq-item > summary::after {
+      content: "+";
+      position: absolute;
+      right: 0.25rem;
+      top: 50%;
+      transform: translateY(-50%);
+      font-weight: 400;
+      font-size: 1.25rem;
+      line-height: 1;
+    }
+    .rn-faq-item[open] > summary::after {
+      content: "\2212"; /* unicode minus */
+    }
+    .rn-faq-item > summary:focus-visible {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+      border-radius: 2px;
+    }
+    .rn-faq-answer {
+      padding: 0.5rem 0 0.25rem;
+      line-height: 1.6;
+    }
+    .rn-faq-answer > :first-child { margin-top: 0; }
+    .rn-faq-answer > :last-child  { margin-bottom: 0; }
+  </style>
+
+  <script>
+    (function () {
+      function openFromHash() {
+        var hash = window.location.hash;
+        if (!hash || hash.length < 2) return;
+        var el = document.getElementById(decodeURIComponent(hash.substring(1)));
+        if (el && el.tagName && el.tagName.toLowerCase() === "details" && el.classList.contains("rn-faq-item")) {
+          el.open = true;
+          el.scrollIntoView({ block: "start" });
+        }
+      }
+      if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", openFromHash);
+      } else {
+        openFromHash();
+      }
+      window.addEventListener("hashchange", openFromHash);
+    })();
+  </script>
+</section>
+{{- end -}}
+{{- end -}}
diff --git a/specs/001-faq-section/checklists/requirements.md b/specs/001-faq-section/checklists/requirements.md
new file mode 100644
index 00000000..c41ef950
--- /dev/null
+++ b/specs/001-faq-section/checklists/requirements.md
@@ -0,0 +1,37 @@
+# Specification Quality Checklist: Frequently Asked Questions Section on Home Page
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-04-28
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Items marked incomplete require spec updates before `/speckit-clarify` or `/speckit-plan`.
+- The phrase "main tab" in the original request was interpreted as the Home page (`content/_index.md`); this is recorded explicitly in the Assumptions section so that a maintainer reviewing the spec can confirm or redirect before planning begins.
+- FR-007 references WCAG 2.1 AA. While "WCAG" is a standard rather than an implementation detail, reviewers should confirm the target conformance level is appropriate for the site.
+- The starter content (FR-014) bounds scope to 5–8 questions and a topic list; exact wording is intentionally deferred to maintainers.
diff --git a/specs/001-faq-section/contracts/faq-shortcode.md b/specs/001-faq-section/contracts/faq-shortcode.md
new file mode 100644
index 00000000..d40e985e
--- /dev/null
+++ b/specs/001-faq-section/contracts/faq-shortcode.md
@@ -0,0 +1,113 @@
+# Contract: `rn-faq` Hugo Shortcode
+
+**Feature**: 001-faq-section
+**Date**: 2026-04-28
+
+This is the public contract the FAQ shortcode exposes to the rest of the site. It defines the input it consumes, the output HTML it produces, and the interaction guarantees that downstream tests (manual + automated accessibility) can verify against.
+
+## Invocation
+
+In a content file (e.g., `content/_index.md`):
+
+```markdown
+{{< rn-faq >}}
+```
+
+The shortcode takes **no positional or named arguments**. All content comes from `site.Data.faq`.
+
+Optional named argument (future-friendly, not used at v1):
+
+| Argument | Type   | Default | Purpose |
+|----------|--------|---------|---------|
+| `title`  | string | `"Frequently Asked Questions"` | Override the section heading text. |
+
+## Input contract
+
+The shortcode reads `site.Data.faq.entries` (i.e., the `entries:` list inside `data/faq.yaml`).
+
+- If `data/faq.yaml` does not exist, or `entries` is missing, or `entries` is empty: the shortcode emits **no output**.
+- If `entries` is non-empty: each item must conform to the schema in `data-model.md`. Invalid items are skipped with a Hugo build warning; the rest still render.
+
+## Output contract
+
+For a non-empty `entries` list, the shortcode emits this HTML structure:
+
+```html
+<section class="rn-faq" aria-labelledby="rn-faq-heading">
+  <h2 id="rn-faq-heading">Frequently Asked Questions</h2>
+
+  <details id="faq-what-is-repronim" class="rn-faq-item">
+    <summary>What is ReproNim?</summary>
+    <div class="rn-faq-answer">
+      <!-- markdownified answer HTML -->
+    </div>
+  </details>
+
+  <details id="faq-how-do-i-get-started" class="rn-faq-item">
+    <summary>How do I get started?</summary>
+    <div class="rn-faq-answer">
+      <!-- markdownified answer HTML -->
+    </div>
+  </details>
+
+  <!-- one <details> per entry, in YAML order -->
+
+  <style>/* scoped styles for .rn-faq, .rn-faq-item, .rn-faq-answer */</style>
+  <script>/* deep-link expansion handler */</script>
+</section>
+```
+
+### Guaranteed properties
+
+- The wrapping element is a `<section>` with class `rn-faq` and an `aria-labelledby` pointing at the heading. Assistive tech announces the section as a named region.
+- The heading is `<h2>` so it slots correctly under the home page's `<h1>` title.
+- Each entry is a `<details>` element with:
+  - A unique `id` (per `data-model.md` rules).
+  - The class `rn-faq-item`.
+  - A child `<summary>` containing the plain-text question.
+  - A child `<div class="rn-faq-answer">` containing the rendered Markdown answer.
+- No `open` attribute is set server-side — every entry renders collapsed (FR-002a).
+- The `<style>` and `<script>` blocks are scoped to `.rn-faq` selectors and behavior — they do not affect the rest of the page.
+
+### Style guarantees
+
+The scoped CSS must:
+
+- Inherit text color and background from the active theme so light/dark mode work without overrides (FR-009).
+- Provide adequate spacing between entries (≥ 0.75 rem vertical) and a visible focus ring on `<summary>` for keyboard users.
+- Maintain WCAG 2.1 AA contrast (FR-007). Don't override Hextra's link colors inside `.rn-faq-answer`.
+- Replace the default disclosure triangle with a styled chevron only if the substitution preserves accessibility — otherwise leave the browser default (acceptable per FR-007).
+
+### Script guarantees
+
+The inline `<script>` must:
+
+- Run on initial load and on every `hashchange`.
+- If the URL hash matches the `id` of an `<details>` inside `.rn-faq`, set `open = true` and call `scrollIntoView({ block: 'start' })`.
+- Do nothing else. No analytics, no state mutation outside the targeted element, no event listeners on `<summary>` (the browser handles those natively).
+- Be wrapped in an IIFE to avoid leaking globals.
+
+## Behavioral guarantees (verifiable from this contract)
+
+| ID  | Behavior | How to verify |
+|-----|----------|---------------|
+| C1  | Section is hidden when no entries exist | Remove `data/faq.yaml`; rebuild; confirm no `<section class="rn-faq">` in `public/index.html`. |
+| C2  | Entries render in YAML order | View page source; confirm `<details>` ids appear in the same order as YAML list. |
+| C3  | Each entry collapsed by default (no anchor) | Load `/`; confirm no `<details>` has the `open` attribute. |
+| C4  | Deep link opens the targeted entry | Load `/#faq-how-do-i-get-started`; confirm the matching `<details>` has `open=true` and is in view. |
+| C5  | Invalid anchor is harmless | Load `/#faq-does-not-exist`; confirm the page renders normally with all entries collapsed. |
+| C6  | Multiple entries can be open simultaneously | Click two `<summary>` elements; confirm both stay open. |
+| C7  | Keyboard operable | Tab to a `<summary>`; press Enter or Space; confirm it expands; press again to collapse. |
+| C8  | Screen-reader expanded state | Inspect with VoiceOver/NVDA; confirm `<summary>` announces expanded/collapsed correctly (provided natively by `<details>`). |
+| C9  | Theme adaptation | Toggle light/dark; confirm contrast meets AA in both. |
+| C10 | Markdown links in answers work | Add an answer with `[link](/about/)`; click it; confirm navigation. |
+| C11 | Search indexing | Site search returns FAQ answer text when querying for a phrase that appears only in an answer. |
+
+## Non-contract (intentionally unspecified)
+
+These are implementation freedoms left to whoever writes the shortcode:
+
+- The exact CSS values (colors, font sizes, spacing) — must respect theme tokens and contrast, but specific numbers are tunable.
+- Whether to use a custom chevron `::after` pseudo-element or the browser default disclosure triangle.
+- Whether to memoize `urlize` results across iterations (a Hugo perf detail with no observable effect).
+- Future expansion: optional `title` argument and optional per-entry `tag` field for grouping. Not in v1.
diff --git a/specs/001-faq-section/data-model.md b/specs/001-faq-section/data-model.md
new file mode 100644
index 00000000..7fffba08
--- /dev/null
+++ b/specs/001-faq-section/data-model.md
@@ -0,0 +1,75 @@
+# Phase 1 Data Model: FAQ Entries
+
+**Feature**: 001-faq-section
+**Date**: 2026-04-28
+
+There is one entity in this feature, stored in **`data/faq.yaml`** and consumed by the `rn-faq` Hugo shortcode.
+
+## Entity: FAQ Entry
+
+| Field      | Type   | Required | Description |
+|------------|--------|----------|-------------|
+| `question` | string | Yes      | The question text. Plain text, no Markdown (renders inside `<summary>`). Should be written naturally — sentence case, ending with `?`. |
+| `answer`   | string | Yes      | The answer body. Markdown — supports paragraphs, links, lists, emphasis, inline code. Authored using a YAML literal block scalar (`|`). |
+| `id`       | string | No       | Optional explicit anchor override. Lowercase, kebab-case, alphanumeric + hyphens only. If omitted, defaults to `faq-{{ urlize question }}`. |
+
+## File: `data/faq.yaml`
+
+The data file has a single top-level key `entries` whose value is an ordered list of FAQ Entry objects. Order in the list = render order on the page.
+
+```yaml
+entries:
+  - question: What is ReproNim?
+    answer: |
+      ReproNim is a national biotechnology development center dedicated to
+      tools and services for reproducible neuroimaging. See the
+      [About page](/about/) for more.
+
+  - question: How do I get started?
+    answer: |
+      Visit the [Getting Started](/resources/getting-started/) page for an
+      overview, or browse the [tools page](/resources/tools/).
+
+  - id: fellowship-apply
+    question: How do I apply to the ReproNim Fellowship?
+    answer: |
+      Application details and the current cycle are on the
+      [Fellowship page](/fellowship/).
+```
+
+## Validation rules
+
+These are enforced by the shortcode template at render time. Failures during `hugo build` mean the home page won't deploy until the YAML is fixed — surfacing problems to the maintainer immediately.
+
+1. **`question` is non-empty.** A blank question would produce an empty `<summary>` and an unreachable id. The shortcode skips entries with no `question` and emits a build warning.
+2. **`answer` is non-empty.** A missing answer makes the entry pointless. Skipped with warning.
+3. **Anchor uniqueness.** The shortcode tracks ids it has already emitted in the current page; on a duplicate, it appends `-2`, `-3`, etc. to disambiguate, and emits a build warning so the maintainer can fix the source. (Two distinct questions can occasionally produce the same slug, e.g. capitalization-only differences.)
+4. **`id` format (when provided).** Must match the regex `^[a-z0-9][a-z0-9-]*$`. Invalid ids fall back to the auto-generated slug and emit a build warning.
+
+## Anchor URL examples
+
+For a question `"How do I get started?"` with no `id` override:
+
+- Anchor: `faq-how-do-i-get-started`
+- Deep-link URL: `https://repronim.org/#faq-how-do-i-get-started`
+
+For an entry with `id: fellowship-apply`:
+
+- Anchor: `fellowship-apply`
+- Deep-link URL: `https://repronim.org/#fellowship-apply`
+
+## Lifecycle
+
+FAQ Entries have no runtime lifecycle — they are static content rebuilt each deploy. The maintainer-facing operations are:
+
+| Operation | Action |
+|-----------|--------|
+| Add | Append a new list item to `data/faq.yaml`. |
+| Edit | Modify the `question` or `answer` of an existing item. Editing the question changes its auto-generated anchor unless an explicit `id` is in place. |
+| Reorder | Move list items up/down in the YAML. |
+| Remove | Delete the list item. Outstanding deep-links to the removed anchor become inert (page loads cleanly per FR-011). |
+| Add a stable anchor to an existing entry | Add an explicit `id:` field, preferably matching the previous auto-generated slug, so existing deep-links keep working. |
+
+## Relationship to other entities
+
+None — FAQ Entries are self-contained leaf data with no foreign keys to other site content.
diff --git a/specs/001-faq-section/plan.md b/specs/001-faq-section/plan.md
new file mode 100644
index 00000000..7dd80c62
--- /dev/null
+++ b/specs/001-faq-section/plan.md
@@ -0,0 +1,83 @@
+# Implementation Plan: Frequently Asked Questions Section on Home Page
+
+**Branch**: `001-faq-section` | **Date**: 2026-04-28 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/001-faq-section/spec.md`
+
+## Summary
+
+Add a Frequently Asked Questions section to the ReproNim home page (`content/_index.md`), rendered by a new Hugo shortcode that reads from a single maintainer-editable data file (`data/faq.yaml`). Each entry is a question/answer pair; answers support Markdown so links, lists, and emphasis render correctly. Entries default to collapsed, support multiple open at once, expose stable URL anchors for deep-linking, and meet WCAG 2.1 AA in both light and dark themes.
+
+The implementation leans on the **HTML5 `<details>`/`<summary>` element** for the accordion behavior so semantics, keyboard interaction, and screen-reader announcement are correct by default with zero JavaScript. A small inline progressive-enhancement script handles only the deep-linking case (open the targeted `<details>` and scroll to it on page load and on `hashchange`).
+
+## Technical Context
+
+**Language/Version**: Hugo 0.132.2 (extended), Hextra theme v0.8.3 (Go module)
+**Primary Dependencies**: Hugo Go templates, Hextra theme; no new runtime dependencies, no JS framework, no build tooling beyond Hugo itself
+**Storage**: Static; FAQ entries stored in `data/faq.yaml` (committed to the repo)
+**Testing**: Manual verification via `hugo server` + an automated accessibility check (axe DevTools or Lighthouse) on the home page; no test framework added
+**Target Platform**: Static site served via Netlify; supported browsers per the existing site (last two major versions of Chrome, Firefox, Safari, Edge)
+**Project Type**: Static documentation/content site (Hugo + Hextra)
+**Performance Goals**: Home page LCP must stay within 10% of pre-launch value (per SC-007); no additional render-blocking assets
+**Constraints**: Must work without JavaScript for read-only viewing (NoJS users still see all answers when they click `<details>`); only deep-linking degrades to "anchor scrolls but entry stays closed" without JS; must honor the existing light/dark theme toggle; no changes to the top navigation
+**Scale/Scope**: Single page surface; 5–8 entries at launch (per FR-014), expected to grow to ≤30 over the foreseeable life of the section
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+The repository's `.specify/memory/constitution.md` is the unfilled template — no project-specific principles have been ratified, so there are no formal gates to evaluate. Applying the workspace-level standards from `/Users/yibeichen/Documents/GitHub/CLAUDE.md` and the existing site conventions instead:
+
+| Standard | Status | Notes |
+|----------|--------|-------|
+| Use existing tech stack (Hugo + Hextra) | Pass | No new framework, no JS bundle, no build step changes |
+| Markdown-first content authoring | Pass | Answers authored as Markdown in YAML; rendered with `markdownify` |
+| Accessibility (WCAG 2.1 AA) | Pass by design | Native `<details>`/`<summary>` carries semantics; theme contrast already AA |
+| No console/debug noise in commits | Pass | Inline JS is ~15 lines, scoped, no logging |
+| Conventional commits | Pass | Implementation will use `feat: …` |
+| `[skip netlify]` flag awareness | N/A | Used only for non-deploy commits |
+
+**Result**: No violations. No `Complexity Tracking` entries needed. Re-checked after Phase 1 design — still no violations.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/001-faq-section/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output (how a maintainer adds an entry)
+├── contracts/
+│   └── faq-shortcode.md # Phase 1 output (input data schema + output HTML contract)
+├── checklists/
+│   └── requirements.md  # Spec quality checklist (already created)
+└── tasks.md             # Phase 2 output (created later by /speckit-tasks)
+```
+
+### Source Code (repository root)
+
+This is a Hugo static site, not a traditional code project. The feature lands in the existing site layout:
+
+```text
+repronim.org/
+├── content/
+│   └── _index.md                       # Home page — add {{< rn-faq >}} shortcode call
+├── data/
+│   └── faq.yaml                        # NEW — maintainer-edited FAQ entries
+├── layouts/
+│   └── shortcodes/
+│       └── rn-faq.html                 # NEW — renders the FAQ section from data/faq.yaml
+├── static/                             # (unchanged) inline JS lives in the shortcode
+└── hugo.yaml                           # (unchanged) — no menu/config changes; stays on Home tab
+```
+
+**Structure Decision**: Add **one** new shortcode (`layouts/shortcodes/rn-faq.html`) and **one** new data file (`data/faq.yaml`). Modify **one** existing file (`content/_index.md`) to invoke the shortcode below the existing intro and `rn-buttons` block. No CSS file is added; styles are scoped inside the shortcode (matching the precedent set by `rn-buttons.html`, which inlines its `<style>`). No changes to `hugo.yaml`, navigation, or the theme module.
+
+This is the minimum surface area that satisfies all functional requirements and matches the existing per-feature convention used by `rn-button` / `rn-buttons` / `wordpress-posts` / `people` / `fellows-resources`.
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+No constitution violations. Section intentionally left empty.
diff --git a/specs/001-faq-section/quickstart.md b/specs/001-faq-section/quickstart.md
new file mode 100644
index 00000000..e5e3772e
--- /dev/null
+++ b/specs/001-faq-section/quickstart.md
@@ -0,0 +1,86 @@
+# Quickstart: Adding & Editing FAQ Entries
+
+**Feature**: 001-faq-section
+**Audience**: ReproNim maintainers (anyone already comfortable editing site Markdown via GitHub)
+**Time to add a new entry**: ~5 minutes
+
+This guide assumes the FAQ feature has been implemented and shipped. If it hasn't, see `tasks.md` (created by `/speckit-tasks`) for the implementation steps.
+
+## TL;DR
+
+To add an FAQ entry, edit one file: **`data/faq.yaml`** in the repo. Append a new list item under `entries:`, commit, and the question appears on the home page after the next Netlify deploy.
+
+## Step-by-step: add a new FAQ entry
+
+1. **Open `data/faq.yaml`** on GitHub. The "Edit this page" workflow that already works for site Markdown also works for data files — open the file in the GitHub UI and click the pencil icon.
+
+2. **Append a new list item** under `entries:`. Use this template:
+
+   ```yaml
+     - question: Your question goes here?
+       answer: |
+         Your answer goes here. You can use **Markdown**:
+         - Lists work.
+         - [Links](/resources/) work.
+         - `Inline code` works.
+   ```
+
+   Notes:
+   - The `|` after `answer:` is YAML's literal block scalar. It lets you write multi-line Markdown naturally.
+   - Indent the answer body two spaces past the `answer:` key, as shown.
+
+3. **(Optional) Set a stable anchor** by adding an explicit `id:` field. Recommended whenever you expect the question wording might change later but you want existing deep links to keep working.
+
+   ```yaml
+     - id: fellowship-apply
+       question: How do I apply to the ReproNim Fellowship?
+       answer: |
+         See the [Fellowship page](/fellowship/).
+   ```
+
+   Without `id:`, the anchor is auto-generated from the question slug — fine for stable wording, but a reworded question changes the URL.
+
+4. **Commit and push.** Use a conventional-commit message such as `docs: add FAQ entry on fellowship deadlines`. A pull request triggers Netlify's preview deploy; merging to `main` triggers production.
+
+5. **Verify.** After deploy:
+   - Open `https://repronim.org/` and scroll to the FAQ section.
+   - Click your new question; the answer should expand.
+   - Copy the URL of the question's anchor (right-click the question → "Copy link" works in most browsers, or check the rendered page source for the `<details id="...">`).
+   - Paste the deep-link URL in a new tab; confirm the page loads with your entry already expanded and scrolled into view.
+
+## Step-by-step: edit or remove an entry
+
+- **Edit**: Change `question` or `answer` in place. Reordering, formatting, and link changes are all in-place edits.
+- **Reorder**: Move the list item up or down within `entries:`. Render order = YAML order.
+- **Remove**: Delete the list item. If you anticipate that outstanding deep links exist (e.g., the question was linked from an email or another page), consider replacing it with a redirect-style answer that points to the new location instead of deleting outright.
+
+## Anchor stability tips
+
+- The auto-generated anchor for a question is `faq-` + the URL-friendly slug of the question. Example: `"How do I get started?"` → `faq-how-do-i-get-started`.
+- To preserve a deep link across a rewording, set `id:` to the previous slug **before** changing the question text. Example: change to `id: faq-how-do-i-get-started`, then update `question:` freely.
+
+## Common pitfalls
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| New entry doesn't appear on the home page | YAML indentation is wrong (Netlify build will have failed) | Check the build log on Netlify for a YAML parse error; fix indentation so each list item starts with `  - question:`. |
+| Answer renders as a single long line | Used `>` (folded scalar) instead of `|` (literal scalar) for `answer:` | Use `|` to preserve newlines. |
+| Markdown link looks like raw text in the answer | The answer string is being treated as plain text | Confirm the YAML uses `answer: |` (with the pipe) and that the answer is indented correctly. The shortcode runs `markdownify` on the value. |
+| Deep link doesn't open the entry | Hash in URL doesn't match any entry's id (typo, stale link, or entry was removed) | Verify the current id by inspecting the page or by checking `data/faq.yaml` for an `id:` override. |
+| Duplicate ids warning in build log | Two questions slugify to the same anchor (e.g., differ only in punctuation) | Add an explicit `id:` to one of them. |
+
+## Verifying accessibility (occasional check)
+
+When the FAQ grows or styles change, run an accessibility check on the home page:
+
+- **Lighthouse** (Chrome DevTools → Lighthouse → "Accessibility") — score should be ≥ 95 with no FAQ-related findings.
+- **axe DevTools** browser extension — run on `/`; confirm no violations under the `.rn-faq` section.
+- Keyboard test: Tab to a question; press Enter; press Tab again to confirm focus moves into the answer's links.
+
+## Where the implementation lives
+
+- Data: `data/faq.yaml`
+- Shortcode template: `layouts/shortcodes/rn-faq.html`
+- Invocation: `content/_index.md` (one `{{< rn-faq >}}` line below the `rn-buttons` block)
+
+If you need to change the section heading, the styling, or the script, edit `layouts/shortcodes/rn-faq.html`. For everyday content edits, you only need `data/faq.yaml`.
diff --git a/specs/001-faq-section/research.md b/specs/001-faq-section/research.md
new file mode 100644
index 00000000..c6f383e6
--- /dev/null
+++ b/specs/001-faq-section/research.md
@@ -0,0 +1,165 @@
+# Phase 0 Research: FAQ Section on Home Page
+
+**Feature**: 001-faq-section
+**Date**: 2026-04-28
+
+The Technical Context for this feature has no `NEEDS CLARIFICATION` markers — Hugo, Hextra, the data-file pattern, and the deployment pipeline are already in use across the site. The remaining open questions are *implementation choices* that the spec leaves to planning. Each is resolved below with a decision, rationale, and the alternatives that were considered.
+
+---
+
+## R1. Accordion mechanism: native `<details>` vs. custom JS
+
+**Decision**: Use the HTML5 `<details>`/`<summary>` element as the primitive for each FAQ entry, with Markdown-rendered answer content inside.
+
+**Rationale**:
+- Built-in semantics: keyboard focus, Enter/Space toggling, and `aria-expanded` state are handled by the browser. This satisfies FR-007 and SC-004 with no extra ARIA wiring.
+- Zero JavaScript required for the core expand/collapse behavior. Visitors with JS disabled still get a fully functional FAQ.
+- HTML5 `<details>` is supported in every browser the site targets (last two majors of Chrome, Firefox, Safari, Edge — universal since ~2020).
+- Multiple entries can be open simultaneously by default, satisfying FR-003. We deliberately do **not** group entries with `name="faq"` (HTML5 exclusive accordions), because that would force collapsing one to view another.
+- Theme-friendly: `<summary>` is a normal element that inherits color and font tokens from the Hextra theme; no theme-specific styling is needed beyond a small marker tweak.
+
+**Alternatives considered**:
+- *Custom `<button aria-expanded>` + `<div role="region">`*: requires hand-rolled keyboard handling and ARIA management. More code, more risk of accessibility regression. Rejected.
+- *Hextra's `card` or `callout` shortcode reused as a faux accordion*: not designed for this purpose; would not collapse and would not deep-link cleanly. Rejected.
+- *A third-party accordion JS library*: adds a dependency for a feature that the platform handles natively. Rejected.
+
+---
+
+## R2. Content storage: data file vs. Markdown shortcode-per-entry vs. content bundle
+
+**Decision**: Store entries in **`data/faq.yaml`**, a single YAML file with an `entries:` list, each item having `question`, `answer` (Markdown string), and an optional `id` override. The shortcode reads this file via `site.Data.faq`.
+
+**Rationale**:
+- One source of truth. A maintainer adds, removes, or reorders entries by editing one file via the existing GitHub "Edit this page" workflow. Satisfies FR-005 and SC-003.
+- Order in the YAML list = render order. Satisfies FR-006.
+- Matches the established site precedent: `data/fellows-2024.yaml`, `data/repronim-team.yaml`, `data/publications.yaml` are all structured YAML consumed by shortcodes/partials.
+- Markdown answers are rendered with Hugo's `markdownify` function, so links, lists, inline code, and emphasis work without special handling. Satisfies FR-004.
+- Anchors are derived deterministically from the question via Hugo's `urlize` (or `anchorize`) function, with an explicit `id` override available for stability if a question is reworded later. Satisfies FR-010.
+
+**Alternatives considered**:
+- *Per-entry shortcode calls inside `_index.md`* (e.g., `{{< rn-faq-item q="..." >}}` with body content): more verbose, harder to reorder, mixes structure and content in a single file. Rejected.
+- *Hugo content bundle under `content/faq/` with one Markdown page per entry*: overkill for a section-of-a-page feature; pulls in page-level concerns (taxonomies, list templates) that we don't need. Rejected.
+- *Front matter list in `_index.md`*: works for tiny lists but conflates page metadata with body content. Rejected for clarity.
+
+---
+
+## R3. Deep-linking and default expansion state
+
+**Decision**: All entries render with `<details>` collapsed (no `open` attribute) on the server. A tiny inline `<script>` inside the shortcode runs on `DOMContentLoaded` and on `hashchange`: if `window.location.hash` matches an FAQ entry's id, set its `open` attribute and scroll it into view.
+
+**Rationale**:
+- Server-rendered HTML matches FR-002a (all collapsed by default) for the no-anchor case.
+- The script is ~15 lines, defer-safe, has no dependencies, and degrades gracefully — without JS, an anchor still scrolls the visitor to the closed entry; the visitor can still click to open it.
+- `hashchange` handling means an in-page link to another FAQ entry also opens the target.
+- This pattern is well-established (used by GitHub Markdown, MDN, and many docs sites).
+
+**Implementation sketch** (will live inside `rn-faq.html`):
+
+```html
+<script>
+(function () {
+  function openFromHash() {
+    var hash = window.location.hash;
+    if (!hash || hash.length < 2) return;
+    var el = document.getElementById(hash.substring(1));
+    if (el && el.tagName === 'DETAILS') {
+      el.open = true;
+      el.scrollIntoView({ block: 'start' });
+    }
+  }
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', openFromHash);
+  } else {
+    openFromHash();
+  }
+  window.addEventListener('hashchange', openFromHash);
+})();
+</script>
+```
+
+**Alternatives considered**:
+- *Server-render the targeted entry with `open` based on a query param*: Hugo SSG cannot read the URL hash at build time, and using a query param instead of a hash is non-standard for in-page anchors. Rejected.
+- *Open all entries when JS is disabled*: defeats the "compact by default" goal and violates FR-002a. Rejected.
+
+---
+
+## R4. Markdown-in-YAML answers
+
+**Decision**: Author answers in YAML using a literal block scalar (`|`) and render with Hugo's `markdownify` function in the template.
+
+**Example**:
+
+```yaml
+- question: How do I get started with ReproNim?
+  answer: |
+    See the [Getting Started](/resources/getting-started/) page for an overview,
+    or jump straight to the [tools page](/resources/tools/) to find a specific tool.
+```
+
+**Rationale**:
+- Block scalars preserve newlines and let authors write multi-paragraph answers naturally.
+- `markdownify` is the standard Hugo function for inline Markdown rendering and supports the same Goldmark configuration as the rest of the site (including `markup.goldmark.renderer.unsafe = true` from `hugo.yaml`, which allows raw HTML if a maintainer ever needs it).
+- Keeps the editing experience identical to other Markdown content on the site.
+
+**Alternatives considered**:
+- *Plain-string answers (no Markdown)*: would block links and formatting. Violates FR-004. Rejected.
+- *Separate Markdown files referenced from YAML*: doubles file count per entry for marginal benefit. Rejected.
+
+---
+
+## R5. Anchor (id) generation
+
+**Decision**: Default the `<details>` `id` to `faq-{{ .question | urlize }}`. If the YAML entry provides an explicit `id:` field, use that verbatim (still namespaced under the FAQ section by convention).
+
+**Rationale**:
+- `urlize` produces a slug compatible with the existing Hextra heading-anchor convention.
+- The `faq-` prefix avoids id collisions with any heading anchor on the home page.
+- The explicit override lets maintainers preserve a stable link if a question's wording is updated. This is the same trade-off Wikipedia uses for section-anchor stability.
+
+**Alternatives considered**:
+- *Numeric ids based on list index* (`faq-1`, `faq-2`, …): unstable across reorderings. Rejected.
+- *Hash of question text*: opaque to humans; a reworded question silently breaks links anyway. Rejected.
+
+---
+
+## R6. Search indexing
+
+**Decision**: Take no special action — Hextra's built-in search (Pagefind/FlexSearch via the theme) already indexes home-page content, so the rendered FAQ is included automatically. Verify in the quickstart.
+
+**Rationale**:
+- Satisfies FR-013 with zero additional configuration. The shortcode renders normal HTML (not in a Web Component, not behind JS) so the indexer reads it like any other content.
+
+**Alternatives considered**:
+- *Add explicit search metadata*: not needed; would be redundant. Rejected.
+
+---
+
+## R7. Empty-state behavior
+
+**Decision**: The shortcode checks `len site.Data.faq.entries`. If there are zero entries, the shortcode emits **no output at all** (not even an empty `<section>` or heading). If there are entries, it emits the full section.
+
+**Rationale**:
+- Satisfies FR-012 directly: an empty FAQ produces no visible artifact, no broken layout, no orphan heading.
+- Lets the home page exist without a `data/faq.yaml` file at all (the shortcode also defends against the entire data key being absent).
+
+**Alternatives considered**:
+- *Render heading + "Coming soon" placeholder*: worse UX than just not showing the section. Rejected.
+
+---
+
+## R8. Performance impact
+
+**Decision**: No additional fetch, no new font, no new image. The shortcode contributes a small inline `<style>` block (similar in size to `rn-buttons.html`) and a ~15-line inline `<script>`. The data file is consumed at build time.
+
+**Rationale**:
+- No network requests are added beyond the home-page HTML itself, so SC-007 (LCP within 10% of pre-launch) is met by construction.
+- Inline assets defeat HTTP caching but are tiny (under ~2 KB combined uncompressed) and avoid extra round trips. This matches the precedent set by other `rn-*` shortcodes.
+
+**Alternatives considered**:
+- *Move CSS/JS to `static/` files for caching*: would be the right call at much larger sizes; for ~2 KB total, the inline form is faster overall and keeps the shortcode self-contained. Reject for v1; revisit if the FAQ grows substantially.
+
+---
+
+## Open items
+
+None. All resolutions are deterministic and ready for Phase 1.
diff --git a/specs/001-faq-section/spec.md b/specs/001-faq-section/spec.md
new file mode 100644
index 00000000..f4a90996
--- /dev/null
+++ b/specs/001-faq-section/spec.md
@@ -0,0 +1,122 @@
+# Feature Specification: Frequently Asked Questions Section on Home Page
+
+**Feature Branch**: `001-faq-section`
+**Created**: 2026-04-28
+**Status**: Draft
+**Input**: User description: "let's add a 'frequently asked' section in the main tab"
+
+## Clarifications
+
+### Session 2026-04-28
+
+- Q: Should deep-linking to specific FAQ entries (URL anchors that auto-expand the targeted entry) be in scope for v1? → A: Yes — keep deep-linking in scope (FR-010/FR-011/SC-008 stand).
+- Q: Where should the FAQ live? → A: As a section on the Home page (`/`, `content/_index.md`), below the existing intro and section buttons. No new top-nav entry; no standalone `/faq/` page.
+- Q: What is the default expansion state of FAQ entries on first load (no anchor in URL)? → A: All entries collapsed by default; visitor expands the ones they want. Deep-linked entries (URL anchor present) still open expanded per FR-010.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Visitor finds answers to common questions on the home page (Priority: P1)
+
+A first-time visitor lands on the ReproNim home page wanting to understand what the center offers, who it serves, and how to get started. Instead of navigating across multiple sub-pages, they scroll down and find a Frequently Asked Questions section that surfaces concise answers to the questions newcomers most often ask.
+
+**Why this priority**: This is the core value of the feature. Without it, the home page only links to other pages and forces visitors to hunt for basic answers, which increases bounce rate and email volume to `info@repronim.org`. P1 because the entire feature exists to serve this journey.
+
+**Independent Test**: A visitor opens the home page in a browser, scrolls past the existing intro and section buttons, sees a clearly-labeled "Frequently Asked Questions" section with at least one question, expands a question, and reads the answer. The feature is valuable on day one even if only a small starter set of questions is published.
+
+**Acceptance Scenarios**:
+
+1. **Given** a visitor on the home page, **When** they scroll past the existing top-of-page content (banner, intro, section buttons), **Then** they see a section clearly titled as the FAQ with a list of questions.
+2. **Given** the FAQ section is displayed, **When** the visitor selects a question, **Then** the corresponding answer becomes visible without navigating away from the home page.
+3. **Given** an answer is expanded, **When** the visitor selects the same question again (or another expanded question), **Then** the answer collapses, keeping the page tidy.
+4. **Given** a visitor wants more depth on a topic covered in the FAQ, **When** they read the answer, **Then** the answer may include a link to the relevant deeper resource (e.g., a tutorial, the tools page, or the help page).
+
+---
+
+### User Story 2 - Maintainer adds, edits, and removes FAQ entries (Priority: P2)
+
+A ReproNim maintainer (the same audience already editing other content via GitHub) needs to be able to add new questions, revise existing answers, and remove entries that are no longer relevant — without involving a developer or touching layout code.
+
+**Why this priority**: The FAQ is only useful if the team can keep it current. P2 because the visitor-facing experience (P1) can launch with a small initial set, but ongoing usefulness depends on easy editing.
+
+**Independent Test**: A maintainer opens the editable content for the FAQ via the existing "Edit this page" workflow used elsewhere on the site, adds a new question/answer pair, commits the change, and confirms the new entry appears on the home page after the next deploy.
+
+**Acceptance Scenarios**:
+
+1. **Given** a maintainer wants to add an FAQ entry, **When** they edit a single content source for the FAQ section, **Then** the new question and answer appear on the home page after deployment without code changes.
+2. **Given** an existing entry needs revision, **When** the maintainer updates that entry's answer text, **Then** only that answer changes on the home page; ordering and other entries remain stable.
+3. **Given** an entry is no longer relevant, **When** the maintainer removes that entry, **Then** it disappears from the home page and no broken anchors remain.
+
+---
+
+### User Story 3 - Visitor links directly to a specific question (Priority: P3)
+
+A staff member answering an email or a community member posting in a forum wants to share a direct link that opens the ReproNim home page with a specific FAQ entry already visible.
+
+**Why this priority**: Deep-linking improves the FAQ's usefulness as a support tool but is not required for the section to deliver value. P3.
+
+**Independent Test**: A user opens a URL of the form `https://repronim.org/#<question-anchor>`, the page loads, scrolls to the FAQ section, and the targeted question is expanded and visible.
+
+**Acceptance Scenarios**:
+
+1. **Given** a URL with an FAQ entry's anchor, **When** the page loads, **Then** the FAQ section is reached and the targeted question is in its expanded state.
+2. **Given** an anchor that does not match any current FAQ entry, **When** the page loads, **Then** the home page renders normally with no error and the FAQ section in its default state.
+
+---
+
+### Edge Cases
+
+- The FAQ has zero entries (e.g., during initial setup or while content is being prepared): the section either is hidden or shows a brief placeholder, but the home page must not appear broken.
+- The FAQ has many entries (e.g., 25+): the section remains scannable; visitors can still locate a question without excessive scrolling.
+- An answer contains rich content (links, lists, inline code): the answer renders correctly within the expanded view and remains readable.
+- The visitor uses a screen reader or keyboard-only navigation: each question is reachable, focusable, and operable, and the expanded/collapsed state is announced.
+- The visitor views the home page on a small mobile screen: the FAQ is fully usable, with tap targets large enough to operate and answers wrapping cleanly.
+- The visitor switches between light and dark site themes: the FAQ section honors both themes (the site already supports a theme toggle).
+- A visitor arrives via an outdated deep link to a question that has since been removed: the page loads cleanly and presents the FAQ in default state.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The home page MUST display a clearly-titled Frequently Asked Questions section, positioned below the existing intro paragraph and section buttons so it does not displace current top-of-page content.
+- **FR-002**: The FAQ section MUST present each entry as a question that can be expanded to reveal its answer and collapsed to hide it, so the page stays compact by default.
+- **FR-002a**: On initial page load, when no FAQ anchor is present in the URL, every FAQ entry MUST start in the collapsed state. (When an anchor matching an entry is present, that entry opens expanded per FR-010; all other entries still start collapsed.)
+- **FR-003**: Multiple questions MAY be expanded at the same time; the design MUST NOT force collapsing one entry to view another (this supports comparison reading).
+- **FR-004**: Each FAQ entry MUST support an answer that may include plain text, links to other site pages or external resources, and basic formatting (lists, emphasis, inline code).
+- **FR-005**: FAQ content MUST be editable through the same content workflow already used for other site pages (Markdown via GitHub-based "Edit this page"), without requiring layout or template changes for ordinary edits.
+- **FR-006**: The order in which entries are authored MUST be the order in which they appear on the page, so maintainers can curate prominence.
+- **FR-007**: The FAQ section MUST be accessible: each question is reachable by keyboard, expanded/collapsed state is exposed to assistive technology, and contrast meets WCAG 2.1 AA in both light and dark themes.
+- **FR-008**: The FAQ section MUST be responsive across desktop, tablet, and mobile breakpoints used by the rest of the site.
+- **FR-009**: The FAQ section MUST honor the site's existing light/dark theme toggle.
+- **FR-010**: Each FAQ entry MUST have a stable URL fragment (anchor) that can be used to deep-link to that entry; loading the page with such an anchor MUST scroll to the entry and present it in expanded state.
+- **FR-011**: An invalid or missing FAQ anchor in a URL MUST NOT break page rendering; the home page MUST load normally.
+- **FR-012**: When the FAQ has zero entries, the section MUST either be hidden entirely or show an unobtrusive placeholder — the home page MUST NOT show an empty heading or broken layout.
+- **FR-013**: The FAQ section MUST be discoverable by site search if site search already indexes home page content.
+- **FR-014**: The initial launch MUST include a starter set of 5–8 questions covering: what ReproNim is, who it is for, how to get started, where to find tools, how to participate, where to get help / office hours, and how to apply to the fellowship. (Final wording to be drafted by maintainers; this requirement bounds scope, not exact text.)
+
+### Key Entities *(include if feature involves data)*
+
+- **FAQ Entry**: A single question-and-answer pair shown in the FAQ section. Attributes: question text (short), answer body (formatted text, may include links), display order, and a stable anchor identifier derived from the question.
+- **FAQ Section**: The collection of FAQ Entries rendered on the home page, with a section heading and a defined position in the page layout.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: A first-time visitor can locate an answer to one of the starter questions (e.g., "How do I get started?") from the home page in under 30 seconds without leaving the home page.
+- **SC-002**: At launch, the FAQ section contains at least 5 published question-and-answer pairs.
+- **SC-003**: A maintainer who is already comfortable editing other Markdown pages on the site can add a new FAQ entry end-to-end (edit, commit, deploy) in under 10 minutes, with no code changes outside the FAQ content source.
+- **SC-004**: 100% of FAQ entries are operable by keyboard alone (Tab to focus, Enter/Space to expand and collapse) and announce their expanded/collapsed state to screen readers.
+- **SC-005**: The FAQ section meets WCAG 2.1 AA contrast in both light and dark themes (verified with an automated accessibility check on the home page).
+- **SC-006**: Within 90 days of launch, the volume of inbound `info@repronim.org` emails asking the questions covered by the FAQ trends downward, measured by maintainer review of the inbox or an equivalent qualitative review.
+- **SC-007**: Adding the FAQ does not regress existing home page performance: the home page's largest contentful paint stays within 10% of its pre-launch value on a typical broadband connection.
+- **SC-008**: Deep links to specific FAQ entries succeed (the targeted entry is visible and expanded) on at least the latest two major versions of the browsers the rest of the site supports.
+
+## Assumptions
+
+- The FAQ lives as a section on the **Home** page (`/`, rendered from `content/_index.md`), below the existing intro and section buttons. Confirmed via clarification on 2026-04-28. No standalone `/faq/` page and no new top-nav entry are introduced by this feature.
+- Initial FAQ content will be authored by ReproNim maintainers; this spec does not prescribe the exact wording of questions or answers, only the topic coverage and minimum count at launch.
+- The existing site theme (Hextra-based Hugo theme), navigation, and content-editing workflow continue to be used; no new content management system is introduced.
+- The FAQ uses a familiar expand/collapse interaction pattern (an accordion-style list) because it is the conventional, accessible default for FAQ sections; alternatives (e.g., always-open list, modal dialogs) are out of scope unless the maintainers choose otherwise during planning.
+- Translation/i18n is out of scope for this feature; the FAQ ships in the same language as the rest of the home page.
+- Analytics for tracking which FAQ entries are most expanded is out of scope for v1 but compatible with the existing Google Analytics integration if added later.
+- The starter set of 5–8 questions is sufficient for launch; ongoing growth of the FAQ is a maintenance activity, not part of this feature's delivery.
diff --git a/specs/001-faq-section/tasks.md b/specs/001-faq-section/tasks.md
new file mode 100644
index 00000000..05bc8a1e
--- /dev/null
+++ b/specs/001-faq-section/tasks.md
@@ -0,0 +1,211 @@
+---
+
+description: "Task list for feature 001-faq-section"
+---
+
+# Tasks: Frequently Asked Questions Section on Home Page
+
+**Input**: Design documents from `/specs/001-faq-section/`
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/faq-shortcode.md, quickstart.md
+
+**Tests**: Automated tests are NOT requested by the spec. This is a Hugo static site with no test framework; verification is manual (`hugo server`) plus accessibility tooling (Lighthouse, axe DevTools, keyboard test). Verification tasks are explicit in the Polish phase.
+
+**Organization**: Tasks are grouped by user story (US1, US2, US3 from spec.md) so each story can be implemented and validated as an independent increment.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependency on incomplete tasks).
+- **[Story]**: User story this task belongs to (US1 = P1 visitor view, US2 = P2 maintainer editing, US3 = P3 deep-linking).
+- File paths are absolute or repo-rooted as appropriate.
+
+## Path Conventions
+
+This is a Hugo + Hextra static site. The relevant paths are:
+
+- `content/_index.md` — home page content
+- `data/faq.yaml` — FAQ data (new file)
+- `layouts/shortcodes/rn-faq.html` — FAQ shortcode (new file)
+- `CONTRIBUTING.md` — existing contributor guide (will be linked, not rewritten)
+
+---
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Confirm the local Hugo + Hextra environment is ready. No code changes here.
+
+- [X] T001 Verify the Hugo dev environment runs cleanly: from the repo root run `hugo server -D` and confirm the home page loads at `http://localhost:1313/` with no template errors and no missing-module warnings. If `hugo` is not installed, install Hugo extended ≥ 0.132.2 (matching `netlify.toml`) before continuing.
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Create the empty file scaffolding that every user story builds on. Both files must exist before US1 work begins.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
+
+- [X] T002 [P] Create the data file `data/faq.yaml` with a top-level `entries:` key holding **one placeholder item** (`question:` + `answer:` using the `|` block scalar) so the shortcode has something to read during initial wiring. The real content replaces this placeholder in T008.
+- [X] T003 [P] Create the shortcode skeleton `layouts/shortcodes/rn-faq.html` with the empty-state guard only: an outer Go-template `{{ with site.Data.faq }}{{ with .entries }}` … `{{ end }}{{ end }}` block that emits nothing when `data/faq.yaml` is missing or `entries` is empty. Confirm by temporarily removing the placeholder and verifying no output is rendered, then restore it.
+
+**Checkpoint**: Foundation ready — User Story 1 can begin.
+
+---
+
+## Phase 3: User Story 1 — Visitor finds answers on the home page (Priority: P1) 🎯 MVP
+
+**Goal**: A first-time visitor lands on the home page, sees a clearly titled FAQ section below the existing intro and section buttons, can expand any question to read its answer, and can collapse it again. Multiple entries can be open at once. Section honors light/dark theme and meets WCAG 2.1 AA contrast.
+
+**Independent Test**: Run `hugo server`, open `/`, scroll past the legacy banner / intro / `rn-buttons` block, see "Frequently Asked Questions" with 5–8 entries, click any question to expand, click again to collapse, click two questions to confirm both stay open. Toggle the site theme; verify the section reads correctly in both light and dark.
+
+### Implementation for User Story 1
+
+- [X] T004 [US1] In `layouts/shortcodes/rn-faq.html`, add the section wrapper: `<section class="rn-faq" aria-labelledby="rn-faq-heading">` with an `<h2 id="rn-faq-heading">Frequently Asked Questions</h2>`. Place it inside the empty-state guard from T003 so it only renders when entries exist. Reference `contracts/faq-shortcode.md` for the exact element/attribute names.
+- [X] T005 [US1] In `layouts/shortcodes/rn-faq.html`, implement the entry rendering loop: `{{ range .entries }}` … `{{ end }}` emitting one `<details class="rn-faq-item" id="…">` per entry with `<summary>{{ .question }}</summary>` and `<div class="rn-faq-answer">{{ .answer | markdownify }}</div>`. Do **not** set the `open` attribute (FR-002a). Order = YAML order (FR-006).
+- [X] T006 [US1] In `layouts/shortcodes/rn-faq.html`, implement anchor id generation: if `.id` is set on the entry use it verbatim; otherwise compute `printf "faq-%s" (urlize .question)`. Use the result as the `<details id="…">` value (per `data-model.md` and contract C2/C4).
+- [X] T007 [US1] In `layouts/shortcodes/rn-faq.html`, append a scoped `<style>` block at the end of the section (mirroring the precedent set by `layouts/shortcodes/rn-buttons.html`). Style only `.rn-faq`, `.rn-faq-item`, `.rn-faq-item > summary`, and `.rn-faq-answer`. Required: vertical spacing ≥ 0.75rem between entries; visible focus ring on `<summary>` (`:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }`); cursor: pointer on `<summary>`; inherit color/background from the theme so light/dark both work (FR-009); do not override link colors inside `.rn-faq-answer`.
+- [X] T008 [US1] In `content/_index.md`, append `{{< rn-faq >}}` on its own line **after** the closing `{{< /rn-buttons >}}` so the FAQ section sits below the existing intro and section buttons, not above them.
+- [X] T009 [US1] In `data/faq.yaml`, replace the T002 placeholder with the launch starter set: 5–8 entries covering (per FR-014) "what ReproNim is", "who it is for", "how to get started", "where to find tools", "how to participate", "where to get help / office hours", and "how to apply to the fellowship." Use the YAML literal block scalar (`|`) for each `answer:`. Where natural, link to the relevant existing page (`/about/`, `/resources/getting-started/`, `/resources/tools/`, `/participate/`, `/help/`, `/fellowship/`). Reference `data-model.md` for the exact schema and `quickstart.md` for the editing pattern.
+- [ ] T010 [US1] Verify US1 acceptance: from `hugo server`, load `/`, confirm the FAQ section renders below `rn-buttons` with 5–8 collapsed entries; expand one, expand a second (confirm both stay open per FR-003); collapse one; toggle the theme switcher and confirm both light and dark mode render with readable contrast.
+
+**Checkpoint**: User Story 1 fully delivers the MVP. The home page now has a working FAQ that is visible to visitors. Could be shipped as-is.
+
+---
+
+## Phase 4: User Story 2 — Maintainer adds, edits, and removes entries (Priority: P2)
+
+**Goal**: A maintainer can manage the FAQ via the existing GitHub edit workflow without touching layout code. The shortcode degrades gracefully on malformed entries and surfaces problems in the Hugo build log.
+
+**Independent Test**: Have a maintainer (or simulate one) (a) add a new entry to `data/faq.yaml`, rebuild, confirm it appears in YAML order; (b) edit an existing entry's `answer`, rebuild, confirm only that answer changed; (c) delete an entry, rebuild, confirm it's gone and no broken anchor remains; (d) introduce a malformed entry (empty `question`), rebuild, confirm a Hugo `warnf` appears and the rest of the FAQ still renders.
+
+### Implementation for User Story 2
+
+- [X] T011 [US2] In `layouts/shortcodes/rn-faq.html`, add input validation inside the entry loop: skip entries where `.question` or `.answer` is empty/unset, and emit a Hugo build warning via `warnf` describing the skip. Reference `data-model.md` validation rules 1 and 2.
+- [X] T012 [US2] In `layouts/shortcodes/rn-faq.html`, add duplicate-id detection: track ids seen in the current page (use a `dict`/`slice` accumulator), and on a duplicate append `-2`, `-3`, … as a suffix while emitting a `warnf`. Reference `data-model.md` validation rule 3.
+- [X] T013 [US2] In `layouts/shortcodes/rn-faq.html`, validate the `id` field format when explicitly provided: if it does not match `^[a-z0-9][a-z0-9-]*$`, fall back to the auto-generated slug and emit a `warnf`. Reference `data-model.md` validation rule 4.
+- [X] T014 [US2] In `data/faq.yaml`, add a header comment block (lines starting with `#`) at the top of the file documenting the schema (`question`, `answer`, optional `id`), the literal block scalar usage, and a one-line link to the maintainer guide at `specs/001-faq-section/quickstart.md`. Goal: a maintainer opening the file in GitHub sees how to add an entry without leaving the file.
+- [X] T015 [US2] In `CONTRIBUTING.md`, add a short section titled "Editing the home page FAQ" with a 2–3 sentence pointer to `data/faq.yaml` and a link to `specs/001-faq-section/quickstart.md`. Place it after any existing "How to edit pages" section, or at the end if no comparable section exists. Do not duplicate the full quickstart — link to it.
+- [ ] T016 [US2] Verify US2 acceptance: temporarily add an entry, edit one, delete one, and introduce a malformed entry in `data/faq.yaml`. For each step run `hugo server` (or watch the running server reload), confirm the rendered page reflects the change and the build log behaves per T011/T012/T013. Restore the file before moving on.
+
+**Checkpoint**: User Stories 1 AND 2 both work independently. Maintainers can keep the FAQ current without engineering involvement.
+
+---
+
+## Phase 5: User Story 3 — Visitor deep-links to a specific question (Priority: P3)
+
+**Goal**: A URL of the form `https://repronim.org/#<faq-anchor>` opens the home page with the targeted FAQ entry already expanded and scrolled into view. Invalid anchors degrade gracefully (page renders normally per FR-011).
+
+**Independent Test**: With the dev server running, open `http://localhost:1313/#faq-how-do-i-get-started` (or whichever anchor maps to a real entry); confirm the matching `<details>` is `open` and visible. Then open `http://localhost:1313/#faq-does-not-exist`; confirm the page renders with all entries collapsed and no JS errors in the console.
+
+### Implementation for User Story 3
+
+- [X] T017 [US3] In `layouts/shortcodes/rn-faq.html`, append a scoped inline `<script>` at the end of the section. Wrap in an IIFE; define an `openFromHash` function that reads `window.location.hash`, looks up the matching `<details>` by id, sets `el.open = true`, and calls `el.scrollIntoView({ block: 'start' })`. Bind the function to `DOMContentLoaded` (or run immediately if the document is already past `loading`) and to `hashchange`. Reference the implementation sketch in `research.md` § R3.
+- [ ] T018 [US3] Verify US3 acceptance: with `hugo server` running, (a) load `/#<existing-anchor>`, confirm the targeted entry opens and scrolls into view; (b) load `/#faq-does-not-exist`, confirm the page renders with no console error and all entries collapsed; (c) while on `/`, manually change the URL hash in the address bar to a different valid anchor and press Enter, confirm `hashchange` triggers expansion of the new target.
+
+**Checkpoint**: All three user stories are complete. Feature is fully functional.
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: Verification against the success criteria in spec.md (SC-001 … SC-008), plus accessibility, performance, and final pre-PR checks.
+
+- [ ] T019 [P] Run Lighthouse on `/` (Chrome DevTools → Lighthouse → Accessibility, mobile + desktop). Confirm the Accessibility score is ≥ 95 and that no findings reference elements under `.rn-faq`. (Verifies SC-005 and supports SC-004.)
+- [ ] T020 [P] Run axe DevTools (browser extension) on `/`. Confirm zero violations. Pay particular attention to color-contrast rules under `.rn-faq` and `.rn-faq-answer` in both light and dark themes. (Verifies SC-005.)
+- [ ] T021 [P] Keyboard-only test on `/`: Tab through the page; confirm each `<summary>` receives focus with a visible outline; press Enter on a focused `<summary>` and confirm the entry expands; press Space and confirm it collapses; Tab again and confirm focus moves into the answer's first link (when present). (Verifies SC-004.)
+- [ ] T022 [P] Theme contrast check: toggle the site theme between light and dark via the theme switch in the navbar; on each, verify the FAQ heading, question text, and answer text meet WCAG AA contrast ratios (≥ 4.5:1 for body text). Use the browser's color-picker if needed. (Verifies SC-005 and FR-009.)
+- [ ] T023 [P] Performance check: capture a baseline LCP for `/` against `main` (no FAQ) using Chrome DevTools Performance panel or the Web Vitals extension; capture LCP on the feature branch; confirm the new value is within 10% of baseline. (Verifies SC-007.)
+- [ ] T024 [P] Search indexing check: trigger the site's search (the navbar search button) and search for a phrase that appears only inside an FAQ answer; confirm the home page is returned in results. If Hextra search needs an index rebuild step, run it. (Verifies FR-013.)
+- [ ] T025 Run the maintainer flow end-to-end against `specs/001-faq-section/quickstart.md`: follow each step in the "add a new FAQ entry" section, including verifying the deep-link URL afterward. Time the experience and confirm it stays under 10 minutes (SC-003). Restore the file when done.
+- [ ] T026 Confirm zero-entry behavior (FR-012): in a scratch branch (or via temporary edit), set `entries: []` in `data/faq.yaml` and reload `/`. Confirm no `<section class="rn-faq">` appears in the rendered HTML and the home page renders cleanly. Restore the file.
+- [ ] T027 Open a pull request to `main` titled `feat: add Frequently Asked Questions section to home page`. PR body: link to `specs/001-faq-section/spec.md`, summarize the three user stories, and call out the verification done in T019–T026. Do NOT include `[skip netlify]` — the Netlify preview deploy is the final visual check.
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1 (Setup)**: No dependencies. Start immediately.
+- **Phase 2 (Foundational)**: Depends on Phase 1. Blocks all user stories.
+- **Phase 3 (US1)**: Depends on Phase 2. Delivers the MVP.
+- **Phase 4 (US2)**: Depends on Phase 2; can layer on top of US1 work or run in parallel after T005 lands (the validation logic in T011–T013 modifies the same `rn-faq.html` file as US1, so practical ordering is US1 → US2).
+- **Phase 5 (US3)**: Depends on Phase 2; the deep-link script is appended to the same shortcode, so practical ordering is US1 → US3 (US2 and US3 can swap order or interleave).
+- **Phase 6 (Polish)**: Depends on Phases 3–5 being complete (or on whichever user stories you elected to ship).
+
+### User Story Dependencies
+
+- **US1**: No dependency on other stories. Ships alone as a complete MVP.
+- **US2**: No functional dependency on US1, but practical: validation/comments are easier to add once the rendering loop exists. Can be deferred (a maintainer can already edit `data/faq.yaml` after US1).
+- **US3**: No functional dependency on US1, but the deep-link script targets ids that US1 produces. Could ship without US3; deep-links would still scroll-to-anchor (browser default) but not auto-expand.
+
+### Within a User Story
+
+- Tasks that touch the same file (`layouts/shortcodes/rn-faq.html` is the main one) must run sequentially within a story. The task ordering above respects this.
+- Verification tasks (T010, T016, T018) come last within their story.
+
+### Parallel Opportunities
+
+- **Phase 2**: T002 (data file) and T003 (shortcode skeleton) touch different files → both `[P]`.
+- **Phase 6**: T019–T024 are all read-only verification activities against the running site → all `[P]`.
+- Inside US1: T004–T007 all edit `rn-faq.html`, so they are sequential. T008 (`_index.md`) and T009 (`faq.yaml`) touch different files; either order works once T004–T007 are done.
+- Across stories with multiple developers: once Phase 2 lands, US1 has to ship before US2 and US3 add their layers to `rn-faq.html`. With a single developer, the linear order in this document is the recommended path.
+
+---
+
+## Parallel Example: Phase 2
+
+```bash
+# Both files can be created concurrently:
+Task: "Create data/faq.yaml with placeholder entry"               # T002 [P]
+Task: "Create layouts/shortcodes/rn-faq.html empty-state skeleton" # T003 [P]
+```
+
+## Parallel Example: Phase 6 verifications
+
+```bash
+# All read-only checks can run concurrently against `hugo server`:
+Task: "Lighthouse accessibility audit on /"                  # T019 [P]
+Task: "axe DevTools scan on /"                               # T020 [P]
+Task: "Keyboard-only navigation test on /"                   # T021 [P]
+Task: "Theme contrast check (light + dark)"                  # T022 [P]
+Task: "LCP comparison vs. baseline"                          # T023 [P]
+Task: "Search indexing check"                                # T024 [P]
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 only)
+
+1. Phase 1 (T001).
+2. Phase 2 (T002, T003).
+3. Phase 3 (T004 → T010).
+4. **STOP and validate**: open `/`, exercise all acceptance scenarios in spec.md US1.
+5. Optionally ship the MVP — the FAQ is fully usable for visitors.
+
+### Incremental Delivery
+
+1. MVP per above.
+2. Add US2 (T011 → T016) → run the maintainer flow (T025-style mini-check) → ship.
+3. Add US3 (T017 → T018) → verify deep-linking → ship.
+4. Polish (T019 → T027) → open PR.
+
+### Single-Developer Recommended Path
+
+1. T001.
+2. T002, T003 in parallel.
+3. T004 → T010 sequentially.
+4. T011 → T016 sequentially.
+5. T017 → T018 sequentially.
+6. T019 → T024 in parallel.
+7. T025, T026, T027 sequentially.
+
+---
+
+## Notes
+
+- This is a Hugo static site; "tasks" map to template/data edits and verification, not to traditional source code. There is no test framework to add.
+- All shortcode logic lives in **one file** (`layouts/shortcodes/rn-faq.html`) by design (matches `rn-buttons.html` precedent). Keep it that way unless the file grows past ~150 lines.
+- Commit after each task or each logical group. Use conventional commits (`feat:`, `docs:`, `chore:`).
+- Stop at any checkpoint to demo or ship — every user story is independently shippable.
+- Avoid: adding a JS framework, adding a CSS file, modifying `hugo.yaml` navigation, modifying the Hextra theme module.

From b9db2bb0a4da44965c498465816060bfe6850764 Mon Sep 17 00:00:00 2001
From: Yibei Chen <yibeichan@gmail.com>
Date: Wed, 29 Apr 2026 19:49:35 -0400
Subject: [PATCH 2/3] docs: promote FAQ maintainer guide to docs/, drop process
 artifacts

- Move specs/001-faq-section/quickstart.md to docs/maintaining-faq.md
  and refit its framing from "feature spec appendix" to standalone
  maintainer guide. The file lives outside content/, so Hugo does
  not render it on the website.
- Remove the other speckit process files (spec, plan, research,
  data-model, tasks, contracts/, checklists/). They were one-time
  design notes; the production code, data/faq.yaml header comment,
  CONTRIBUTING.md, and docs/maintaining-faq.md are the durable docs.
- Add a hidden HTML comment in content/_index.md next to the
  {{< rn-faq >}} call so anyone landing there via the site's
  "Edit this page" link is pointed at data/faq.yaml.
- Update the link in CONTRIBUTING.md and in the data/faq.yaml header
  comment to the new docs/ path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CONTRIBUTING.md                               |   2 +-
 content/_index.md                             |   1 +
 data/faq.yaml                                 |   2 +-
 .../quickstart.md => docs/maintaining-faq.md  |   5 +-
 .../checklists/requirements.md                |  37 ---
 .../contracts/faq-shortcode.md                | 113 ----------
 specs/001-faq-section/data-model.md           |  75 -------
 specs/001-faq-section/plan.md                 |  83 -------
 specs/001-faq-section/research.md             | 165 --------------
 specs/001-faq-section/spec.md                 | 122 ----------
 specs/001-faq-section/tasks.md                | 211 ------------------
 11 files changed, 5 insertions(+), 811 deletions(-)
 rename specs/001-faq-section/quickstart.md => docs/maintaining-faq.md (95%)
 delete mode 100644 specs/001-faq-section/checklists/requirements.md
 delete mode 100644 specs/001-faq-section/contracts/faq-shortcode.md
 delete mode 100644 specs/001-faq-section/data-model.md
 delete mode 100644 specs/001-faq-section/plan.md
 delete mode 100644 specs/001-faq-section/research.md
 delete mode 100644 specs/001-faq-section/spec.md
 delete mode 100644 specs/001-faq-section/tasks.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1e48043b..2bc11c01 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -47,7 +47,7 @@ Once approved, a maintainer will merge your PR. If your changes need revision, f
 
 ## Editing the home page FAQ
 
-The Frequently Asked Questions section on the home page is generated from a single data file: [`data/faq.yaml`](./data/faq.yaml). To add, edit, reorder, or remove a question, edit that file directly via the GitHub web UI (no template or layout changes are needed for ordinary content edits). The file's header comment documents the schema; for a longer walkthrough see [`specs/001-faq-section/quickstart.md`](./specs/001-faq-section/quickstart.md).
+The Frequently Asked Questions section on the home page is generated from a single data file: [`data/faq.yaml`](./data/faq.yaml). To add, edit, reorder, or remove a question, edit that file directly via the GitHub web UI (no template or layout changes are needed for ordinary content edits). The file's header comment documents the schema; for a longer walkthrough see [`docs/maintaining-faq.md`](./docs/maintaining-faq.md).
 
 ## Local Development
 
diff --git a/content/_index.md b/content/_index.md
index 3decc47e..424971ac 100644
--- a/content/_index.md
+++ b/content/_index.md
@@ -63,4 +63,5 @@ A national biotechnology development center dedicated to developing tools and se
     >}}
 {{< /rn-buttons >}}
 
+<!-- FAQ content lives in data/faq.yaml — see docs/maintaining-faq.md for the editing guide. -->
 {{< rn-faq >}}
diff --git a/data/faq.yaml b/data/faq.yaml
index 693139f1..b4f44467 100644
--- a/data/faq.yaml
+++ b/data/faq.yaml
@@ -18,7 +18,7 @@
 # form "faq-<slugified-question>", e.g. "faq-how-do-i-get-started". Share
 # https://repronim.org/#faq-how-do-i-get-started to deep-link directly.
 #
-# Detailed maintainer guide: specs/001-faq-section/quickstart.md
+# Detailed maintainer guide: docs/maintaining-faq.md
 
 entries:
   - question: What is ReproNim?
diff --git a/specs/001-faq-section/quickstart.md b/docs/maintaining-faq.md
similarity index 95%
rename from specs/001-faq-section/quickstart.md
rename to docs/maintaining-faq.md
index e5e3772e..4c3f2e45 100644
--- a/specs/001-faq-section/quickstart.md
+++ b/docs/maintaining-faq.md
@@ -1,10 +1,9 @@
-# Quickstart: Adding & Editing FAQ Entries
+# Maintaining the home page FAQ
 
-**Feature**: 001-faq-section
 **Audience**: ReproNim maintainers (anyone already comfortable editing site Markdown via GitHub)
 **Time to add a new entry**: ~5 minutes
 
-This guide assumes the FAQ feature has been implemented and shipped. If it hasn't, see `tasks.md` (created by `/speckit-tasks`) for the implementation steps.
+The Frequently Asked Questions section on the home page is generated from a single data file. This guide walks through adding, editing, reordering, and removing entries — all without touching any layout or template code.
 
 ## TL;DR
 
diff --git a/specs/001-faq-section/checklists/requirements.md b/specs/001-faq-section/checklists/requirements.md
deleted file mode 100644
index c41ef950..00000000
--- a/specs/001-faq-section/checklists/requirements.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# Specification Quality Checklist: Frequently Asked Questions Section on Home Page
-
-**Purpose**: Validate specification completeness and quality before proceeding to planning
-**Created**: 2026-04-28
-**Feature**: [spec.md](../spec.md)
-
-## Content Quality
-
-- [x] No implementation details (languages, frameworks, APIs)
-- [x] Focused on user value and business needs
-- [x] Written for non-technical stakeholders
-- [x] All mandatory sections completed
-
-## Requirement Completeness
-
-- [x] No [NEEDS CLARIFICATION] markers remain
-- [x] Requirements are testable and unambiguous
-- [x] Success criteria are measurable
-- [x] Success criteria are technology-agnostic (no implementation details)
-- [x] All acceptance scenarios are defined
-- [x] Edge cases are identified
-- [x] Scope is clearly bounded
-- [x] Dependencies and assumptions identified
-
-## Feature Readiness
-
-- [x] All functional requirements have clear acceptance criteria
-- [x] User scenarios cover primary flows
-- [x] Feature meets measurable outcomes defined in Success Criteria
-- [x] No implementation details leak into specification
-
-## Notes
-
-- Items marked incomplete require spec updates before `/speckit-clarify` or `/speckit-plan`.
-- The phrase "main tab" in the original request was interpreted as the Home page (`content/_index.md`); this is recorded explicitly in the Assumptions section so that a maintainer reviewing the spec can confirm or redirect before planning begins.
-- FR-007 references WCAG 2.1 AA. While "WCAG" is a standard rather than an implementation detail, reviewers should confirm the target conformance level is appropriate for the site.
-- The starter content (FR-014) bounds scope to 5–8 questions and a topic list; exact wording is intentionally deferred to maintainers.
diff --git a/specs/001-faq-section/contracts/faq-shortcode.md b/specs/001-faq-section/contracts/faq-shortcode.md
deleted file mode 100644
index d40e985e..00000000
--- a/specs/001-faq-section/contracts/faq-shortcode.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# Contract: `rn-faq` Hugo Shortcode
-
-**Feature**: 001-faq-section
-**Date**: 2026-04-28
-
-This is the public contract the FAQ shortcode exposes to the rest of the site. It defines the input it consumes, the output HTML it produces, and the interaction guarantees that downstream tests (manual + automated accessibility) can verify against.
-
-## Invocation
-
-In a content file (e.g., `content/_index.md`):
-
-```markdown
-{{< rn-faq >}}
-```
-
-The shortcode takes **no positional or named arguments**. All content comes from `site.Data.faq`.
-
-Optional named argument (future-friendly, not used at v1):
-
-| Argument | Type   | Default | Purpose |
-|----------|--------|---------|---------|
-| `title`  | string | `"Frequently Asked Questions"` | Override the section heading text. |
-
-## Input contract
-
-The shortcode reads `site.Data.faq.entries` (i.e., the `entries:` list inside `data/faq.yaml`).
-
-- If `data/faq.yaml` does not exist, or `entries` is missing, or `entries` is empty: the shortcode emits **no output**.
-- If `entries` is non-empty: each item must conform to the schema in `data-model.md`. Invalid items are skipped with a Hugo build warning; the rest still render.
-
-## Output contract
-
-For a non-empty `entries` list, the shortcode emits this HTML structure:
-
-```html
-<section class="rn-faq" aria-labelledby="rn-faq-heading">
-  <h2 id="rn-faq-heading">Frequently Asked Questions</h2>
-
-  <details id="faq-what-is-repronim" class="rn-faq-item">
-    <summary>What is ReproNim?</summary>
-    <div class="rn-faq-answer">
-      <!-- markdownified answer HTML -->
-    </div>
-  </details>
-
-  <details id="faq-how-do-i-get-started" class="rn-faq-item">
-    <summary>How do I get started?</summary>
-    <div class="rn-faq-answer">
-      <!-- markdownified answer HTML -->
-    </div>
-  </details>
-
-  <!-- one <details> per entry, in YAML order -->
-
-  <style>/* scoped styles for .rn-faq, .rn-faq-item, .rn-faq-answer */</style>
-  <script>/* deep-link expansion handler */</script>
-</section>
-```
-
-### Guaranteed properties
-
-- The wrapping element is a `<section>` with class `rn-faq` and an `aria-labelledby` pointing at the heading. Assistive tech announces the section as a named region.
-- The heading is `<h2>` so it slots correctly under the home page's `<h1>` title.
-- Each entry is a `<details>` element with:
-  - A unique `id` (per `data-model.md` rules).
-  - The class `rn-faq-item`.
-  - A child `<summary>` containing the plain-text question.
-  - A child `<div class="rn-faq-answer">` containing the rendered Markdown answer.
-- No `open` attribute is set server-side — every entry renders collapsed (FR-002a).
-- The `<style>` and `<script>` blocks are scoped to `.rn-faq` selectors and behavior — they do not affect the rest of the page.
-
-### Style guarantees
-
-The scoped CSS must:
-
-- Inherit text color and background from the active theme so light/dark mode work without overrides (FR-009).
-- Provide adequate spacing between entries (≥ 0.75 rem vertical) and a visible focus ring on `<summary>` for keyboard users.
-- Maintain WCAG 2.1 AA contrast (FR-007). Don't override Hextra's link colors inside `.rn-faq-answer`.
-- Replace the default disclosure triangle with a styled chevron only if the substitution preserves accessibility — otherwise leave the browser default (acceptable per FR-007).
-
-### Script guarantees
-
-The inline `<script>` must:
-
-- Run on initial load and on every `hashchange`.
-- If the URL hash matches the `id` of an `<details>` inside `.rn-faq`, set `open = true` and call `scrollIntoView({ block: 'start' })`.
-- Do nothing else. No analytics, no state mutation outside the targeted element, no event listeners on `<summary>` (the browser handles those natively).
-- Be wrapped in an IIFE to avoid leaking globals.
-
-## Behavioral guarantees (verifiable from this contract)
-
-| ID  | Behavior | How to verify |
-|-----|----------|---------------|
-| C1  | Section is hidden when no entries exist | Remove `data/faq.yaml`; rebuild; confirm no `<section class="rn-faq">` in `public/index.html`. |
-| C2  | Entries render in YAML order | View page source; confirm `<details>` ids appear in the same order as YAML list. |
-| C3  | Each entry collapsed by default (no anchor) | Load `/`; confirm no `<details>` has the `open` attribute. |
-| C4  | Deep link opens the targeted entry | Load `/#faq-how-do-i-get-started`; confirm the matching `<details>` has `open=true` and is in view. |
-| C5  | Invalid anchor is harmless | Load `/#faq-does-not-exist`; confirm the page renders normally with all entries collapsed. |
-| C6  | Multiple entries can be open simultaneously | Click two `<summary>` elements; confirm both stay open. |
-| C7  | Keyboard operable | Tab to a `<summary>`; press Enter or Space; confirm it expands; press again to collapse. |
-| C8  | Screen-reader expanded state | Inspect with VoiceOver/NVDA; confirm `<summary>` announces expanded/collapsed correctly (provided natively by `<details>`). |
-| C9  | Theme adaptation | Toggle light/dark; confirm contrast meets AA in both. |
-| C10 | Markdown links in answers work | Add an answer with `[link](/about/)`; click it; confirm navigation. |
-| C11 | Search indexing | Site search returns FAQ answer text when querying for a phrase that appears only in an answer. |
-
-## Non-contract (intentionally unspecified)
-
-These are implementation freedoms left to whoever writes the shortcode:
-
-- The exact CSS values (colors, font sizes, spacing) — must respect theme tokens and contrast, but specific numbers are tunable.
-- Whether to use a custom chevron `::after` pseudo-element or the browser default disclosure triangle.
-- Whether to memoize `urlize` results across iterations (a Hugo perf detail with no observable effect).
-- Future expansion: optional `title` argument and optional per-entry `tag` field for grouping. Not in v1.
diff --git a/specs/001-faq-section/data-model.md b/specs/001-faq-section/data-model.md
deleted file mode 100644
index 7fffba08..00000000
--- a/specs/001-faq-section/data-model.md
+++ /dev/null
@@ -1,75 +0,0 @@
-# Phase 1 Data Model: FAQ Entries
-
-**Feature**: 001-faq-section
-**Date**: 2026-04-28
-
-There is one entity in this feature, stored in **`data/faq.yaml`** and consumed by the `rn-faq` Hugo shortcode.
-
-## Entity: FAQ Entry
-
-| Field      | Type   | Required | Description |
-|------------|--------|----------|-------------|
-| `question` | string | Yes      | The question text. Plain text, no Markdown (renders inside `<summary>`). Should be written naturally — sentence case, ending with `?`. |
-| `answer`   | string | Yes      | The answer body. Markdown — supports paragraphs, links, lists, emphasis, inline code. Authored using a YAML literal block scalar (`|`). |
-| `id`       | string | No       | Optional explicit anchor override. Lowercase, kebab-case, alphanumeric + hyphens only. If omitted, defaults to `faq-{{ urlize question }}`. |
-
-## File: `data/faq.yaml`
-
-The data file has a single top-level key `entries` whose value is an ordered list of FAQ Entry objects. Order in the list = render order on the page.
-
-```yaml
-entries:
-  - question: What is ReproNim?
-    answer: |
-      ReproNim is a national biotechnology development center dedicated to
-      tools and services for reproducible neuroimaging. See the
-      [About page](/about/) for more.
-
-  - question: How do I get started?
-    answer: |
-      Visit the [Getting Started](/resources/getting-started/) page for an
-      overview, or browse the [tools page](/resources/tools/).
-
-  - id: fellowship-apply
-    question: How do I apply to the ReproNim Fellowship?
-    answer: |
-      Application details and the current cycle are on the
-      [Fellowship page](/fellowship/).
-```
-
-## Validation rules
-
-These are enforced by the shortcode template at render time. Failures during `hugo build` mean the home page won't deploy until the YAML is fixed — surfacing problems to the maintainer immediately.
-
-1. **`question` is non-empty.** A blank question would produce an empty `<summary>` and an unreachable id. The shortcode skips entries with no `question` and emits a build warning.
-2. **`answer` is non-empty.** A missing answer makes the entry pointless. Skipped with warning.
-3. **Anchor uniqueness.** The shortcode tracks ids it has already emitted in the current page; on a duplicate, it appends `-2`, `-3`, etc. to disambiguate, and emits a build warning so the maintainer can fix the source. (Two distinct questions can occasionally produce the same slug, e.g. capitalization-only differences.)
-4. **`id` format (when provided).** Must match the regex `^[a-z0-9][a-z0-9-]*$`. Invalid ids fall back to the auto-generated slug and emit a build warning.
-
-## Anchor URL examples
-
-For a question `"How do I get started?"` with no `id` override:
-
-- Anchor: `faq-how-do-i-get-started`
-- Deep-link URL: `https://repronim.org/#faq-how-do-i-get-started`
-
-For an entry with `id: fellowship-apply`:
-
-- Anchor: `fellowship-apply`
-- Deep-link URL: `https://repronim.org/#fellowship-apply`
-
-## Lifecycle
-
-FAQ Entries have no runtime lifecycle — they are static content rebuilt each deploy. The maintainer-facing operations are:
-
-| Operation | Action |
-|-----------|--------|
-| Add | Append a new list item to `data/faq.yaml`. |
-| Edit | Modify the `question` or `answer` of an existing item. Editing the question changes its auto-generated anchor unless an explicit `id` is in place. |
-| Reorder | Move list items up/down in the YAML. |
-| Remove | Delete the list item. Outstanding deep-links to the removed anchor become inert (page loads cleanly per FR-011). |
-| Add a stable anchor to an existing entry | Add an explicit `id:` field, preferably matching the previous auto-generated slug, so existing deep-links keep working. |
-
-## Relationship to other entities
-
-None — FAQ Entries are self-contained leaf data with no foreign keys to other site content.
diff --git a/specs/001-faq-section/plan.md b/specs/001-faq-section/plan.md
deleted file mode 100644
index 7dd80c62..00000000
--- a/specs/001-faq-section/plan.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# Implementation Plan: Frequently Asked Questions Section on Home Page
-
-**Branch**: `001-faq-section` | **Date**: 2026-04-28 | **Spec**: [spec.md](./spec.md)
-**Input**: Feature specification from `/specs/001-faq-section/spec.md`
-
-## Summary
-
-Add a Frequently Asked Questions section to the ReproNim home page (`content/_index.md`), rendered by a new Hugo shortcode that reads from a single maintainer-editable data file (`data/faq.yaml`). Each entry is a question/answer pair; answers support Markdown so links, lists, and emphasis render correctly. Entries default to collapsed, support multiple open at once, expose stable URL anchors for deep-linking, and meet WCAG 2.1 AA in both light and dark themes.
-
-The implementation leans on the **HTML5 `<details>`/`<summary>` element** for the accordion behavior so semantics, keyboard interaction, and screen-reader announcement are correct by default with zero JavaScript. A small inline progressive-enhancement script handles only the deep-linking case (open the targeted `<details>` and scroll to it on page load and on `hashchange`).
-
-## Technical Context
-
-**Language/Version**: Hugo 0.132.2 (extended), Hextra theme v0.8.3 (Go module)
-**Primary Dependencies**: Hugo Go templates, Hextra theme; no new runtime dependencies, no JS framework, no build tooling beyond Hugo itself
-**Storage**: Static; FAQ entries stored in `data/faq.yaml` (committed to the repo)
-**Testing**: Manual verification via `hugo server` + an automated accessibility check (axe DevTools or Lighthouse) on the home page; no test framework added
-**Target Platform**: Static site served via Netlify; supported browsers per the existing site (last two major versions of Chrome, Firefox, Safari, Edge)
-**Project Type**: Static documentation/content site (Hugo + Hextra)
-**Performance Goals**: Home page LCP must stay within 10% of pre-launch value (per SC-007); no additional render-blocking assets
-**Constraints**: Must work without JavaScript for read-only viewing (NoJS users still see all answers when they click `<details>`); only deep-linking degrades to "anchor scrolls but entry stays closed" without JS; must honor the existing light/dark theme toggle; no changes to the top navigation
-**Scale/Scope**: Single page surface; 5–8 entries at launch (per FR-014), expected to grow to ≤30 over the foreseeable life of the section
-
-## Constitution Check
-
-*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
-
-The repository's `.specify/memory/constitution.md` is the unfilled template — no project-specific principles have been ratified, so there are no formal gates to evaluate. Applying the workspace-level standards from `/Users/yibeichen/Documents/GitHub/CLAUDE.md` and the existing site conventions instead:
-
-| Standard | Status | Notes |
-|----------|--------|-------|
-| Use existing tech stack (Hugo + Hextra) | Pass | No new framework, no JS bundle, no build step changes |
-| Markdown-first content authoring | Pass | Answers authored as Markdown in YAML; rendered with `markdownify` |
-| Accessibility (WCAG 2.1 AA) | Pass by design | Native `<details>`/`<summary>` carries semantics; theme contrast already AA |
-| No console/debug noise in commits | Pass | Inline JS is ~15 lines, scoped, no logging |
-| Conventional commits | Pass | Implementation will use `feat: …` |
-| `[skip netlify]` flag awareness | N/A | Used only for non-deploy commits |
-
-**Result**: No violations. No `Complexity Tracking` entries needed. Re-checked after Phase 1 design — still no violations.
-
-## Project Structure
-
-### Documentation (this feature)
-
-```text
-specs/001-faq-section/
-├── plan.md              # This file
-├── research.md          # Phase 0 output
-├── data-model.md        # Phase 1 output
-├── quickstart.md        # Phase 1 output (how a maintainer adds an entry)
-├── contracts/
-│   └── faq-shortcode.md # Phase 1 output (input data schema + output HTML contract)
-├── checklists/
-│   └── requirements.md  # Spec quality checklist (already created)
-└── tasks.md             # Phase 2 output (created later by /speckit-tasks)
-```
-
-### Source Code (repository root)
-
-This is a Hugo static site, not a traditional code project. The feature lands in the existing site layout:
-
-```text
-repronim.org/
-├── content/
-│   └── _index.md                       # Home page — add {{< rn-faq >}} shortcode call
-├── data/
-│   └── faq.yaml                        # NEW — maintainer-edited FAQ entries
-├── layouts/
-│   └── shortcodes/
-│       └── rn-faq.html                 # NEW — renders the FAQ section from data/faq.yaml
-├── static/                             # (unchanged) inline JS lives in the shortcode
-└── hugo.yaml                           # (unchanged) — no menu/config changes; stays on Home tab
-```
-
-**Structure Decision**: Add **one** new shortcode (`layouts/shortcodes/rn-faq.html`) and **one** new data file (`data/faq.yaml`). Modify **one** existing file (`content/_index.md`) to invoke the shortcode below the existing intro and `rn-buttons` block. No CSS file is added; styles are scoped inside the shortcode (matching the precedent set by `rn-buttons.html`, which inlines its `<style>`). No changes to `hugo.yaml`, navigation, or the theme module.
-
-This is the minimum surface area that satisfies all functional requirements and matches the existing per-feature convention used by `rn-button` / `rn-buttons` / `wordpress-posts` / `people` / `fellows-resources`.
-
-## Complexity Tracking
-
-> **Fill ONLY if Constitution Check has violations that must be justified**
-
-No constitution violations. Section intentionally left empty.
diff --git a/specs/001-faq-section/research.md b/specs/001-faq-section/research.md
deleted file mode 100644
index c6f383e6..00000000
--- a/specs/001-faq-section/research.md
+++ /dev/null
@@ -1,165 +0,0 @@
-# Phase 0 Research: FAQ Section on Home Page
-
-**Feature**: 001-faq-section
-**Date**: 2026-04-28
-
-The Technical Context for this feature has no `NEEDS CLARIFICATION` markers — Hugo, Hextra, the data-file pattern, and the deployment pipeline are already in use across the site. The remaining open questions are *implementation choices* that the spec leaves to planning. Each is resolved below with a decision, rationale, and the alternatives that were considered.
-
----
-
-## R1. Accordion mechanism: native `<details>` vs. custom JS
-
-**Decision**: Use the HTML5 `<details>`/`<summary>` element as the primitive for each FAQ entry, with Markdown-rendered answer content inside.
-
-**Rationale**:
-- Built-in semantics: keyboard focus, Enter/Space toggling, and `aria-expanded` state are handled by the browser. This satisfies FR-007 and SC-004 with no extra ARIA wiring.
-- Zero JavaScript required for the core expand/collapse behavior. Visitors with JS disabled still get a fully functional FAQ.
-- HTML5 `<details>` is supported in every browser the site targets (last two majors of Chrome, Firefox, Safari, Edge — universal since ~2020).
-- Multiple entries can be open simultaneously by default, satisfying FR-003. We deliberately do **not** group entries with `name="faq"` (HTML5 exclusive accordions), because that would force collapsing one to view another.
-- Theme-friendly: `<summary>` is a normal element that inherits color and font tokens from the Hextra theme; no theme-specific styling is needed beyond a small marker tweak.
-
-**Alternatives considered**:
-- *Custom `<button aria-expanded>` + `<div role="region">`*: requires hand-rolled keyboard handling and ARIA management. More code, more risk of accessibility regression. Rejected.
-- *Hextra's `card` or `callout` shortcode reused as a faux accordion*: not designed for this purpose; would not collapse and would not deep-link cleanly. Rejected.
-- *A third-party accordion JS library*: adds a dependency for a feature that the platform handles natively. Rejected.
-
----
-
-## R2. Content storage: data file vs. Markdown shortcode-per-entry vs. content bundle
-
-**Decision**: Store entries in **`data/faq.yaml`**, a single YAML file with an `entries:` list, each item having `question`, `answer` (Markdown string), and an optional `id` override. The shortcode reads this file via `site.Data.faq`.
-
-**Rationale**:
-- One source of truth. A maintainer adds, removes, or reorders entries by editing one file via the existing GitHub "Edit this page" workflow. Satisfies FR-005 and SC-003.
-- Order in the YAML list = render order. Satisfies FR-006.
-- Matches the established site precedent: `data/fellows-2024.yaml`, `data/repronim-team.yaml`, `data/publications.yaml` are all structured YAML consumed by shortcodes/partials.
-- Markdown answers are rendered with Hugo's `markdownify` function, so links, lists, inline code, and emphasis work without special handling. Satisfies FR-004.
-- Anchors are derived deterministically from the question via Hugo's `urlize` (or `anchorize`) function, with an explicit `id` override available for stability if a question is reworded later. Satisfies FR-010.
-
-**Alternatives considered**:
-- *Per-entry shortcode calls inside `_index.md`* (e.g., `{{< rn-faq-item q="..." >}}` with body content): more verbose, harder to reorder, mixes structure and content in a single file. Rejected.
-- *Hugo content bundle under `content/faq/` with one Markdown page per entry*: overkill for a section-of-a-page feature; pulls in page-level concerns (taxonomies, list templates) that we don't need. Rejected.
-- *Front matter list in `_index.md`*: works for tiny lists but conflates page metadata with body content. Rejected for clarity.
-
----
-
-## R3. Deep-linking and default expansion state
-
-**Decision**: All entries render with `<details>` collapsed (no `open` attribute) on the server. A tiny inline `<script>` inside the shortcode runs on `DOMContentLoaded` and on `hashchange`: if `window.location.hash` matches an FAQ entry's id, set its `open` attribute and scroll it into view.
-
-**Rationale**:
-- Server-rendered HTML matches FR-002a (all collapsed by default) for the no-anchor case.
-- The script is ~15 lines, defer-safe, has no dependencies, and degrades gracefully — without JS, an anchor still scrolls the visitor to the closed entry; the visitor can still click to open it.
-- `hashchange` handling means an in-page link to another FAQ entry also opens the target.
-- This pattern is well-established (used by GitHub Markdown, MDN, and many docs sites).
-
-**Implementation sketch** (will live inside `rn-faq.html`):
-
-```html
-<script>
-(function () {
-  function openFromHash() {
-    var hash = window.location.hash;
-    if (!hash || hash.length < 2) return;
-    var el = document.getElementById(hash.substring(1));
-    if (el && el.tagName === 'DETAILS') {
-      el.open = true;
-      el.scrollIntoView({ block: 'start' });
-    }
-  }
-  if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', openFromHash);
-  } else {
-    openFromHash();
-  }
-  window.addEventListener('hashchange', openFromHash);
-})();
-</script>
-```
-
-**Alternatives considered**:
-- *Server-render the targeted entry with `open` based on a query param*: Hugo SSG cannot read the URL hash at build time, and using a query param instead of a hash is non-standard for in-page anchors. Rejected.
-- *Open all entries when JS is disabled*: defeats the "compact by default" goal and violates FR-002a. Rejected.
-
----
-
-## R4. Markdown-in-YAML answers
-
-**Decision**: Author answers in YAML using a literal block scalar (`|`) and render with Hugo's `markdownify` function in the template.
-
-**Example**:
-
-```yaml
-- question: How do I get started with ReproNim?
-  answer: |
-    See the [Getting Started](/resources/getting-started/) page for an overview,
-    or jump straight to the [tools page](/resources/tools/) to find a specific tool.
-```
-
-**Rationale**:
-- Block scalars preserve newlines and let authors write multi-paragraph answers naturally.
-- `markdownify` is the standard Hugo function for inline Markdown rendering and supports the same Goldmark configuration as the rest of the site (including `markup.goldmark.renderer.unsafe = true` from `hugo.yaml`, which allows raw HTML if a maintainer ever needs it).
-- Keeps the editing experience identical to other Markdown content on the site.
-
-**Alternatives considered**:
-- *Plain-string answers (no Markdown)*: would block links and formatting. Violates FR-004. Rejected.
-- *Separate Markdown files referenced from YAML*: doubles file count per entry for marginal benefit. Rejected.
-
----
-
-## R5. Anchor (id) generation
-
-**Decision**: Default the `<details>` `id` to `faq-{{ .question | urlize }}`. If the YAML entry provides an explicit `id:` field, use that verbatim (still namespaced under the FAQ section by convention).
-
-**Rationale**:
-- `urlize` produces a slug compatible with the existing Hextra heading-anchor convention.
-- The `faq-` prefix avoids id collisions with any heading anchor on the home page.
-- The explicit override lets maintainers preserve a stable link if a question's wording is updated. This is the same trade-off Wikipedia uses for section-anchor stability.
-
-**Alternatives considered**:
-- *Numeric ids based on list index* (`faq-1`, `faq-2`, …): unstable across reorderings. Rejected.
-- *Hash of question text*: opaque to humans; a reworded question silently breaks links anyway. Rejected.
-
----
-
-## R6. Search indexing
-
-**Decision**: Take no special action — Hextra's built-in search (Pagefind/FlexSearch via the theme) already indexes home-page content, so the rendered FAQ is included automatically. Verify in the quickstart.
-
-**Rationale**:
-- Satisfies FR-013 with zero additional configuration. The shortcode renders normal HTML (not in a Web Component, not behind JS) so the indexer reads it like any other content.
-
-**Alternatives considered**:
-- *Add explicit search metadata*: not needed; would be redundant. Rejected.
-
----
-
-## R7. Empty-state behavior
-
-**Decision**: The shortcode checks `len site.Data.faq.entries`. If there are zero entries, the shortcode emits **no output at all** (not even an empty `<section>` or heading). If there are entries, it emits the full section.
-
-**Rationale**:
-- Satisfies FR-012 directly: an empty FAQ produces no visible artifact, no broken layout, no orphan heading.
-- Lets the home page exist without a `data/faq.yaml` file at all (the shortcode also defends against the entire data key being absent).
-
-**Alternatives considered**:
-- *Render heading + "Coming soon" placeholder*: worse UX than just not showing the section. Rejected.
-
----
-
-## R8. Performance impact
-
-**Decision**: No additional fetch, no new font, no new image. The shortcode contributes a small inline `<style>` block (similar in size to `rn-buttons.html`) and a ~15-line inline `<script>`. The data file is consumed at build time.
-
-**Rationale**:
-- No network requests are added beyond the home-page HTML itself, so SC-007 (LCP within 10% of pre-launch) is met by construction.
-- Inline assets defeat HTTP caching but are tiny (under ~2 KB combined uncompressed) and avoid extra round trips. This matches the precedent set by other `rn-*` shortcodes.
-
-**Alternatives considered**:
-- *Move CSS/JS to `static/` files for caching*: would be the right call at much larger sizes; for ~2 KB total, the inline form is faster overall and keeps the shortcode self-contained. Reject for v1; revisit if the FAQ grows substantially.
-
----
-
-## Open items
-
-None. All resolutions are deterministic and ready for Phase 1.
diff --git a/specs/001-faq-section/spec.md b/specs/001-faq-section/spec.md
deleted file mode 100644
index f4a90996..00000000
--- a/specs/001-faq-section/spec.md
+++ /dev/null
@@ -1,122 +0,0 @@
-# Feature Specification: Frequently Asked Questions Section on Home Page
-
-**Feature Branch**: `001-faq-section`
-**Created**: 2026-04-28
-**Status**: Draft
-**Input**: User description: "let's add a 'frequently asked' section in the main tab"
-
-## Clarifications
-
-### Session 2026-04-28
-
-- Q: Should deep-linking to specific FAQ entries (URL anchors that auto-expand the targeted entry) be in scope for v1? → A: Yes — keep deep-linking in scope (FR-010/FR-011/SC-008 stand).
-- Q: Where should the FAQ live? → A: As a section on the Home page (`/`, `content/_index.md`), below the existing intro and section buttons. No new top-nav entry; no standalone `/faq/` page.
-- Q: What is the default expansion state of FAQ entries on first load (no anchor in URL)? → A: All entries collapsed by default; visitor expands the ones they want. Deep-linked entries (URL anchor present) still open expanded per FR-010.
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Visitor finds answers to common questions on the home page (Priority: P1)
-
-A first-time visitor lands on the ReproNim home page wanting to understand what the center offers, who it serves, and how to get started. Instead of navigating across multiple sub-pages, they scroll down and find a Frequently Asked Questions section that surfaces concise answers to the questions newcomers most often ask.
-
-**Why this priority**: This is the core value of the feature. Without it, the home page only links to other pages and forces visitors to hunt for basic answers, which increases bounce rate and email volume to `info@repronim.org`. P1 because the entire feature exists to serve this journey.
-
-**Independent Test**: A visitor opens the home page in a browser, scrolls past the existing intro and section buttons, sees a clearly-labeled "Frequently Asked Questions" section with at least one question, expands a question, and reads the answer. The feature is valuable on day one even if only a small starter set of questions is published.
-
-**Acceptance Scenarios**:
-
-1. **Given** a visitor on the home page, **When** they scroll past the existing top-of-page content (banner, intro, section buttons), **Then** they see a section clearly titled as the FAQ with a list of questions.
-2. **Given** the FAQ section is displayed, **When** the visitor selects a question, **Then** the corresponding answer becomes visible without navigating away from the home page.
-3. **Given** an answer is expanded, **When** the visitor selects the same question again (or another expanded question), **Then** the answer collapses, keeping the page tidy.
-4. **Given** a visitor wants more depth on a topic covered in the FAQ, **When** they read the answer, **Then** the answer may include a link to the relevant deeper resource (e.g., a tutorial, the tools page, or the help page).
-
----
-
-### User Story 2 - Maintainer adds, edits, and removes FAQ entries (Priority: P2)
-
-A ReproNim maintainer (the same audience already editing other content via GitHub) needs to be able to add new questions, revise existing answers, and remove entries that are no longer relevant — without involving a developer or touching layout code.
-
-**Why this priority**: The FAQ is only useful if the team can keep it current. P2 because the visitor-facing experience (P1) can launch with a small initial set, but ongoing usefulness depends on easy editing.
-
-**Independent Test**: A maintainer opens the editable content for the FAQ via the existing "Edit this page" workflow used elsewhere on the site, adds a new question/answer pair, commits the change, and confirms the new entry appears on the home page after the next deploy.
-
-**Acceptance Scenarios**:
-
-1. **Given** a maintainer wants to add an FAQ entry, **When** they edit a single content source for the FAQ section, **Then** the new question and answer appear on the home page after deployment without code changes.
-2. **Given** an existing entry needs revision, **When** the maintainer updates that entry's answer text, **Then** only that answer changes on the home page; ordering and other entries remain stable.
-3. **Given** an entry is no longer relevant, **When** the maintainer removes that entry, **Then** it disappears from the home page and no broken anchors remain.
-
----
-
-### User Story 3 - Visitor links directly to a specific question (Priority: P3)
-
-A staff member answering an email or a community member posting in a forum wants to share a direct link that opens the ReproNim home page with a specific FAQ entry already visible.
-
-**Why this priority**: Deep-linking improves the FAQ's usefulness as a support tool but is not required for the section to deliver value. P3.
-
-**Independent Test**: A user opens a URL of the form `https://repronim.org/#<question-anchor>`, the page loads, scrolls to the FAQ section, and the targeted question is expanded and visible.
-
-**Acceptance Scenarios**:
-
-1. **Given** a URL with an FAQ entry's anchor, **When** the page loads, **Then** the FAQ section is reached and the targeted question is in its expanded state.
-2. **Given** an anchor that does not match any current FAQ entry, **When** the page loads, **Then** the home page renders normally with no error and the FAQ section in its default state.
-
----
-
-### Edge Cases
-
-- The FAQ has zero entries (e.g., during initial setup or while content is being prepared): the section either is hidden or shows a brief placeholder, but the home page must not appear broken.
-- The FAQ has many entries (e.g., 25+): the section remains scannable; visitors can still locate a question without excessive scrolling.
-- An answer contains rich content (links, lists, inline code): the answer renders correctly within the expanded view and remains readable.
-- The visitor uses a screen reader or keyboard-only navigation: each question is reachable, focusable, and operable, and the expanded/collapsed state is announced.
-- The visitor views the home page on a small mobile screen: the FAQ is fully usable, with tap targets large enough to operate and answers wrapping cleanly.
-- The visitor switches between light and dark site themes: the FAQ section honors both themes (the site already supports a theme toggle).
-- A visitor arrives via an outdated deep link to a question that has since been removed: the page loads cleanly and presents the FAQ in default state.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The home page MUST display a clearly-titled Frequently Asked Questions section, positioned below the existing intro paragraph and section buttons so it does not displace current top-of-page content.
-- **FR-002**: The FAQ section MUST present each entry as a question that can be expanded to reveal its answer and collapsed to hide it, so the page stays compact by default.
-- **FR-002a**: On initial page load, when no FAQ anchor is present in the URL, every FAQ entry MUST start in the collapsed state. (When an anchor matching an entry is present, that entry opens expanded per FR-010; all other entries still start collapsed.)
-- **FR-003**: Multiple questions MAY be expanded at the same time; the design MUST NOT force collapsing one entry to view another (this supports comparison reading).
-- **FR-004**: Each FAQ entry MUST support an answer that may include plain text, links to other site pages or external resources, and basic formatting (lists, emphasis, inline code).
-- **FR-005**: FAQ content MUST be editable through the same content workflow already used for other site pages (Markdown via GitHub-based "Edit this page"), without requiring layout or template changes for ordinary edits.
-- **FR-006**: The order in which entries are authored MUST be the order in which they appear on the page, so maintainers can curate prominence.
-- **FR-007**: The FAQ section MUST be accessible: each question is reachable by keyboard, expanded/collapsed state is exposed to assistive technology, and contrast meets WCAG 2.1 AA in both light and dark themes.
-- **FR-008**: The FAQ section MUST be responsive across desktop, tablet, and mobile breakpoints used by the rest of the site.
-- **FR-009**: The FAQ section MUST honor the site's existing light/dark theme toggle.
-- **FR-010**: Each FAQ entry MUST have a stable URL fragment (anchor) that can be used to deep-link to that entry; loading the page with such an anchor MUST scroll to the entry and present it in expanded state.
-- **FR-011**: An invalid or missing FAQ anchor in a URL MUST NOT break page rendering; the home page MUST load normally.
-- **FR-012**: When the FAQ has zero entries, the section MUST either be hidden entirely or show an unobtrusive placeholder — the home page MUST NOT show an empty heading or broken layout.
-- **FR-013**: The FAQ section MUST be discoverable by site search if site search already indexes home page content.
-- **FR-014**: The initial launch MUST include a starter set of 5–8 questions covering: what ReproNim is, who it is for, how to get started, where to find tools, how to participate, where to get help / office hours, and how to apply to the fellowship. (Final wording to be drafted by maintainers; this requirement bounds scope, not exact text.)
-
-### Key Entities *(include if feature involves data)*
-
-- **FAQ Entry**: A single question-and-answer pair shown in the FAQ section. Attributes: question text (short), answer body (formatted text, may include links), display order, and a stable anchor identifier derived from the question.
-- **FAQ Section**: The collection of FAQ Entries rendered on the home page, with a section heading and a defined position in the page layout.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A first-time visitor can locate an answer to one of the starter questions (e.g., "How do I get started?") from the home page in under 30 seconds without leaving the home page.
-- **SC-002**: At launch, the FAQ section contains at least 5 published question-and-answer pairs.
-- **SC-003**: A maintainer who is already comfortable editing other Markdown pages on the site can add a new FAQ entry end-to-end (edit, commit, deploy) in under 10 minutes, with no code changes outside the FAQ content source.
-- **SC-004**: 100% of FAQ entries are operable by keyboard alone (Tab to focus, Enter/Space to expand and collapse) and announce their expanded/collapsed state to screen readers.
-- **SC-005**: The FAQ section meets WCAG 2.1 AA contrast in both light and dark themes (verified with an automated accessibility check on the home page).
-- **SC-006**: Within 90 days of launch, the volume of inbound `info@repronim.org` emails asking the questions covered by the FAQ trends downward, measured by maintainer review of the inbox or an equivalent qualitative review.
-- **SC-007**: Adding the FAQ does not regress existing home page performance: the home page's largest contentful paint stays within 10% of its pre-launch value on a typical broadband connection.
-- **SC-008**: Deep links to specific FAQ entries succeed (the targeted entry is visible and expanded) on at least the latest two major versions of the browsers the rest of the site supports.
-
-## Assumptions
-
-- The FAQ lives as a section on the **Home** page (`/`, rendered from `content/_index.md`), below the existing intro and section buttons. Confirmed via clarification on 2026-04-28. No standalone `/faq/` page and no new top-nav entry are introduced by this feature.
-- Initial FAQ content will be authored by ReproNim maintainers; this spec does not prescribe the exact wording of questions or answers, only the topic coverage and minimum count at launch.
-- The existing site theme (Hextra-based Hugo theme), navigation, and content-editing workflow continue to be used; no new content management system is introduced.
-- The FAQ uses a familiar expand/collapse interaction pattern (an accordion-style list) because it is the conventional, accessible default for FAQ sections; alternatives (e.g., always-open list, modal dialogs) are out of scope unless the maintainers choose otherwise during planning.
-- Translation/i18n is out of scope for this feature; the FAQ ships in the same language as the rest of the home page.
-- Analytics for tracking which FAQ entries are most expanded is out of scope for v1 but compatible with the existing Google Analytics integration if added later.
-- The starter set of 5–8 questions is sufficient for launch; ongoing growth of the FAQ is a maintenance activity, not part of this feature's delivery.
diff --git a/specs/001-faq-section/tasks.md b/specs/001-faq-section/tasks.md
deleted file mode 100644
index 05bc8a1e..00000000
--- a/specs/001-faq-section/tasks.md
+++ /dev/null
@@ -1,211 +0,0 @@
----
-
-description: "Task list for feature 001-faq-section"
----
-
-# Tasks: Frequently Asked Questions Section on Home Page
-
-**Input**: Design documents from `/specs/001-faq-section/`
-**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/faq-shortcode.md, quickstart.md
-
-**Tests**: Automated tests are NOT requested by the spec. This is a Hugo static site with no test framework; verification is manual (`hugo server`) plus accessibility tooling (Lighthouse, axe DevTools, keyboard test). Verification tasks are explicit in the Polish phase.
-
-**Organization**: Tasks are grouped by user story (US1, US2, US3 from spec.md) so each story can be implemented and validated as an independent increment.
-
-## Format: `[ID] [P?] [Story] Description`
-
-- **[P]**: Can run in parallel (different files, no dependency on incomplete tasks).
-- **[Story]**: User story this task belongs to (US1 = P1 visitor view, US2 = P2 maintainer editing, US3 = P3 deep-linking).
-- File paths are absolute or repo-rooted as appropriate.
-
-## Path Conventions
-
-This is a Hugo + Hextra static site. The relevant paths are:
-
-- `content/_index.md` — home page content
-- `data/faq.yaml` — FAQ data (new file)
-- `layouts/shortcodes/rn-faq.html` — FAQ shortcode (new file)
-- `CONTRIBUTING.md` — existing contributor guide (will be linked, not rewritten)
-
----
-
-## Phase 1: Setup (Shared Infrastructure)
-
-**Purpose**: Confirm the local Hugo + Hextra environment is ready. No code changes here.
-
-- [X] T001 Verify the Hugo dev environment runs cleanly: from the repo root run `hugo server -D` and confirm the home page loads at `http://localhost:1313/` with no template errors and no missing-module warnings. If `hugo` is not installed, install Hugo extended ≥ 0.132.2 (matching `netlify.toml`) before continuing.
-
----
-
-## Phase 2: Foundational (Blocking Prerequisites)
-
-**Purpose**: Create the empty file scaffolding that every user story builds on. Both files must exist before US1 work begins.
-
-**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
-
-- [X] T002 [P] Create the data file `data/faq.yaml` with a top-level `entries:` key holding **one placeholder item** (`question:` + `answer:` using the `|` block scalar) so the shortcode has something to read during initial wiring. The real content replaces this placeholder in T008.
-- [X] T003 [P] Create the shortcode skeleton `layouts/shortcodes/rn-faq.html` with the empty-state guard only: an outer Go-template `{{ with site.Data.faq }}{{ with .entries }}` … `{{ end }}{{ end }}` block that emits nothing when `data/faq.yaml` is missing or `entries` is empty. Confirm by temporarily removing the placeholder and verifying no output is rendered, then restore it.
-
-**Checkpoint**: Foundation ready — User Story 1 can begin.
-
----
-
-## Phase 3: User Story 1 — Visitor finds answers on the home page (Priority: P1) 🎯 MVP
-
-**Goal**: A first-time visitor lands on the home page, sees a clearly titled FAQ section below the existing intro and section buttons, can expand any question to read its answer, and can collapse it again. Multiple entries can be open at once. Section honors light/dark theme and meets WCAG 2.1 AA contrast.
-
-**Independent Test**: Run `hugo server`, open `/`, scroll past the legacy banner / intro / `rn-buttons` block, see "Frequently Asked Questions" with 5–8 entries, click any question to expand, click again to collapse, click two questions to confirm both stay open. Toggle the site theme; verify the section reads correctly in both light and dark.
-
-### Implementation for User Story 1
-
-- [X] T004 [US1] In `layouts/shortcodes/rn-faq.html`, add the section wrapper: `<section class="rn-faq" aria-labelledby="rn-faq-heading">` with an `<h2 id="rn-faq-heading">Frequently Asked Questions</h2>`. Place it inside the empty-state guard from T003 so it only renders when entries exist. Reference `contracts/faq-shortcode.md` for the exact element/attribute names.
-- [X] T005 [US1] In `layouts/shortcodes/rn-faq.html`, implement the entry rendering loop: `{{ range .entries }}` … `{{ end }}` emitting one `<details class="rn-faq-item" id="…">` per entry with `<summary>{{ .question }}</summary>` and `<div class="rn-faq-answer">{{ .answer | markdownify }}</div>`. Do **not** set the `open` attribute (FR-002a). Order = YAML order (FR-006).
-- [X] T006 [US1] In `layouts/shortcodes/rn-faq.html`, implement anchor id generation: if `.id` is set on the entry use it verbatim; otherwise compute `printf "faq-%s" (urlize .question)`. Use the result as the `<details id="…">` value (per `data-model.md` and contract C2/C4).
-- [X] T007 [US1] In `layouts/shortcodes/rn-faq.html`, append a scoped `<style>` block at the end of the section (mirroring the precedent set by `layouts/shortcodes/rn-buttons.html`). Style only `.rn-faq`, `.rn-faq-item`, `.rn-faq-item > summary`, and `.rn-faq-answer`. Required: vertical spacing ≥ 0.75rem between entries; visible focus ring on `<summary>` (`:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }`); cursor: pointer on `<summary>`; inherit color/background from the theme so light/dark both work (FR-009); do not override link colors inside `.rn-faq-answer`.
-- [X] T008 [US1] In `content/_index.md`, append `{{< rn-faq >}}` on its own line **after** the closing `{{< /rn-buttons >}}` so the FAQ section sits below the existing intro and section buttons, not above them.
-- [X] T009 [US1] In `data/faq.yaml`, replace the T002 placeholder with the launch starter set: 5–8 entries covering (per FR-014) "what ReproNim is", "who it is for", "how to get started", "where to find tools", "how to participate", "where to get help / office hours", and "how to apply to the fellowship." Use the YAML literal block scalar (`|`) for each `answer:`. Where natural, link to the relevant existing page (`/about/`, `/resources/getting-started/`, `/resources/tools/`, `/participate/`, `/help/`, `/fellowship/`). Reference `data-model.md` for the exact schema and `quickstart.md` for the editing pattern.
-- [ ] T010 [US1] Verify US1 acceptance: from `hugo server`, load `/`, confirm the FAQ section renders below `rn-buttons` with 5–8 collapsed entries; expand one, expand a second (confirm both stay open per FR-003); collapse one; toggle the theme switcher and confirm both light and dark mode render with readable contrast.
-
-**Checkpoint**: User Story 1 fully delivers the MVP. The home page now has a working FAQ that is visible to visitors. Could be shipped as-is.
-
----
-
-## Phase 4: User Story 2 — Maintainer adds, edits, and removes entries (Priority: P2)
-
-**Goal**: A maintainer can manage the FAQ via the existing GitHub edit workflow without touching layout code. The shortcode degrades gracefully on malformed entries and surfaces problems in the Hugo build log.
-
-**Independent Test**: Have a maintainer (or simulate one) (a) add a new entry to `data/faq.yaml`, rebuild, confirm it appears in YAML order; (b) edit an existing entry's `answer`, rebuild, confirm only that answer changed; (c) delete an entry, rebuild, confirm it's gone and no broken anchor remains; (d) introduce a malformed entry (empty `question`), rebuild, confirm a Hugo `warnf` appears and the rest of the FAQ still renders.
-
-### Implementation for User Story 2
-
-- [X] T011 [US2] In `layouts/shortcodes/rn-faq.html`, add input validation inside the entry loop: skip entries where `.question` or `.answer` is empty/unset, and emit a Hugo build warning via `warnf` describing the skip. Reference `data-model.md` validation rules 1 and 2.
-- [X] T012 [US2] In `layouts/shortcodes/rn-faq.html`, add duplicate-id detection: track ids seen in the current page (use a `dict`/`slice` accumulator), and on a duplicate append `-2`, `-3`, … as a suffix while emitting a `warnf`. Reference `data-model.md` validation rule 3.
-- [X] T013 [US2] In `layouts/shortcodes/rn-faq.html`, validate the `id` field format when explicitly provided: if it does not match `^[a-z0-9][a-z0-9-]*$`, fall back to the auto-generated slug and emit a `warnf`. Reference `data-model.md` validation rule 4.
-- [X] T014 [US2] In `data/faq.yaml`, add a header comment block (lines starting with `#`) at the top of the file documenting the schema (`question`, `answer`, optional `id`), the literal block scalar usage, and a one-line link to the maintainer guide at `specs/001-faq-section/quickstart.md`. Goal: a maintainer opening the file in GitHub sees how to add an entry without leaving the file.
-- [X] T015 [US2] In `CONTRIBUTING.md`, add a short section titled "Editing the home page FAQ" with a 2–3 sentence pointer to `data/faq.yaml` and a link to `specs/001-faq-section/quickstart.md`. Place it after any existing "How to edit pages" section, or at the end if no comparable section exists. Do not duplicate the full quickstart — link to it.
-- [ ] T016 [US2] Verify US2 acceptance: temporarily add an entry, edit one, delete one, and introduce a malformed entry in `data/faq.yaml`. For each step run `hugo server` (or watch the running server reload), confirm the rendered page reflects the change and the build log behaves per T011/T012/T013. Restore the file before moving on.
-
-**Checkpoint**: User Stories 1 AND 2 both work independently. Maintainers can keep the FAQ current without engineering involvement.
-
----
-
-## Phase 5: User Story 3 — Visitor deep-links to a specific question (Priority: P3)
-
-**Goal**: A URL of the form `https://repronim.org/#<faq-anchor>` opens the home page with the targeted FAQ entry already expanded and scrolled into view. Invalid anchors degrade gracefully (page renders normally per FR-011).
-
-**Independent Test**: With the dev server running, open `http://localhost:1313/#faq-how-do-i-get-started` (or whichever anchor maps to a real entry); confirm the matching `<details>` is `open` and visible. Then open `http://localhost:1313/#faq-does-not-exist`; confirm the page renders with all entries collapsed and no JS errors in the console.
-
-### Implementation for User Story 3
-
-- [X] T017 [US3] In `layouts/shortcodes/rn-faq.html`, append a scoped inline `<script>` at the end of the section. Wrap in an IIFE; define an `openFromHash` function that reads `window.location.hash`, looks up the matching `<details>` by id, sets `el.open = true`, and calls `el.scrollIntoView({ block: 'start' })`. Bind the function to `DOMContentLoaded` (or run immediately if the document is already past `loading`) and to `hashchange`. Reference the implementation sketch in `research.md` § R3.
-- [ ] T018 [US3] Verify US3 acceptance: with `hugo server` running, (a) load `/#<existing-anchor>`, confirm the targeted entry opens and scrolls into view; (b) load `/#faq-does-not-exist`, confirm the page renders with no console error and all entries collapsed; (c) while on `/`, manually change the URL hash in the address bar to a different valid anchor and press Enter, confirm `hashchange` triggers expansion of the new target.
-
-**Checkpoint**: All three user stories are complete. Feature is fully functional.
-
----
-
-## Phase 6: Polish & Cross-Cutting Concerns
-
-**Purpose**: Verification against the success criteria in spec.md (SC-001 … SC-008), plus accessibility, performance, and final pre-PR checks.
-
-- [ ] T019 [P] Run Lighthouse on `/` (Chrome DevTools → Lighthouse → Accessibility, mobile + desktop). Confirm the Accessibility score is ≥ 95 and that no findings reference elements under `.rn-faq`. (Verifies SC-005 and supports SC-004.)
-- [ ] T020 [P] Run axe DevTools (browser extension) on `/`. Confirm zero violations. Pay particular attention to color-contrast rules under `.rn-faq` and `.rn-faq-answer` in both light and dark themes. (Verifies SC-005.)
-- [ ] T021 [P] Keyboard-only test on `/`: Tab through the page; confirm each `<summary>` receives focus with a visible outline; press Enter on a focused `<summary>` and confirm the entry expands; press Space and confirm it collapses; Tab again and confirm focus moves into the answer's first link (when present). (Verifies SC-004.)
-- [ ] T022 [P] Theme contrast check: toggle the site theme between light and dark via the theme switch in the navbar; on each, verify the FAQ heading, question text, and answer text meet WCAG AA contrast ratios (≥ 4.5:1 for body text). Use the browser's color-picker if needed. (Verifies SC-005 and FR-009.)
-- [ ] T023 [P] Performance check: capture a baseline LCP for `/` against `main` (no FAQ) using Chrome DevTools Performance panel or the Web Vitals extension; capture LCP on the feature branch; confirm the new value is within 10% of baseline. (Verifies SC-007.)
-- [ ] T024 [P] Search indexing check: trigger the site's search (the navbar search button) and search for a phrase that appears only inside an FAQ answer; confirm the home page is returned in results. If Hextra search needs an index rebuild step, run it. (Verifies FR-013.)
-- [ ] T025 Run the maintainer flow end-to-end against `specs/001-faq-section/quickstart.md`: follow each step in the "add a new FAQ entry" section, including verifying the deep-link URL afterward. Time the experience and confirm it stays under 10 minutes (SC-003). Restore the file when done.
-- [ ] T026 Confirm zero-entry behavior (FR-012): in a scratch branch (or via temporary edit), set `entries: []` in `data/faq.yaml` and reload `/`. Confirm no `<section class="rn-faq">` appears in the rendered HTML and the home page renders cleanly. Restore the file.
-- [ ] T027 Open a pull request to `main` titled `feat: add Frequently Asked Questions section to home page`. PR body: link to `specs/001-faq-section/spec.md`, summarize the three user stories, and call out the verification done in T019–T026. Do NOT include `[skip netlify]` — the Netlify preview deploy is the final visual check.
-
----
-
-## Dependencies & Execution Order
-
-### Phase Dependencies
-
-- **Phase 1 (Setup)**: No dependencies. Start immediately.
-- **Phase 2 (Foundational)**: Depends on Phase 1. Blocks all user stories.
-- **Phase 3 (US1)**: Depends on Phase 2. Delivers the MVP.
-- **Phase 4 (US2)**: Depends on Phase 2; can layer on top of US1 work or run in parallel after T005 lands (the validation logic in T011–T013 modifies the same `rn-faq.html` file as US1, so practical ordering is US1 → US2).
-- **Phase 5 (US3)**: Depends on Phase 2; the deep-link script is appended to the same shortcode, so practical ordering is US1 → US3 (US2 and US3 can swap order or interleave).
-- **Phase 6 (Polish)**: Depends on Phases 3–5 being complete (or on whichever user stories you elected to ship).
-
-### User Story Dependencies
-
-- **US1**: No dependency on other stories. Ships alone as a complete MVP.
-- **US2**: No functional dependency on US1, but practical: validation/comments are easier to add once the rendering loop exists. Can be deferred (a maintainer can already edit `data/faq.yaml` after US1).
-- **US3**: No functional dependency on US1, but the deep-link script targets ids that US1 produces. Could ship without US3; deep-links would still scroll-to-anchor (browser default) but not auto-expand.
-
-### Within a User Story
-
-- Tasks that touch the same file (`layouts/shortcodes/rn-faq.html` is the main one) must run sequentially within a story. The task ordering above respects this.
-- Verification tasks (T010, T016, T018) come last within their story.
-
-### Parallel Opportunities
-
-- **Phase 2**: T002 (data file) and T003 (shortcode skeleton) touch different files → both `[P]`.
-- **Phase 6**: T019–T024 are all read-only verification activities against the running site → all `[P]`.
-- Inside US1: T004–T007 all edit `rn-faq.html`, so they are sequential. T008 (`_index.md`) and T009 (`faq.yaml`) touch different files; either order works once T004–T007 are done.
-- Across stories with multiple developers: once Phase 2 lands, US1 has to ship before US2 and US3 add their layers to `rn-faq.html`. With a single developer, the linear order in this document is the recommended path.
-
----
-
-## Parallel Example: Phase 2
-
-```bash
-# Both files can be created concurrently:
-Task: "Create data/faq.yaml with placeholder entry"               # T002 [P]
-Task: "Create layouts/shortcodes/rn-faq.html empty-state skeleton" # T003 [P]
-```
-
-## Parallel Example: Phase 6 verifications
-
-```bash
-# All read-only checks can run concurrently against `hugo server`:
-Task: "Lighthouse accessibility audit on /"                  # T019 [P]
-Task: "axe DevTools scan on /"                               # T020 [P]
-Task: "Keyboard-only navigation test on /"                   # T021 [P]
-Task: "Theme contrast check (light + dark)"                  # T022 [P]
-Task: "LCP comparison vs. baseline"                          # T023 [P]
-Task: "Search indexing check"                                # T024 [P]
-```
-
----
-
-## Implementation Strategy
-
-### MVP First (User Story 1 only)
-
-1. Phase 1 (T001).
-2. Phase 2 (T002, T003).
-3. Phase 3 (T004 → T010).
-4. **STOP and validate**: open `/`, exercise all acceptance scenarios in spec.md US1.
-5. Optionally ship the MVP — the FAQ is fully usable for visitors.
-
-### Incremental Delivery
-
-1. MVP per above.
-2. Add US2 (T011 → T016) → run the maintainer flow (T025-style mini-check) → ship.
-3. Add US3 (T017 → T018) → verify deep-linking → ship.
-4. Polish (T019 → T027) → open PR.
-
-### Single-Developer Recommended Path
-
-1. T001.
-2. T002, T003 in parallel.
-3. T004 → T010 sequentially.
-4. T011 → T016 sequentially.
-5. T017 → T018 sequentially.
-6. T019 → T024 in parallel.
-7. T025, T026, T027 sequentially.
-
----
-
-## Notes
-
-- This is a Hugo static site; "tasks" map to template/data edits and verification, not to traditional source code. There is no test framework to add.
-- All shortcode logic lives in **one file** (`layouts/shortcodes/rn-faq.html`) by design (matches `rn-buttons.html` precedent). Keep it that way unless the file grows past ~150 lines.
-- Commit after each task or each logical group. Use conventional commits (`feat:`, `docs:`, `chore:`).
-- Stop at any checkpoint to demo or ship — every user story is independently shippable.
-- Avoid: adding a JS framework, adding a CSS file, modifying `hugo.yaml` navigation, modifying the Hextra theme module.

From ce32cb55fa76bced9ffb8c97c9427e006dfd1914 Mon Sep 17 00:00:00 2001
From: Yibei Chen <yibeichan@gmail.com>
Date: Mon, 4 May 2026 15:39:31 -0400
Subject: [PATCH 3/3] fix: offset deep-link scroll past Hextra's sticky navbar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Hextra's navbar sticks to the top of the viewport (height ~ 4rem from
the theme's --navbar-height variable). When a visitor opens a deep link
like /#faq-some-question, the inline script's scrollIntoView would
position the targeted entry at the very top of the document, hidden
behind the sticky navbar.

Adds scroll-margin-top to .rn-faq-item using the theme's variable so
the targeted entry lands cleanly below the navbar with a small buffer.
The fallback (4rem) keeps the behavior reasonable if the variable
is ever missing.

Verified headlessly: scroll-margin-top resolves to 72px in Chromium;
deep-linked entry's top position sits ≥ navbar bottom edge (64px)
after the inline script runs.

Addresses gemini-code-assist review feedback on PR #468.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 layouts/shortcodes/rn-faq.html | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/layouts/shortcodes/rn-faq.html b/layouts/shortcodes/rn-faq.html
index 48f825b4..413dd955 100644
--- a/layouts/shortcodes/rn-faq.html
+++ b/layouts/shortcodes/rn-faq.html
@@ -63,6 +63,9 @@ <h2 id="rn-faq-heading">Frequently Asked Questions</h2>
     .rn-faq-item {
       border-top: 1px solid rgba(127, 127, 127, 0.3);
       padding: 0.75rem 0;
+      /* Offset deep-link scroll so the targeted entry lands below the
+         Hextra sticky navbar (--navbar-height) instead of behind it. */
+      scroll-margin-top: calc(var(--navbar-height, 4rem) + 0.5rem);
     }
     .rn-faq-item:last-of-type {
       border-bottom: 1px solid rgba(127, 127, 127, 0.3);