Merge pull request 'feat: similar schools nearby on the detail page' (#150) from feat/similar-schools-nearby into main

Reviewed-on: #150

backend/app.py

@@ -41,7 +41,7 @@ from .data_loader import get_data_info as get_db_info
 from . import flags
 from .places import build_place_index, build_place_registry, places_for_urn
 from .schemas import METRIC_DEFINITIONS, PHASE_GROUPS, RANKING_COLUMNS, SCHOOL_COLUMNS
-from .nearby_schools import select_nearby
+from .similar_schools import is_secondary_phase, select_similar
 from .utils import clean_for_json, convert_to_native
 
 # Values to exclude from filter dropdowns (empty strings, non-applicable labels)
@@ -266,23 +266,25 @@ def _places_payload(urn: int) -> list[dict]:
     return payload
 
 
-def _nearby_schools_payload(urn: int) -> list[dict]:
+def _similar_schools_payload(urn: int, phase: str | None) -> list[dict]:
-    """The nearest eligible schools this page may offer, closest first.
+    """Nearby schools this page may offer as alternatives.
-
-    Phase and reach are read from the school's own row inside select_nearby,
-    so nothing here can hand it a phase that disagrees with the data.
 
     Wrapped: a failure in selection must never 500 a page that is otherwise
     complete, which is the posture get_supplementary_data already takes. The
     section simply does not render.
     """
     try:
-        return select_nearby(load_latest_school_data(), int(urn))
+        # Decided in similar_schools, beside the PHASE_GROUPS bucket it selects
+        # from, so the two cannot drift. A substring test for "secondary" here
+        # would miss "16 plus" and hand a sixth-form college the primary bucket.
+        return select_similar(
+            load_latest_school_data(), int(urn), is_secondary_phase(phase)
+        )
     except Exception:
         import logging
 
         logging.getLogger(__name__).exception(
-            "Nearby schools selection failed for urn=%s", urn
+            "Similar schools selection failed for urn=%s", urn
         )
         return []
 
@@ -997,10 +999,11 @@ async def get_school_details(request: Request, urn: int):
         # and authority both fall below the publish threshold has nowhere to
         # point, and the page renders without the module.
         "places": _places_payload(urn),
-        # The nearest eligible schools, closest first. Always present on a
+        # Nearby schools of the same phase and a comparable intake. Always
-        # build with this code; the frontend treats absent and empty
+        # present on a build with this code; the frontend treats absent and
-        # identically, which is what lets the two images deploy independently.
+        # empty identically, which is what lets the two images deploy
-        "nearby_schools": _nearby_schools_payload(urn),
+        # independently.
+        "similar_schools": _similar_schools_payload(urn, latest.get("phase")),
         "yearly_data": clean_for_json(school_data),
         # Supplementary data (null if not yet populated by Kestra)
         "ofsted": supplementary.get("ofsted"),

backend/schemas.py

@@ -536,7 +536,7 @@ RANKING_COLUMNS = [
 # include. All-through schools appear in both primary and secondary results,
 # which is why this is a set per phase rather than a single string comparison.
 #
-# Lives here rather than in app.py because nearby_schools.py needs it too, and
+# Lives here rather than in app.py because similar_schools.py needs it too, and
 # importing app from there would be a cycle.
 PHASE_GROUPS: dict[str, set[str]] = {
     "primary": {"primary", "middle deemed primary", "all-through"},

backend/similar_schools.py

@@ -1,24 +1,17 @@
 """Which nearby schools a detail page may offer as alternatives.
 
-HARD FILTERS decide eligibility, and encode claims the section is not allowed
+Two kinds of rule, and they are not interchangeable.
-to make. A selective school is not an alternative to a non-selective one, a
-special school is not comparable to a mainstream one, and a Girls school is not
-an option for a Boys school's reader. They never relax, at any distance, even
-where that means the section does not render at all.
 
-DISTANCE decides the order, and nothing else does.
+HARD FILTERS encode claims the section is not allowed to make. A selective
+school is not an alternative to a non-selective one, a special school is not
+comparable to a mainstream one, and a Girls school is not an option for a Boys
+school's reader. These never relax, at any distance, even where that means the
+section does not render at all.
 
-An earlier version ranked by intake similarity first and used distance only as
+SOFT PREFERENCES describe how closely an intake resembles this school's. They
-a tiebreak. That put a Catholic school 2.9 miles away above the community
+relax in tiers, and every card reports the tier that actually took it so the
-school 0.3 miles down the road, and — because the row filled from the best tier
+page can say what is shared rather than implying more. They relax only far
-before widening — filled all six slots with faith matches while omitting every
+enough to reach a usable set, never far enough to fill the last of the slots.
-school a parent could actually walk to. For a primary, a school that far is not
-a weaker option; it is not an option. Distance is a constraint and intake is a
-preference, and the ranking now says so.
-
-Similarity survives as `shared`: what a candidate genuinely has in common with
-this school, reported on its card, so a reader applies their own weighting
-instead of having ours applied for them.
 
 Pure functions over a DataFrame: no I/O, no FastAPI, no database.
 """
@@ -32,21 +25,19 @@ import pandas as pd
 
 from .schemas import PHASE_GROUPS
 
-# Three fit the row; the rest are behind the carousel arrows.
+# A cap, not a quota: the section shows everything that qualified at the tiers
+# it used, up to this many. Three fit the row; the rest are behind the arrows.
 MAX_SCHOOLS = 6
+# Tiers stop relaxing once this many have been found. Without it, a cap of six
+# would reliably drag in tier-3 schools ten miles away to fill a row that three
+# good matches had already earned.
+ENOUGH = 3
 MINIMUM = 2
 
-# How far the section will reach, in miles, when nothing closer exists.
+# (tier, radius in miles). Faith relaxes before gender: a faith mismatch
-#
+# changes the character of a school, while a gender mismatch can mean the
-# A sanity bound rather than a target: ordering by distance already handles
+# school is not available to this reader's child at all.
-# density, so a school in a dense area fills all six slots inside a mile and
+TIERS: tuple[tuple[int, float], ...] = ((1, 3.0), (2, 5.0), (3, 10.0))
-# never sees this. It decides one thing — what happens where the area is
-# sparse — and the answer differs by phase because catchments do. Primary
-# catchments are routinely under a mile; beyond two, a primary is not a weaker
-# option but not an option, and no section is the honest answer.
-PRIMARY_RADIUS_MILES = 2.0
-SECONDARY_RADIUS_MILES = 6.0
-POST16_RADIUS_MILES = 10.0
 
 EARTH_RADIUS_MILES = 3958.8
 
@@ -89,6 +80,15 @@ def genders_compatible(a: str | None, b: str | None) -> bool:
     return not (left in single and right in single and left != right)
 
 
+def phase_label(phase: str | None) -> str:
+    text = (phase or "").strip()
+    if not text:
+        return "School"
+    if text.lower() == "all-through":
+        return "All-through school"
+    return f"{text.capitalize()} school"
+
+
 def is_secondary_phase(phase: str | None) -> bool:
     """Whether this phase takes the secondary side: secondary group membership,
     minus all-through.
@@ -107,13 +107,6 @@ def is_secondary_phase(phase: str | None) -> bool:
     return text != "all-through" and text in PHASE_GROUPS["secondary"]
 
 
-def radius_miles(phase: str | None) -> float:
-    """How far this phase's section will reach when nothing closer exists."""
-    if (phase or "").strip().lower() == "16 plus":
-        return POST16_RADIUS_MILES
-    return SECONDARY_RADIUS_MILES if is_secondary_phase(phase) else PRIMARY_RADIUS_MILES
-
-
 def _phase_group(is_secondary: bool) -> set[str]:
     return PHASE_GROUPS["secondary" if is_secondary else "primary"]
 
@@ -151,45 +144,26 @@ def _mask(series: pd.Series, predicate) -> pd.Series:
     return pd.Series([predicate(value) for value in series], index=series.index, dtype=bool)
 
 
-def _shared(subject: pd.Series, candidate: pd.Series, is_secondary: bool) -> list[str]:
+def _chips(subject: pd.Series, candidate: pd.Series, tier: int, is_secondary: bool) -> list[str]:
-    """What this candidate genuinely has in common with the subject.
+    if tier >= 3:
-
+        return [phase_label(candidate.get("phase"))]
-    Empty is a real answer, and renders no chips at all. A card claiming a
-    shared characteristic it does not have would be worse than a bare one —
-    and since these no longer affect the order, an empty list costs the school
-    nothing but its place in the row, which distance already decided.
-    """
-    shared: list[str] = []
-
-    gender = str(subject.get("gender") or "").strip()
-    if gender and str(candidate.get("gender") or "").strip().lower() == gender.lower():
-        shared.append(gender)
 
+    chips = [str(subject.get("gender") or "").strip()]
     if is_secondary:
-        policy = str(candidate.get("admissions_policy") or "").strip()
+        policy = (candidate.get("admissions_policy") or "").strip()
-        subject_policy = str(subject.get("admissions_policy") or "").strip()
+        if policy and policy.lower() not in {"not applicable", "unknown"}:
-        if (
+            chips.append(policy)
-            policy
+    if tier == 1:
-            and policy.lower() == subject_policy.lower()
+        chips.append(faith_label(candidate.get("religious_denomination")))
-            and policy.lower() not in {"not applicable", "unknown"}
+    return [chip for chip in chips if chip]
-        ):
-            shared.append(policy)
-
-    if faith_key(candidate.get("religious_denomination")) == faith_key(
-        subject.get("religious_denomination")
-    ):
-        shared.append(faith_label(candidate.get("religious_denomination")))
-
-    return shared
 
 
-def select_nearby(frame: pd.DataFrame, urn: int) -> list[dict]:
+def select_similar(frame: pd.DataFrame, urn: int, is_secondary: bool) -> list[dict]:
-    """The nearest eligible schools, closest first — at most MAX_SCHOOLS, and
+    """Up to MAX_SCHOOLS nearby schools this page may offer, or [] below MINIMUM.
-    none at all below MINIMUM.
 
-    The phase is read from the subject's own row rather than passed in, so a
+    Selected by tier, displayed by distance: the tier decides which schools
-    caller cannot hand this a phase that disagrees with the data it selects
+    earn a slot, and the render order is then closest-first, because "nearby"
-    from.
+    is the promise in the heading.
     """
     subject_rows = frame[frame["urn"] == urn]
     if subject_rows.empty:
@@ -200,9 +174,6 @@ def select_nearby(frame: pd.DataFrame, urn: int) -> list[dict]:
     if lat is None or lon is None:
         return []
 
-    phase = subject.get("phase")
-    is_secondary = is_secondary_phase(phase)
-    reach = radius_miles(phase)
     metric_key = "attainment_8_score" if is_secondary else "rwm_expected_pct"
 
     candidates = frame[frame["urn"] != urn].copy()
@@ -237,12 +208,42 @@ def select_nearby(frame: pd.DataFrame, urn: int) -> list[dict]:
         lat, lon, candidates["latitude"].values, candidates["longitude"].values
     ).round(1)
 
-    # ── Nearest first, and nothing else has a say ───────────────────────
+    # ── Soft preferences, in tiers ──────────────────────────────────────
-    within = candidates[candidates["distance_miles"] <= reach]
+    subject_faith = faith_key(subject.get("religious_denomination"))
-    if len(within) < MINIMUM:
+    subject_gender_key = (subject_gender or "").strip().lower()
+    same_gender = candidates["gender"].fillna("").str.strip().str.lower() == subject_gender_key
+    same_faith = _mask(
+        candidates["religious_denomination"], lambda d: faith_key(d) == subject_faith
+    )
+
+    tier_masks = {
+        1: same_gender & same_faith,
+        2: same_gender,
+        3: pd.Series(True, index=candidates.index),
+    }
+
+    # Descend the tiers only until the set reaches ENOUGH. The tier that gets
+    # there is the last one opened, and the remaining slots up to MAX_SCHOOLS
+    # are filled from the tiers already used — never by widening again.
+    picked: dict[int, tuple[int, pd.Series]] = {}
+    for tier, radius in TIERS:
+        within = candidates[tier_masks[tier] & (candidates["distance_miles"] <= radius)]
+        for _, row in within.sort_values("distance_miles").iterrows():
+            candidate_urn = int(row["urn"])
+            if candidate_urn in picked:
+                continue
+            picked[candidate_urn] = (tier, row)
+            if len(picked) >= MAX_SCHOOLS:
+                break
+        if len(picked) >= ENOUGH:
+            break
+
+    if len(picked) < MINIMUM:
         return []
 
-    selected = within.sort_values(["distance_miles", "urn"]).head(MAX_SCHOOLS)
+    selected = sorted(
+        picked.values(), key=lambda pair: float(pair[1]["distance_miles"])
+    )[:MAX_SCHOOLS]
     return [
         {
             "urn": int(row["urn"]),
@@ -250,10 +251,11 @@ def select_nearby(frame: pd.DataFrame, urn: int) -> list[dict]:
             "distance_miles": float(row["distance_miles"]),
             "school_type": _native(row.get("school_type")),
             "age_range": _native(row.get("age_range")),
-            "shared": _shared(subject, row, is_secondary),
+            "shared": _chips(subject, row, tier, is_secondary),
+            "tier": tier,
             "metric_value": _native(row.get(metric_key)),
             "metric_key": metric_key,
             "metric_year": _native(row.get("year")),
         }
-        for _, row in selected.iterrows()
+        for tier, row in selected
     ]

backend/tests/test_similar_schools.py

@@ -1,26 +1,19 @@
-"""Selection rules for the nearby-schools section.
+"""Selection rules for the "similar schools nearby" section.
 
-Hard filters encode claims the section is not allowed to make — that a
+The hard filters encode claims the section is not allowed to make — that a
 selective school is an alternative to a non-selective one, that a special
 school is comparable to a mainstream one, or that a Girls school is an option
-for a Boys school's reader. They decide who is eligible.
+for a Boys school's reader. They never relax. The soft preferences describe
-
+how close the intake is, and they do — but only far enough to reach a usable
-Distance decides the order, and nothing else does. An earlier version ranked by
+set, never far enough to fill the last of the six slots.
-intake similarity first, which put a Catholic school 2.9 miles away above the
-community school 0.3 miles down the road — for a primary, a school that far is
-not a weaker option, it is not an option. Similarity is now reported on the
-card and never reorders the row.
 """
 
 import numpy as np
 import pandas as pd
 
-from backend.nearby_schools import (
+from backend.similar_schools import is_secondary_phase, select_similar
-    is_secondary_phase,
-    radius_miles,
-    select_nearby,
-)
 
+# Roughly 0.7 miles apart in latitude at this longitude.
 BASE_LAT, BASE_LON = 51.5000, -0.1000
 
 
@@ -55,68 +48,16 @@ def _at(miles):
     return BASE_LAT + miles / 69.0
 
 
-# ---------------------------------------------------------------------------
+def test_returns_nearest_same_phase_schools():
-# Order: distance, and only distance
-# ---------------------------------------------------------------------------
-
-def test_returns_nearest_first():
     frame = _frame(
         _row(100001, "Subject"),
-        _row(100002, "Mid", latitude=_at(1.0)),
+        _row(100002, "Near", latitude=_at(0.5)),
-        _row(100003, "Near", latitude=_at(0.4)),
+        _row(100003, "Mid", latitude=_at(1.0)),
-        _row(100004, "Far", latitude=_at(1.8)),
+        _row(100004, "Far", latitude=_at(2.0)),
     )
-    result = select_nearby(frame, 100001)
+    result = select_similar(frame, 100001, is_secondary=False)
-    assert [s["urn"] for s in result] == [100003, 100002, 100004]
+    assert [s["urn"] for s in result] == [100002, 100003, 100004]
-    assert result[0]["distance_miles"] == 0.4
+    assert result[0]["distance_miles"] == 0.5
-
-
-def test_a_faith_match_never_outranks_a_closer_school():
-    """The reported defect. A Catholic primary surrounded by Catholic primaries
-    showed six of them and omitted the community school down the road."""
-    frame = _frame(
-        _row(100001, "St Jude's RC Primary", religious_denomination="Roman Catholic"),
-        _row(100002, "Elm Grove Primary", religious_denomination="None", latitude=_at(0.3)),
-        _row(100003, "Holy Cross RC", religious_denomination="Roman Catholic", latitude=_at(0.8)),
-        _row(100004, "Sacred Heart RC", religious_denomination="Roman Catholic", latitude=_at(1.2)),
-        _row(100005, "St Peter's RC", religious_denomination="Roman Catholic", latitude=_at(1.6)),
-    )
-    result = select_nearby(frame, 100001)
-    assert result[0]["urn"] == 100002, "the nearest school leads, whatever its intake"
-    assert [s["distance_miles"] for s in result] == sorted(s["distance_miles"] for s in result)
-
-
-def test_the_nearest_eligible_school_is_always_shown():
-    """Whatever else changes, a section titled "nearby" cannot omit the nearest
-    school while listing one four times further away."""
-    frame = _frame(
-        _row(100001, "Subject", gender="Boys", religious_denomination="Roman Catholic"),
-        _row(100002, "Nearest", gender="Mixed", religious_denomination="None", latitude=_at(0.2)),
-        *[
-            _row(100010 + n, f"Match {n}", gender="Boys",
-                 religious_denomination="Roman Catholic", latitude=_at(0.9 + n * 0.1))
-            for n in range(6)
-        ],
-    )
-    assert select_nearby(frame, 100001)[0]["urn"] == 100002
-
-
-def test_caps_at_six_taking_the_nearest():
-    frame = _frame(
-        _row(100001, "Subject"),
-        *[_row(100010 + n, f"Peer {n}", latitude=_at(0.1 * (n + 1))) for n in range(7)],
-    )
-    result = select_nearby(frame, 100001)
-    assert len(result) == 6
-    assert 100016 not in {s["urn"] for s in result}, "the seventh-nearest is the one dropped"
-
-
-def test_fewer_than_two_matches_returns_empty():
-    frame = _frame(
-        _row(100001, "Subject"),
-        _row(100002, "Only neighbour", latitude=_at(0.5)),
-    )
-    assert select_nearby(frame, 100001) == []
 
 
 def test_excludes_the_subject_school():
@@ -125,66 +66,19 @@ def test_excludes_the_subject_school():
         _row(100002, "A", latitude=_at(0.5)),
         _row(100003, "B", latitude=_at(0.6)),
     )
-    assert 100001 not in {s["urn"] for s in select_nearby(frame, 100001)}
+    assert 100001 not in {s["urn"] for s in select_similar(frame, 100001, is_secondary=False)}
 
 
-def test_a_school_is_never_listed_twice():
-    frame = _frame(
-        _row(100001, "Subject"),
-        _row(100002, "A", latitude=_at(0.5)),
-        _row(100003, "B", latitude=_at(0.6)),
-    )
-    result = select_nearby(frame, 100001)
-    assert len(result) == len({s["urn"] for s in result})
-
-
-# ---------------------------------------------------------------------------
-# Reach: a sanity bound, not a target
-# ---------------------------------------------------------------------------
-
-def test_primary_does_not_reach_past_two_miles():
-    frame = _frame(
-        _row(100001, "Subject"),
-        _row(100002, "Just inside", latitude=_at(1.9)),
-        _row(100003, "Just outside", latitude=_at(2.4)),
-        _row(100004, "Miles away", latitude=_at(4.0)),
-    )
-    # One inside the cap is below the minimum, so nothing renders at all —
-    # a primary with nothing within two miles has no nearby schools.
-    assert select_nearby(frame, 100001) == []
-
-
-def test_secondary_reaches_further_than_primary():
-    frame = _frame(
-        _row(100001, "Subject", phase="Secondary"),
-        _row(100002, "A", phase="Secondary", latitude=_at(3.0)),
-        _row(100003, "B", phase="Secondary", latitude=_at(5.5)),
-    )
-    assert {s["urn"] for s in select_nearby(frame, 100001)} == {100002, 100003}
-
-
-def test_the_cap_follows_the_phase():
-    assert radius_miles("Primary") == 2.0
-    assert radius_miles("Middle deemed primary") == 2.0
-    assert radius_miles("All-through") == 2.0
-    assert radius_miles("Secondary") == 6.0
-    assert radius_miles("Middle deemed secondary") == 6.0
-    # Post-16 is the phase people travel furthest for.
-    assert radius_miles("16 plus") == 10.0
-
-
-# ---------------------------------------------------------------------------
-# Hard filters: eligibility, never order
-# ---------------------------------------------------------------------------
-
 def test_selective_never_meets_non_selective():
     frame = _frame(
         _row(100001, "Grammar", phase="Secondary", admissions_policy="Selective"),
         _row(100002, "Comp A", phase="Secondary", admissions_policy="Non-selective", latitude=_at(0.5)),
         _row(100003, "Comp B", phase="Secondary", admissions_policy="Non-selective", latitude=_at(0.6)),
     )
-    assert select_nearby(frame, 100001) == []
+    assert select_similar(frame, 100001, is_secondary=True) == []
-    assert 100001 not in {s["urn"] for s in select_nearby(frame, 100002)}
+
+    reverse = select_similar(frame, 100002, is_secondary=True)
+    assert 100001 not in {s["urn"] for s in reverse}
 
 
 def test_special_schools_match_only_each_other():
@@ -193,8 +87,8 @@ def test_special_schools_match_only_each_other():
         _row(100002, "Mainstream A", latitude=_at(0.5)),
         _row(100003, "Mainstream B", latitude=_at(0.6)),
     )
-    assert select_nearby(frame, 100001) == []
+    assert select_similar(frame, 100001, is_secondary=False) == []
-    assert select_nearby(frame, 100002) == []
+    assert select_similar(frame, 100002, is_secondary=False) == []
 
 
 def test_boys_never_meets_girls():
@@ -204,7 +98,7 @@ def test_boys_never_meets_girls():
         _row(100003, "Mixed School", gender="Mixed", latitude=_at(0.6)),
         _row(100004, "Another Mixed", gender="Mixed", latitude=_at(0.7)),
     )
-    urns = {s["urn"] for s in select_nearby(frame, 100001)}
+    urns = {s["urn"] for s in select_similar(frame, 100001, is_secondary=False)}
     assert 100002 not in urns
     assert urns == {100003, 100004}
 
@@ -217,7 +111,80 @@ def test_closed_schools_and_missing_coordinates_are_dropped():
         _row(100004, "Good A", latitude=_at(0.6)),
         _row(100005, "Good B", latitude=_at(0.7)),
     )
-    assert {s["urn"] for s in select_nearby(frame, 100001)} == {100004, 100005}
+    assert {s["urn"] for s in select_similar(frame, 100001, is_secondary=False)} == {100004, 100005}
+
+
+def test_tiers_relax_faith_before_gender():
+    frame = _frame(
+        _row(100001, "Subject", gender="Boys", religious_denomination="Roman Catholic"),
+        # Tier 1: same gender and same faith.
+        _row(100002, "Tier one", gender="Boys", religious_denomination="Roman Catholic", latitude=_at(2.0)),
+        # Tier 2: same gender, different faith — closer, but a weaker match.
+        _row(100003, "Tier two", gender="Boys", religious_denomination="None", latitude=_at(0.5)),
+        # Tier 3: mixed gender, different faith.
+        _row(100004, "Tier three", gender="Mixed", religious_denomination="None", latitude=_at(0.6)),
+    )
+    result = select_similar(frame, 100001, is_secondary=False)
+    tier_by_urn = {s["urn"]: s["tier"] for s in result}
+    assert tier_by_urn == {100002: 1, 100003: 2, 100004: 3}
+    # Selected by tier, displayed by distance.
+    assert [s["urn"] for s in result] == [100003, 100004, 100002]
+
+
+def test_caps_at_six_taking_the_nearest():
+    frame = _frame(
+        _row(100001, "Subject"),
+        *[_row(100010 + n, f"Peer {n}", latitude=_at(0.1 * (n + 1))) for n in range(7)],
+    )
+    result = select_similar(frame, 100001, is_secondary=False)
+    assert len(result) == 6
+    # The seventh-nearest is the one dropped, not an arbitrary one.
+    assert 100016 not in {s["urn"] for s in result}
+
+
+def test_tiers_stop_once_enough_are_found():
+    """Four tier-1 matches are a usable set, so tier 2 is never opened — even
+    though it holds a school that is closer than any of them."""
+    frame = _frame(
+        _row(100001, "Subject", religious_denomination="Roman Catholic"),
+        _row(100002, "RC one", religious_denomination="Roman Catholic", latitude=_at(0.5)),
+        _row(100003, "RC two", religious_denomination="Roman Catholic", latitude=_at(0.6)),
+        _row(100004, "RC three", religious_denomination="Roman Catholic", latitude=_at(0.7)),
+        _row(100005, "RC four", religious_denomination="Roman Catholic", latitude=_at(0.8)),
+        # Closer than every one of them, but only a tier-2 match.
+        _row(100006, "Secular and nearer", religious_denomination="None", latitude=_at(0.2)),
+    )
+    result = select_similar(frame, 100001, is_secondary=False)
+    assert 100006 not in {s["urn"] for s in result}
+    assert len(result) == 4
+    assert all(s["tier"] == 1 for s in result)
+
+
+def test_a_school_is_never_taken_twice():
+    frame = _frame(
+        _row(100001, "Subject"),
+        _row(100002, "A", latitude=_at(0.5)),
+        _row(100003, "B", latitude=_at(0.6)),
+    )
+    result = select_similar(frame, 100001, is_secondary=False)
+    assert len(result) == len({s["urn"] for s in result})
+
+
+def test_fewer_than_two_matches_returns_empty():
+    frame = _frame(
+        _row(100001, "Subject"),
+        _row(100002, "Only neighbour", latitude=_at(0.5)),
+    )
+    assert select_similar(frame, 100001, is_secondary=False) == []
+
+
+def test_beyond_the_widest_radius_is_not_offered():
+    frame = _frame(
+        _row(100001, "Subject"),
+        _row(100002, "A", latitude=_at(11.0)),
+        _row(100003, "B", latitude=_at(12.0)),
+    )
+    assert select_similar(frame, 100001, is_secondary=False) == []
 
 
 def test_all_through_is_offered_on_both_phase_sides():
@@ -226,14 +193,14 @@ def test_all_through_is_offered_on_both_phase_sides():
         _row(100002, "All through", phase="All-through", latitude=_at(0.5)),
         _row(100003, "Primary peer", phase="Primary", latitude=_at(0.6)),
     )
-    assert 100002 in {s["urn"] for s in select_nearby(frame, 100001)}
+    assert 100002 in {s["urn"] for s in select_similar(frame, 100001, is_secondary=False)}
 
     secondary = _frame(
         _row(100010, "Secondary subject", phase="Secondary"),
         _row(100002, "All through", phase="All-through", latitude=_at(0.5)),
         _row(100011, "Secondary peer", phase="Secondary", latitude=_at(0.6)),
     )
-    assert 100002 in {s["urn"] for s in select_nearby(secondary, 100010)}
+    assert 100002 in {s["urn"] for s in select_similar(secondary, 100010, is_secondary=True)}
 
 
 def test_sixteen_plus_is_matched_against_secondary_not_primary():
@@ -245,10 +212,11 @@ def test_sixteen_plus_is_matched_against_secondary_not_primary():
         _row(100001, "Sixth Form College", phase="16 plus", age_range="16-19"),
         _row(100002, "Nearby Secondary", phase="Secondary", latitude=_at(0.5),
              attainment_8_score=52.0),
-        _row(100003, "Nearby College", phase="16 plus", latitude=_at(0.6)),
+        _row(100003, "Nearby College", phase="16 plus", latitude=_at(0.6),
+             attainment_8_score=np.nan),
         _row(100004, "Nearby Primary", phase="Primary", latitude=_at(0.1)),
     )
-    result = select_nearby(frame, 100001)
+    result = select_similar(frame, 100001, is_secondary=is_secondary_phase("16 plus"))
     urns = {s["urn"] for s in result}
     assert 100004 not in urns, "a primary school is not a peer for a sixth form"
     assert urns == {100002, 100003}
@@ -256,20 +224,18 @@ def test_sixteen_plus_is_matched_against_secondary_not_primary():
 
 
 def test_is_secondary_phase_agrees_with_the_phase_groups_it_selects_from():
+    """The two must not drift: whatever this calls secondary decides which
+    PHASE_GROUPS bucket the candidates come from."""
     for phase in ("Secondary", "Middle deemed secondary", "16 plus"):
         assert is_secondary_phase(phase) is True, phase
     for phase in ("Primary", "Middle deemed primary", "Nursery", "", None):
         assert is_secondary_phase(phase) is False, phase
     # In PHASE_GROUPS an all-through school is on both sides, but it renders
-    # with the primary template, and the metric follows the phase side.
+    # with the primary template, and the metric follows the template.
     assert is_secondary_phase("All-through") is False
 
 
-# ---------------------------------------------------------------------------
+def test_chips_state_only_what_the_tier_earned():
-# What the card reports
-# ---------------------------------------------------------------------------
-
-def test_shared_lists_only_what_is_actually_shared():
     frame = _frame(
         _row(100001, "Subject", phase="Secondary", gender="Mixed",
              religious_denomination="None", admissions_policy="Non-selective"),
@@ -278,47 +244,28 @@ def test_shared_lists_only_what_is_actually_shared():
         _row(100003, "Faith differs", phase="Secondary", gender="Mixed",
              religious_denomination="Church of England", admissions_policy="Non-selective", latitude=_at(0.6)),
     )
-    by_urn = {s["urn"]: s for s in select_nearby(frame, 100001)}
+    by_urn = {s["urn"]: s for s in select_similar(frame, 100001, is_secondary=True)}
     assert by_urn[100002]["shared"] == ["Mixed", "Non-selective", "No religious character"]
     assert by_urn[100003]["shared"] == ["Mixed", "Non-selective"]
 
 
-def test_a_shared_faith_is_named():
+def test_tier_three_chip_is_the_plain_phase():
     frame = _frame(
-        _row(100001, "Subject", religious_denomination="Roman Catholic"),
+        _row(100001, "Subject", gender="Boys"),
-        _row(100002, "Also RC", religious_denomination="Roman Catholic", latitude=_at(0.4)),
+        _row(100002, "A", gender="Mixed", latitude=_at(0.5)),
-        _row(100003, "Secular", religious_denomination="None", latitude=_at(0.5)),
+        _row(100003, "B", gender="Mixed", latitude=_at(0.6)),
     )
-    by_urn = {s["urn"]: s for s in select_nearby(frame, 100001)}
+    result = select_similar(frame, 100001, is_secondary=False)
-    assert "Roman Catholic" in by_urn[100002]["shared"]
+    assert all(s["shared"] == ["Primary school"] for s in result)
-    assert by_urn[100003]["shared"] == ["Mixed"]
 
 
-def test_shared_is_empty_when_nothing_is_shared():
+def test_metric_follows_the_template_not_the_neighbour():
-    frame = _frame(
-        _row(100001, "Subject", gender="Boys", religious_denomination="Roman Catholic"),
-        _row(100002, "A", gender="Mixed", religious_denomination="None", latitude=_at(0.4)),
-        _row(100003, "B", gender="Mixed", religious_denomination="Church of England", latitude=_at(0.5)),
-    )
-    assert all(s["shared"] == [] for s in select_nearby(frame, 100001))
-
-
-def test_no_tier_is_reported_because_there_are_no_tiers():
-    frame = _frame(
-        _row(100001, "Subject"),
-        _row(100002, "A", latitude=_at(0.4)),
-        _row(100003, "B", latitude=_at(0.5)),
-    )
-    assert all("tier" not in s for s in select_nearby(frame, 100001))
-
-
-def test_metric_follows_the_phase_side_not_the_neighbour():
     frame = _frame(
         _row(100001, "Subject", phase="Secondary", attainment_8_score=50.0),
         _row(100002, "A", phase="Secondary", attainment_8_score=52.8, latitude=_at(0.5)),
         _row(100003, "B", phase="Secondary", attainment_8_score=np.nan, latitude=_at(0.6)),
     )
-    by_urn = {s["urn"]: s for s in select_nearby(frame, 100001)}
+    by_urn = {s["urn"]: s for s in select_similar(frame, 100001, is_secondary=True)}
     assert by_urn[100002]["metric_key"] == "attainment_8_score"
     assert by_urn[100002]["metric_value"] == 52.8
     assert by_urn[100002]["metric_year"] == 202425
@@ -331,7 +278,7 @@ def test_values_are_json_safe_native_types():
         _row(100002, "A", latitude=_at(0.5)),
         _row(100003, "B", latitude=_at(0.6)),
     )
-    for school in select_nearby(frame, 100001):
+    for school in select_similar(frame, 100001, is_secondary=False):
         assert isinstance(school["urn"], int)
         assert isinstance(school["distance_miles"], float)
         assert not isinstance(school["metric_value"], np.generic)
@@ -363,10 +310,10 @@ def client(monkeypatch):
     return TestClient(app_module.app, raise_server_exceptions=False)
 
 
-def test_detail_payload_carries_nearby_schools(client):
+def test_detail_payload_carries_similar_schools(client):
     resp = client.get("/api/schools/100001")
     assert resp.status_code == 200, resp.text
-    similar = resp.json()["nearby_schools"]
+    similar = resp.json()["similar_schools"]
     assert [s["school_name"] for s in similar] == ["Neighbour A", "Neighbour B"]
     assert similar[0]["metric_key"] == "rwm_expected_pct"
 
@@ -377,7 +324,7 @@ def test_a_failure_in_selection_does_not_break_the_page(client, monkeypatch):
     def _explode(*args, **kwargs):
         raise ValueError("selection blew up")
 
-    monkeypatch.setattr(app_module, "select_nearby", _explode)
+    monkeypatch.setattr(app_module, "select_similar", _explode)
     resp = client.get("/api/schools/100001")
     assert resp.status_code == 200, resp.text
-    assert resp.json()["nearby_schools"] == []
+    assert resp.json()["similar_schools"] == []

docs/ARCHITECTURE.md

@@ -73,12 +73,12 @@ There is no SWR dependency. Leaflet maps are loaded through dynamic wrappers;
 Chart.js renders performance and comparison charts.
 
 `components/school/` contains detail sections, with section decisions and data
-preparation in `lib/schoolSections.ts`. The nearby-schools section is selected in
+preparation in `lib/schoolSections.ts`. The similar-schools section is selected
-`backend/nearby_schools.py` — hard filters decide eligibility (phase, provision,
+in `backend/similar_schools.py` — hard filters that never relax (phase,
-selectivity, gender) and distance alone decides the order, capped per phase —
+provision, selectivity, gender) and soft preferences that do (religious
-and served on `/api/schools/{urn}`. Its rules are presentation logic,
+character, then gender exactness) — and served on `/api/schools/{urn}`. Its
-deliberately kept out of `marts.*` so they can be tuned by deploy rather than by
+rules are presentation logic, deliberately kept out of `marts.*` so they can be
-pipeline run. `lib/types.ts` contains manually maintained
+tuned by deploy rather than by pipeline run. `lib/types.ts` contains manually maintained
 API types. `payload-types.ts` and the Payload import map are generated artifacts.
 
 ## Publication and caching today

docs/superpowers/specs/2026-09-21-similar-schools-nearby-design.md

@@ -1,16 +1,9 @@
-# Other Schools Nearby — Design
+# Similar Schools Nearby — Design
 
-**Date:** 2026-09-21, revised 2026-09-22
+**Date:** 2026-09-21
-**Status:** revised after staging review
+**Status:** awaiting review
 **Scope:** school detail pages, both phase templates
 
-> **Revision, 2026-09-22.** The first build ranked by intake similarity and used
-> distance as a tiebreak. On staging a Catholic primary showed six Catholic
-> primaries, none of them close enough to be a real option, and omitted the
-> community school down the road. Distance now decides the order and nothing
-> else does; the tier system is gone. The reasoning is kept below rather than
-> quietly overwritten, because the mistake is the instructive part.
-
 ## Goal
 
 Give a school detail page an answer to the question every reader arrives with
@@ -22,8 +15,7 @@ school. This section adds that edge — up to six nearby schools of the same pha
 and a comparable intake, three at a time in a carousel, each a crawlable link and
 each addable to the comparison basket in one click.
 
-Mockup, in both themes (drawn against the original tiered design, so its ledes
+Mockup, with all three tier states live in both themes:
-and chip fallbacks are one revision behind the copy specified below):
 <https://claude.ai/artifact/168KdUMcfkUeGWW2FGjuec>
 
 Source of the same page in the repo: `mockups/similar-schools-nearby.html`.
@@ -45,23 +37,19 @@ alternative, and there are three ways that claim goes wrong:
 3. A **single-sex** school of the opposite sex. Not a weak match — not an option
    at all.
 
-So the design separates two kinds of fact, and never confuses them:
+So the design separates two kinds of rule, and never confuses them:
 
-- **Hard filters** encode the claims above. They decide eligibility, and are
+- **Hard filters** encode the claims above. They are never relaxed, at any
-  never relaxed at any distance, even if that means the section does not render.
+  distance, even if that means the section does not render.
-- **Shared characteristics** — gender, religious character, selectivity —
+- **Soft preferences** describe how closely the intake resembles this school's.
-  describe how closely an intake resembles this school's. They are *reported on
+  They relax in tiers, and the card's own text always states what survived.
-  the card and never ranked on*, so the reader weighs them rather than having
-  them weighed for them.
 
-Everything below follows from that split. The revision at the top of this
+Everything below follows from that split.
-document is what happens when the second kind is treated as the first.
 
 ## Selection algorithm
 
-A backend helper, `_nearby_schools_payload(urn)` in `backend/app.py`, modelled
+A backend helper, `_similar_schools_payload(urn)` in `backend/app.py`, modelled
-on the existing `_places_payload(urn)` and delegating to
+on the existing `_places_payload(urn)` and operating on the cached
-`backend/nearby_schools.select_nearby(frame, urn)`, which operates on the cached
 `load_latest_school_data()` frame — one row per URN, already carrying
 `latitude`, `longitude`, `phase`, `gender`, `religious_denomination`,
 `admissions_policy`, `school_type` and `status`.
@@ -89,63 +77,64 @@ school the frontend treats as special for benchmarking but the backend treats as
 mainstream for matching would be dropped from its own England comparison and
 then offered as a peer to a mainstream school on the next page along.
 
-**Up to six cards, three visible.** Three fit the row; the rest are reached with
+**Up to six cards, three visible.** Six is a cap, not a quota: the section shows
-the carousel arrows. Two is the minimum that renders at all.
+every school that qualifies at the tiers it used, up to six. Three fit the row,
+and the rest are reached with the carousel arrows. Two is the minimum that
+renders at all.
 
-### Order: distance, and nothing else
+### Soft preferences, relaxed in tiers
 
-The nearest eligible schools, closest first. Similarity does not enter the
+| Tier | Additionally requires | Radius |
-ranking at any point.
+|---|---|---|
+| 1 | exact gender equality **and** same religious character | 3 miles |
+| 2 | exact gender equality | 5 miles |
+| 3 | nothing beyond the hard filters | 10 miles |
 
-**Why not, having built it the other way first.** The original design ranked by
+**Tiers relax to reach a usable set, never to fill the last slots.**
-tiers — same gender and faith within 3 miles, then same gender within 5, then
-anything within 10 — and used distance only to order the result. Two things
-followed, and both showed up on the first Catholic primary anyone looked at:
 
-- A faith match at 2.9 miles outranked a community school at 0.3 miles. For a
+Work down the tiers until the schools found so far reach three. Call the tier
-  primary, whose catchment is routinely under a mile, the far school is not a
+that got there T. The section then shows up to six schools drawn from tiers 1
-  weaker option; it is not an option.
+to T, nearest first — and does not open tier T+1 merely because six slots are
-- Because the row filled from the best tier before widening, three Catholic
+not yet full.
-  schools within 3 miles were enough to fill all six slots with Catholic
-  schools. The stopping rule that produced this had been added to prevent the
-  *opposite* failure — padding a row with weak distant matches — and made this
-  one certain.
 
-The premise was backwards. **Distance is a constraint and intake is a
+Worked through:
-preference.** A parent cannot act on a school outside their reach however well
-it matches, and they are perfectly capable of noticing a shared denomination
-for themselves if we show it to them. So similarity moved from the ranking to
-the card: `shared` reports what a school genuinely has in common, and the reader
-applies their own weighting.
 
-The hard filters above were always where the defensibility lived. They are
+| Qualifying | T | Shown |
-untouched.
+|---|---|---|
+| 14 at tier 1 | 1 | the 6 nearest tier-1 schools |
+| 4 at tier 1 | 1 | all 4 — tier 2 is never opened |
+| 2 at tier 1, 7 more at tier 2 | 2 | the 6 nearest of those 9 |
+| 2 at tier 1, 1 at tier 2 | 2 | all 3 |
+| 2 across all three tiers | 3 | both, since 2 is the minimum |
 
-### Reach: a sanity bound, not a target
+Without that stopping rule, a cap of six would reliably drag in tier-3 schools
+ten miles away to fill a row that three good matches had already earned. The old
+cap of three hid this; six exposes it, which is why the rule is stated rather
+than left to the loop.
 
-| Phase | Reach |
+**Faith relaxes before gender.** A faith mismatch changes the character of a
-|---|---|
+school; a gender mismatch can mean the school is not available to the reader's
-| Primary, middle deemed primary, all-through | 2 miles |
+child at all. Ordering them the other way would fill the section with schools
-| Secondary, middle deemed secondary | 6 miles |
+that cannot be applied to.
-| 16 plus | 10 miles |
 
-Ordering by distance already handles density — a school in inner London fills
+### Two decisions that are easy to get wrong later
-all six slots inside a mile and never approaches the cap. The cap decides one
-thing: what happens where the area is sparse. It differs by phase because
-catchments do, and because people travel furthest for post-16.
 
-**A primary with nothing inside two miles renders no section**, and that is the
+**Selected by tier, displayed by distance.** Tier decides *which* three schools
-intended answer rather than a gap. The alternative is a section headed "nearby"
+earn a slot. The rendered order is then distance ascending, because "nearby" is
-listing a school four miles from a five-year-old.
+the promise in the heading and a reader scanning the row reads the first card as
+the closest. A tier-2 school at 0.4 miles therefore appears above a tier-1
+school at 2.9 miles, and the chips explain the difference in match quality.
 
-**Past the sixth school, the rest are dropped without a count.** The section
+**Past the sixth school, the rest are dropped without a count.** In inner
-does not try to be the list: `NearbyPlaces` sits directly beneath and already
+London dozens clear tier 1, and a parent there will notice three is not the
-leads to the place pages, which are built for browsing a full set and which the
+neighbourhood — hence six. Beyond that the section does not try to be the list:
-school page exists to feed.
+`NearbyPlaces` sits directly beneath and already leads to the place pages, which
+are built for browsing a full set and which the school page exists to feed.
 
 **Fewer than two results renders nothing.** Not an empty state, not a single
-lonely card. The section is absent, the nav item is absent, and the page is
+lonely card, not padding with schools that failed the hard filters. The section
-unchanged from before it existed.
+is absent, the nav item is absent, and the page is unchanged from today. A page
+with one weak match is better off without the section than with it.
 
 ### Distance
 
@@ -168,13 +157,14 @@ reader to assume otherwise.
 | `distance_miles` | one decimal place |
 | `school_type` | GIAS type, translated, for the card's meta line |
 | `age_range` | for the meta line |
-| `shared` | what this school genuinely shares with the subject; may be empty |
+| `shared` | the chip strings the tier actually justifies — see below |
+| `tier` | 1, 2 or 3 — drives the lede's wording and the chip styling |
 | `metric_value` | the phase-appropriate headline figure, or null |
 | `metric_key` | `rwm_expected_pct` or `attainment_8_score` — see below |
 | `metric_year` | the year the figure is from |
 
-The metric follows the subject school's phase side, not the neighbour's own
+The metric follows the phase side the school was *matched* on, not the
-phase, so a row of cards never mixes two scales. The secondary
+neighbour's own phase, so a row of cards never mixes two scales. The secondary
 side uses `attainment_8_score`; the primary side uses `rwm_expected_pct`. Where
 the neighbour has no value for that key, the card reads "Not published" rather
 than falling back to the other key.
@@ -193,6 +183,12 @@ correctly — against secondaries. The section therefore takes its lede noun fro
 the school's own phase rather than from its template, or it would print "Other
 primary schools near <sixth form college>" above a row of secondaries.
 
+`tier` is carried explicitly rather than inferred from the contents of
+`shared`, because the frontend needs it for two separate decisions — whether the
+lede may claim a similar intake, and whether a chip renders as a brand-tinted
+fill or a muted outline — and inferring it from chip count would couple those
+decisions to the copy.
+
 Up to six rows of roughly 130 bytes each. It rides in the existing detail payload
 rather than a new endpoint because the page already makes exactly one server
 fetch for its data, and `/school/[slug]` regenerates at most weekly
@@ -203,11 +199,9 @@ week.
 frontend treats absent and empty identically, which is what allowed
 `NearbyPlaces` to ship without a lockstep deploy of the two images.
 
-`shared` is computed on the backend, beside the data it is derived from, not
+`shared` is computed on the backend beside the tier that produced it, not
-re-derived on the frontend. Deriving it twice is how a card comes to claim
+re-derived on the frontend. Deriving it twice is how a card comes to claim a
-something the selection never established. An empty list is a real answer and
+match the selection did not actually make.
-renders no chips: a bare card costs a school nothing but the likeness it does
-not have, since the order was already settled by distance.
 
 ## Frontend
 
@@ -314,21 +308,16 @@ shows.
 
 ## Copy, and what the section is allowed to claim
 
-**The lede never claims an intake.** It reads "Other primary schools near X." —
+**The lede tracks the deepest tier shown.** At tiers 1–2 it reads "Other primary
-one sentence, no variants. The earlier version varied the wording by tier, which
+schools near X, with a similar intake." Where any card came from tier 3 it drops
-only existed to soften a claim the section should not have been making.
+"with a similar intake", because for at least one of the cards that is not what
+was matched. Six cards make this more likely to fire than three did, which is
+correct: a wider net is exactly when the claim needs dropping.
 
-**The heading is "Other schools nearby", not "Similar schools nearby".** The
+**Chips state only what is shared.** A tier-2 card carries fewer chips rather
-hard filters do guarantee a comparable set — same phase, same selectivity,
+than a chip it has not earned; a tier-3 card falls back to the plain phase name,
-mainstream never beside special — but nothing ranks on likeness, so the heading
+styled as a muted outline rather than a brand-tinted fill so the difference is
-does not say it does. The nav item reads "Nearby schools" and the section id is
+visible at a glance.
-`nearby`.
-
-**Chips state only what is shared, and may be absent entirely.** A card with
-nothing in common renders no chip row rather than falling back to a filler.
-Since chips no longer affect the order, an empty one costs that school nothing
-except a claim it cannot support — and a Catholic parent scanning the row still
-spots "Roman Catholic" on the card that carries it, and weighs it themselves.
 
 **The neighbour's metric carries no valence colour.** Green and terracotta are
 reserved site-wide for comparison against the England average. Colouring a
@@ -375,11 +364,9 @@ synthetic frame rather than live marts:
 - a special school returns only special schools; a mainstream school returns none
 - a Boys school never returns a Girls school; Mixed matches both
 - closed schools and schools without coordinates are never returned
-- results are ordered by distance ascending, always
+- tier relaxation fills in order, and a school taken at tier 1 is not repeated
-- a faith match never outranks a closer school (the staging defect, pinned)
+- tiers stop relaxing once three are found: four tier-1 matches never open tier 2
-- the nearest eligible school is always present
 - more than six qualifying schools returns the six nearest
-- reach is capped per phase, and a primary beyond two miles returns `[]`
 - an all-through school is offered on both phase sides
 - a `16 plus` school is matched against secondaries and colleges, never primaries
 - `is_secondary_phase` and `PHASE_GROUPS` agree on every GIAS phase value
@@ -389,8 +376,7 @@ synthetic frame rather than live marts:
 **Frontend**, in `nextjs-app/__tests__`:
 
 - the section renders nothing for absent, empty and single-row inputs
-- the lede never claims a similar intake
+- the lede drops "with a similar intake" when any card is tier 3
-- an empty `shared` renders no chips rather than a filler
 - a null metric renders "Not published"
 - the nav item appears only alongside the section
 - every card is in the DOM, including the ones scrolled out of view
@@ -422,11 +408,10 @@ journeys are confirmed on the post-merge staging run.
 - Autoplay, dots, or an infinite loop on the carousel. It is a short list a
   reader scans deliberately, not a banner competing for attention, and a row
   that moves on its own is a row that moves while someone is reading it.
-- Statistical neighbours on deprivation, size or cohort profile. If plain
+- Statistical neighbours on deprivation, size or cohort profile. If the tiers
-  distance proves too blunt, that is the trigger to move this computation into a
+  prove too coarse, that is the trigger to move this computation into a dbt mart
-  dbt mart — `select_nearby` is a deliberate seam for exactly that swap.
+  — `_similar_schools_payload` is a deliberate seam for exactly that swap.
 - Precomputing neighbours in `marts.*`. Rejected for now: a new mart is inert
   until Airflow runs, so the feature would ship dark, and every tuning change to
-  the rules would become a pipeline round-trip instead of a deploy. The revision
+  the tiers would become a pipeline round-trip instead of a deploy.
-  at the top of this document is the argument for keeping that loop short.
 - Any change to `/api/compare`, the compare page, or the comparison basket.

e2e/tests/journeys.spec.ts

@@ -2736,7 +2736,7 @@ test('the content sitemap lists the about page and is advertised in robots', asy
 });
 
 /**
- * Other schools nearby.
+ * Similar schools nearby.
  *
  * The section is absent by design where fewer than two schools qualify, and the
  * arrows are absent where three cards fit, so this asserts each part of the
@@ -2746,12 +2746,12 @@ test('the content sitemap lists the about page and is advertised in robots', asy
  * which jsdom cannot measure because it has no layout, and the scroll position
  * surviving a selection, which is DOM state rather than React state.
  */
-test('nearby schools link on to other schools and into compare', async ({ page }) => {
+test('similar schools link on to other schools and into compare', async ({ page }) => {
   await searchByName(page, 'Primary');
   await schoolLinks(page).first().click();
   await page.waitForURL(/\/school\//);
 
-  const section = page.locator('#nearby');
+  const section = page.locator('#similar');
   if ((await section.count()) === 0) {
     test.skip(true, 'No qualifying similar schools for this school');
   }
@@ -2793,7 +2793,7 @@ test('nearby schools link on to other schools and into compare', async ({ page }
 });
 
 /**
- * The nearby-schools section at MOBILE.md's three reference widths.
+ * The section at MOBILE.md's three reference widths.
  *
  * MOBILE.md asks for exactly this check and records that it was not written
  * because "Playwright isn't currently in the project dependency set". That is
@@ -2801,13 +2801,13 @@ test('nearby schools link on to other schools and into compare', async ({ page }
  * to the page this feature touches.
  */
 for (const width of [360, 390, 430]) {
-  test(`nearby schools survives a ${width}px viewport`, async ({ page }) => {
+  test(`similar schools survives a ${width}px viewport`, async ({ page }) => {
     await page.setViewportSize({ width, height: 800 });
     await searchByName(page, 'Primary');
     await schoolLinks(page).first().click();
     await page.waitForURL(/\/school\//);
 
-    const section = page.locator('#nearby');
+    const section = page.locator('#similar');
     if ((await section.count()) === 0) {
       test.skip(true, 'No qualifying similar schools for this school');
     }

nextjs-app/__tests__/components/SimilarSchoolsSection.test.tsx

@@ -1,32 +1,32 @@
 /**
- * The section's job is to be honest about what it is showing. These tests pin
+ * The section's job is to be honest about what it matched. These tests pin the
- * the ways it could mislead: rendering below the minimum, claiming a likeness
+ * ways it could lie: rendering below the minimum, claiming a similar intake at
- * it does not rank on, showing a missing figure as a number, or hiding a card
+ * tier 3, showing a missing figure as a number, or hiding a card behind an
- * behind an arrow where a crawler cannot reach it.
+ * arrow where a crawler cannot reach it.
  */
 
 import { render, screen } from '@testing-library/react';
 
 import {
   nearbyNoun,
-  NearbySchoolsSection,
+  SimilarSchoolsSection,
-  shouldRenderNearby,
+  shouldRenderSimilar,
-} from '@/components/school/NearbySchoolsSection';
+} from '@/components/school/SimilarSchoolsSection';
-import type { NearbySchool } from '@/lib/types';
+import type { SimilarSchool } from '@/lib/types';
 
 jest.mock('@/components/school/AddToCompareButton', () => ({
-  AddToCompareButton: ({ school }: { school: NearbySchool }) => (
+  AddToCompareButton: ({ school }: { school: SimilarSchool }) => (
     <button type="button">Add {school.school_name} to compare</button>
   ),
 }));
 
-jest.mock('@/components/school/NearbySchoolsCompareBar', () => ({
+jest.mock('@/components/school/SimilarSchoolsCompareBar', () => ({
-  NearbySchoolsCompareBar: ({ thisUrn }: { thisUrn: number }) => (
+  SimilarSchoolsCompareBar: ({ thisUrn }: { thisUrn: number }) => (
     <div data-testid="compare-bar">bar for {thisUrn}</div>
   ),
 }));
 
-function school(overrides: Partial<NearbySchool> = {}): NearbySchool {
+function school(overrides: Partial<SimilarSchool> = {}): SimilarSchool {
   return {
     urn: 100002,
     school_name: 'Willow Lane Primary School',
@@ -34,6 +34,7 @@ function school(overrides: Partial<NearbySchool> = {}): NearbySchool {
     school_type: 'Community school',
     age_range: '4-11',
     shared: ['Mixed', 'No religious character'],
+    tier: 1,
     metric_value: 74,
     metric_key: 'rwm_expected_pct',
     metric_year: 202425,
@@ -41,14 +42,14 @@ function school(overrides: Partial<NearbySchool> = {}): NearbySchool {
   };
 }
 
-function renderSection(nearby: NearbySchool[]) {
+function renderSection(similar: SimilarSchool[]) {
   return render(
-    <NearbySchoolsSection
+    <SimilarSchoolsSection
       urn={100001}
       schoolName="Meadowbrook Primary School"
       phase="Primary"
       thisMetricValue={72}
-      nearby={nearby}
+      similar={similar}
     />,
   );
 }
@@ -60,11 +61,11 @@ describe('render gates', () => {
     ['empty', []],
     ['a single school', [school()]],
   ])('renders nothing for %s', (_label, value) => {
-    expect(shouldRenderNearby(value as NearbySchool[] | null | undefined)).toBe(false);
+    expect(shouldRenderSimilar(value as SimilarSchool[] | null | undefined)).toBe(false);
   });
 
   it('renders for two or more schools', () => {
-    expect(shouldRenderNearby([school(), school({ urn: 100003 })])).toBe(true);
+    expect(shouldRenderSimilar([school(), school({ urn: 100003 })])).toBe(true);
   });
 
   it('returns null rather than an empty shell below the minimum', () => {
@@ -73,36 +74,15 @@ describe('render gates', () => {
   });
 });
 
-describe('what the section claims', () => {
+describe('the claim the lede makes', () => {
-  it('never claims a similar intake, because it does not rank on one', () => {
+  it('claims a similar intake when every card is tier 1 or 2', () => {
-    renderSection([school(), school({ urn: 100003, shared: [] })]);
+    renderSection([school({ tier: 1 }), school({ urn: 100003, tier: 2 })]);
-    expect(screen.queryByText(/similar intake/i)).not.toBeInTheDocument();
+    expect(screen.getByText(/with a similar intake/i)).toBeInTheDocument();
   });
 
-  it('is headed "Other schools nearby", not "similar"', () => {
+  it('drops the claim when any card is tier 3', () => {
-    renderSection([school(), school({ urn: 100003 })]);
+    renderSection([school({ tier: 1 }), school({ urn: 100003, tier: 3, shared: ['Primary school'] })]);
-    expect(screen.getByRole('heading', { name: 'Other schools nearby' })).toBeInTheDocument();
+    expect(screen.queryByText(/with a similar intake/i)).not.toBeInTheDocument();
-  });
-
-  it('shows chips for what is shared', () => {
-    renderSection([school({ shared: ['Mixed', 'Roman Catholic'] }), school({ urn: 100003 })]);
-    expect(screen.getAllByText('Roman Catholic').length).toBe(1);
-  });
-
-  it('shows no chips at all when nothing is shared, rather than inventing one', () => {
-    const { container } = render(
-      <NearbySchoolsSection
-        urn={100001}
-        schoolName="Meadowbrook Primary School"
-        phase="Primary"
-        thisMetricValue={72}
-        nearby={[school({ shared: [] }), school({ urn: 100003, shared: [] })]}
-      />,
-    );
-    // The card still carries its distance, name, type and figure — just no
-    // claim of likeness.
-    expect(container.querySelectorAll('li ul').length).toBe(0);
-    expect(screen.getAllByText(/miles away/).length).toBe(2);
   });
 });
 
@@ -124,12 +104,12 @@ describe('what the lede calls the set', () => {
 
   it('never calls a sixth form college\'s neighbours primary schools', () => {
     render(
-      <NearbySchoolsSection
+      <SimilarSchoolsSection
         urn={100001}
         schoolName="Barnet Sixth Form College"
         phase="16 plus"
         thisMetricValue={null}
-        nearby={[school(), school({ urn: 100003 })]}
+        similar={[school(), school({ urn: 100003 })]}
       />,
     );
     expect(screen.getByText(/Other schools and colleges near Barnet Sixth Form College/)).toBeInTheDocument();

nextjs-app/__tests__/lib/schoolSections.test.ts

@@ -173,7 +173,7 @@ describe('buildSecondaryNavItems', () => {
   });
 });
 
-describe('the nearby-schools nav item', () => {
+describe('the similar-schools nav item', () => {
   const navInput = {
     ofsted: null, admissions: null, admissionDistance: null,
     hasLocation: true, yearlyDataLength: 1,
@@ -182,29 +182,29 @@ describe('the nearby-schools nav item', () => {
   it('appears on both templates when the section renders', () => {
     const primary = computeSchoolFlags(primaryFixture);
     const secondary = computeSecondaryFlags(secondaryFixture);
-    const input = { ...navInput, hasNearbySchools: true };
+    const input = { ...navInput, hasSimilarSchools: true };
 
-    expect(buildNavItems(primary, input).map((i) => i.id)).toContain('nearby');
+    expect(buildNavItems(primary, input).map((i) => i.id)).toContain('similar');
-    expect(buildSecondaryNavItems(secondary, input).map((i) => i.id)).toContain('nearby');
+    expect(buildSecondaryNavItems(secondary, input).map((i) => i.id)).toContain('similar');
   });
 
   it('is absent when the section does not render', () => {
     const primary = computeSchoolFlags(primaryFixture);
     const secondary = computeSecondaryFlags(secondaryFixture);
-    const input = { ...navInput, hasNearbySchools: false };
+    const input = { ...navInput, hasSimilarSchools: false };
 
-    expect(buildNavItems(primary, input).map((i) => i.id)).not.toContain('nearby');
+    expect(buildNavItems(primary, input).map((i) => i.id)).not.toContain('similar');
-    expect(buildSecondaryNavItems(secondary, input).map((i) => i.id)).not.toContain('nearby');
+    expect(buildSecondaryNavItems(secondary, input).map((i) => i.id)).not.toContain('similar');
   });
 
   it('is absent when nothing says either way', () => {
     const primary = computeSchoolFlags(primaryFixture);
-    expect(buildNavItems(primary, navInput).map((i) => i.id)).not.toContain('nearby');
+    expect(buildNavItems(primary, navInput).map((i) => i.id)).not.toContain('similar');
   });
 
   it('comes last, because the section renders last', () => {
     const primary = computeSchoolFlags(primaryFixture);
-    const ids = buildNavItems(primary, { ...navInput, hasNearbySchools: true }).map((i) => i.id);
+    const ids = buildNavItems(primary, { ...navInput, hasSimilarSchools: true }).map((i) => i.id);
-    expect(ids[ids.length - 1]).toBe('nearby');
+    expect(ids[ids.length - 1]).toBe('similar');
   });
 });

nextjs-app/app/(frontend)/school/[slug]/page.tsx

@@ -8,7 +8,7 @@ import { APIFetchError, fetchSchoolDetails, fetchSchools, fetchNationalAverages
 import { notFound, redirect } from 'next/navigation';
 import { SchoolDetailShell } from '@/components/school/SchoolDetailShell';
 import { NearbyPlaces } from '@/components/school/NearbyPlaces';
-import { shouldRenderNearby } from '@/components/school/NearbySchoolsSection';
+import { shouldRenderSimilar } from '@/components/school/SimilarSchoolsSection';
 import { schoolBreadcrumbJsonLd, type SchoolPlace } from '@/lib/jsonld';
 import { PrimarySchoolSections } from '@/components/school/PrimarySchoolSections';
 import { SecondarySchoolSections } from '@/components/school/SecondarySchoolSections';
@@ -157,7 +157,7 @@ export default async function SchoolPage({ params }: SchoolPageProps) {
   // lockstep deploy of the two images.
   const places: SchoolPlace[] = data.places ?? [];
   // Absent on an older API build, exactly like `places` above.
-  const nearbySchools = data.nearby_schools ?? [];
+  const similarSchools = data.similar_schools ?? [];
 
   // Redirect bare URN to canonical slug URL
   const canonicalSlug = schoolUrl(urn, school_info.school_name).replace('/school/', '');
@@ -189,7 +189,7 @@ export default async function SchoolPage({ params }: SchoolPageProps) {
     admissions: admissions ?? null,
     admissionDistance: admission_distance ?? null,
     hasLocation: school_info.latitude != null && school_info.longitude != null,
-    hasNearbySchools: shouldRenderNearby(nearbySchools),
+    hasSimilarSchools: shouldRenderSimilar(similarSchools),
     yearlyDataLength: yearly_data.length,
   };
   const primaryNavItems = buildNavItems(primaryFlags, navInput);
@@ -266,7 +266,7 @@ export default async function SchoolPage({ params }: SchoolPageProps) {
             finance={finance ?? null}
             nationalAvg={nationalAvg}
             destinations={destinations ?? null}
-            nearbySchools={nearbySchools}
+            similarSchools={similarSchools}
             flags={secondaryFlags}
           />
         </SchoolDetailShell>
@@ -289,7 +289,7 @@ export default async function SchoolPage({ params }: SchoolPageProps) {
             deprivation={deprivation ?? null}
             finance={finance ?? null}
             nationalAvg={nationalAvg}
-            nearbySchools={nearbySchools}
+            similarSchools={similarSchools}
             flags={primaryFlags}
           />
         </SchoolDetailShell>

nextjs-app/components/school/AddToCompareButton.tsx

@@ -9,10 +9,10 @@
  */
 
 import { useComparisonContext } from '@/context/ComparisonContext';
-import type { School, NearbySchool } from '@/lib/types';
+import type { School, SimilarSchool } from '@/lib/types';
-import styles from './NearbySchools.module.css';
+import styles from './SimilarSchools.module.css';
 
-export function AddToCompareButton({ school }: { school: NearbySchool }) {
+export function AddToCompareButton({ school }: { school: SimilarSchool }) {
   const { addSchool, removeSchool, selectedSchools } = useComparisonContext();
   const selected = selectedSchools.some((s) => s.urn === school.urn);
 

nextjs-app/components/school/PrimarySchoolSections.tsx

@@ -14,7 +14,7 @@
 import type {
   School, SchoolResult, AbsenceData, OfstedInspection, SchoolCensus,
   SchoolAdmissions, SchoolAdmissionDistance, SchoolDeprivation, SchoolFinance, NationalAverages,
-  NearbySchool,
+  SimilarSchool,
 } from '@/lib/types';
 import { ofstedLegacyAreas } from '@/lib/utils';
 import type { SchoolFlags } from '@/lib/schoolSections';
@@ -27,7 +27,7 @@ import { HistorySection } from './HistorySection';
 import { SchoolLifeSection } from './SchoolLifeSection';
 import { LocalAreaSection } from './LocalAreaSection';
 import { FinancesSection } from './FinancesSection';
-import { NearbySchoolsSection } from './NearbySchoolsSection';
+import { SimilarSchoolsSection } from './SimilarSchoolsSection';
 
 export interface PrimarySchoolSectionsProps {
   schoolInfo: School;
@@ -42,14 +42,14 @@ export interface PrimarySchoolSectionsProps {
   finance: SchoolFinance | null;
   nationalAvg: NationalAverages | null;
   /** Nearby schools of a comparable intake. Absent on an older API build. */
-  nearbySchools?: NearbySchool[];
+  similarSchools?: SimilarSchool[];
   flags: SchoolFlags;
 }
 
 export function PrimarySchoolSections({
   schoolInfo, yearlyData, absenceData, ofsted, census,
   admissions, admissionsHistory, admissionDistance,
-  deprivation, finance, nationalAvg, nearbySchools, flags,
+  deprivation, finance, nationalAvg, similarSchools, flags,
 }: PrimarySchoolSectionsProps) {
   const primaryAvg = nationalAvg?.primary ?? {};
   const secondaryAvg = nationalAvg?.secondary ?? {};
@@ -152,12 +152,12 @@ export function PrimarySchoolSections({
       {flags.hasFinance && finance && <FinancesSection finance={finance} />}
 
       {/* Last: it is where the reader goes next, not part of this school. */}
-      <NearbySchoolsSection
+      <SimilarSchoolsSection
         urn={schoolInfo.urn}
         schoolName={schoolInfo.school_name}
         phase={schoolInfo.phase}
         thisMetricValue={flags.latestResults?.rwm_expected_pct ?? null}
-        nearby={nearbySchools}
+        similar={similarSchools}
       />
     </>
   );

nextjs-app/components/school/SecondarySchoolSections.tsx

@@ -14,7 +14,7 @@
 import type {
   School, SchoolResult, AbsenceData, OfstedInspection, SchoolCensus,
   SchoolAdmissions, SchoolAdmissionDistance, SchoolDeprivation, SchoolFinance, NationalAverages,
-  SchoolDestinations, NearbySchool,
+  SchoolDestinations, SimilarSchool,
 } from '@/lib/types';
 import { ofstedLegacyAreas } from '@/lib/utils';
 import type { SecondaryFlags } from '@/lib/schoolSections';
@@ -27,7 +27,7 @@ import { DistanceSection } from './DistanceSection';
 import { SecondaryHistorySection } from './SecondaryHistorySection';
 import { WellbeingSection } from './WellbeingSection';
 import { FinancesSection } from './FinancesSection';
-import { NearbySchoolsSection } from './NearbySchoolsSection';
+import { SimilarSchoolsSection } from './SimilarSchoolsSection';
 import styles from './schoolSections.module.css';
 
 export interface SecondarySchoolSectionsProps {
@@ -49,14 +49,14 @@ export interface SecondarySchoolSectionsProps {
   nationalAvg: NationalAverages | null;
   destinations: SchoolDestinations | null;
   /** Nearby schools of a comparable intake. Absent on an older API build. */
-  nearbySchools?: NearbySchool[];
+  similarSchools?: SimilarSchool[];
   flags: SecondaryFlags;
 }
 
 export function SecondarySchoolSections({
   schoolInfo, yearlyData, ofsted, census,
   admissions, admissionsHistory, admissionDistance,
-  deprivation, finance, nationalAvg, destinations, nearbySchools, flags,
+  deprivation, finance, nationalAvg, destinations, similarSchools, flags,
 }: SecondarySchoolSectionsProps) {
   const secondaryAvg = nationalAvg?.secondary ?? {};
 
@@ -146,12 +146,12 @@ export function SecondarySchoolSections({
       )}
 
       {/* Last: it is where the reader goes next, not part of this school. */}
-      <NearbySchoolsSection
+      <SimilarSchoolsSection
         urn={schoolInfo.urn}
         schoolName={schoolInfo.school_name}
         phase={schoolInfo.phase}
         thisMetricValue={flags.latestResults?.attainment_8_score ?? null}
-        nearby={nearbySchools}
+        similar={similarSchools}
       />
     </div>
   );

nextjs-app/components/school/SimilarSchools.module.css

@@ -39,6 +39,7 @@
 
 .shared { display: flex; flex-wrap: wrap; gap: 0.35rem; list-style: none; margin: 0 0 0.85rem; padding: 0; }
 .chip { font-size: 0.72rem; line-height: 1.4; padding: 0.25rem 0.5rem; border-radius: 999px; background: var(--brand-bg); color: var(--brand); border: 1px solid transparent; }
+.chipLoose { font-size: 0.72rem; line-height: 1.4; padding: 0.25rem 0.5rem; border-radius: 999px; background: transparent; color: var(--text-muted); border: 1px solid var(--border); }
 
 .metric { margin-top: auto; padding-top: 0.8rem; border-top: 1px solid var(--border); }
 /* No valence colour here, deliberately: green and terracotta mean "against the

nextjs-app/components/school/SimilarSchoolsCarousel.tsx

@@ -14,7 +14,7 @@
  */
 
 import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react';
-import styles from './NearbySchools.module.css';
+import styles from './SimilarSchools.module.css';
 
 /** Three cards fit the row, so fewer than four has nowhere to scroll to.
  *  Below 640px the arrows are not rendered at all — see the stylesheet. */
@@ -31,7 +31,7 @@ const VISIBLE = 3;
  */
 const EDGE = 8;
 
-export function NearbySchoolsCarousel({
+export function SimilarSchoolsCarousel({
   count,
   labelledBy,
   header,

nextjs-app/components/school/SimilarSchoolsCompareBar.tsx

@@ -11,15 +11,15 @@
 
 import Link from 'next/link';
 import { useComparisonContext } from '@/context/ComparisonContext';
-import type { NearbySchool } from '@/lib/types';
+import type { SimilarSchool } from '@/lib/types';
-import styles from './NearbySchools.module.css';
+import styles from './SimilarSchools.module.css';
 
-export function NearbySchoolsCompareBar({
+export function SimilarSchoolsCompareBar({
   thisUrn,
   candidates,
 }: {
   thisUrn: number;
-  candidates: NearbySchool[];
+  candidates: SimilarSchool[];
 }) {
   const { selectedSchools } = useComparisonContext();
 

nextjs-app/components/school/SimilarSchoolsSection.tsx

@@ -1,16 +1,12 @@
 /**
- * NearbySchoolsSection — the nearest eligible schools, closest first. Server
+ * SimilarSchoolsSection — nearby schools of the same phase and a comparable
- * component; only the carousel, the compare bar and the add-to-compare button
+ * intake. Server component; only the carousel, the compare bar and the
- * are client-side.
+ * add-to-compare button are client-side.
  *
- * "Other schools nearby", not "similar" ones: the order is distance and only
+ * The section is allowed to say exactly what the backend matched and no more.
- * distance. The hard filters upstream still guarantee the set is comparable —
+ * The lede only claims a similar intake when no card came from tier 3, and a
- * same phase, same selectivity, mainstream never beside special — but nothing
+ * card's chips list what that school actually shares rather than a match it
- * here ranks by how alike two schools are, so the heading does not say it does.
+ * did not earn.
- *
- * The chips report what a school shares, and may be absent entirely. That is
- * information for the reader to weigh, not a verdict this section has already
- * reached on their behalf.
  *
  * There is deliberately no "how these are chosen" panel: the method is already
  * visible in the lede, the chips and the distances. The single caption line is
@@ -18,18 +14,18 @@
  */
 
 import Link from 'next/link';
-import type { NearbySchool } from '@/lib/types';
+import type { SimilarSchool } from '@/lib/types';
 import { schoolUrl } from '@/lib/utils';
 import { AddToCompareButton } from './AddToCompareButton';
-import { NearbySchoolsCarousel } from './NearbySchoolsCarousel';
+import { SimilarSchoolsCarousel } from './SimilarSchoolsCarousel';
-import { NearbySchoolsCompareBar } from './NearbySchoolsCompareBar';
+import { SimilarSchoolsCompareBar } from './SimilarSchoolsCompareBar';
 import { Section } from './sectionShared';
-import styles from './NearbySchools.module.css';
+import styles from './SimilarSchools.module.css';
 
 const MINIMUM = 2;
 
-export function shouldRenderNearby(nearby?: NearbySchool[] | null): boolean {
+export function shouldRenderSimilar(similar?: SimilarSchool[] | null): boolean {
-  return (nearby?.length ?? 0) >= MINIMUM;
+  return (similar?.length ?? 0) >= MINIMUM;
 }
 
 /**
@@ -63,39 +59,44 @@ function formatMetric(value: number | null, key: string): string {
   return key === 'attainment_8_score' ? value.toFixed(1) : `${Math.round(value)}%`;
 }
 
-export function NearbySchoolsSection({
+export function SimilarSchoolsSection({
   urn,
   schoolName,
   phase,
   thisMetricValue,
-  nearby,
+  similar,
 }: {
   urn: number;
   schoolName: string;
   /** The school's own GIAS phase, not the template it renders with. */
   phase: string | null | undefined;
   thisMetricValue: number | null;
-  nearby?: NearbySchool[] | null;
+  similar?: SimilarSchool[] | null;
 }) {
-  if (!shouldRenderNearby(nearby)) return null;
+  if (!shouldRenderSimilar(similar)) return null;
-  const schools = nearby as NearbySchool[];
+  const schools = similar as SimilarSchool[];
 
   // One card matched on phase alone, so the section may not claim the set
   // shares an intake with this school.
+  const loosest = Math.max(...schools.map((s) => s.tier));
   const metricKey = schools[0].metric_key;
   const noun = nearbyNoun(phase);
 
   return (
-    <Section id="nearby">
+    <Section id="similar">
-      <NearbySchoolsCarousel
+      <SimilarSchoolsCarousel
         count={schools.length}
-        labelledBy="nearby-schools-heading"
+        labelledBy="similar-schools-heading"
         header={
           <div>
-            <h2 id="nearby-schools-heading" className={styles.heading}>
+            <h2 id="similar-schools-heading" className={styles.heading}>
-              Other schools nearby
+              Similar schools nearby
             </h2>
-            <p className={styles.lede}>{`Other ${noun} near ${schoolName}.`}</p>
+            <p className={styles.lede}>
+              {loosest >= 3
+                ? `Other ${noun} near ${schoolName}.`
+                : `Other ${noun} near ${schoolName}, with a similar intake.`}
+            </p>
           </div>
         }
       >
@@ -112,13 +113,13 @@ export function NearbySchoolsSection({
                 .filter(Boolean)
                 .join(' · ')}
             </p>
-            {school.shared.length > 0 && (
             <ul className={styles.shared}>
               {school.shared.map((label) => (
-                  <li key={label} className={styles.chip}>{label}</li>
+                <li key={label} className={school.tier >= 3 ? styles.chipLoose : styles.chip}>
+                  {label}
+                </li>
               ))}
             </ul>
-            )}
             <div className={styles.metric}>
               <p
                 className={
@@ -137,9 +138,9 @@ export function NearbySchoolsSection({
             <AddToCompareButton school={school} />
           </li>
         ))}
-      </NearbySchoolsCarousel>
+      </SimilarSchoolsCarousel>
 
-      <NearbySchoolsCompareBar thisUrn={urn} candidates={schools} />
+      <SimilarSchoolsCompareBar thisUrn={urn} candidates={schools} />
 
       {/* The one caveat the cards cannot make on their own: a reader who takes
           "0.6 miles away" for the walk has been misled, and nothing else here

nextjs-app/lib/schoolSections.ts

@@ -128,10 +128,10 @@ export interface NavItemsInput {
    *  measure a postcode, so the nav must gate on them too or it will link to an
    *  anchor that was never rendered. */
   hasLocation?: boolean;
-  /** Whether the nearby-schools section will render. Optional for the same
+  /** Whether the similar-schools section will render. Optional for the same
    *  reason hasLocation is: the nav must never link to an anchor that was not
    *  rendered, and absent has to mean "no section". */
-  hasNearbySchools?: boolean;
+  hasSimilarSchools?: boolean;
   yearlyDataLength: number;
 }
 
@@ -148,7 +148,7 @@ export function buildNavItems(
   flags: SchoolFlags,
   {
     ofsted, admissions, admissionDistance, hasLocation,
-    hasNearbySchools, yearlyDataLength,
+    hasSimilarSchools, yearlyDataLength,
   }: NavItemsInput,
 ): NavItem[] {
   const navItems: NavItem[] = [];
@@ -169,7 +169,7 @@ export function buildNavItems(
   if (flags.hasDeprivation) navItems.push({ id: 'local-area', label: 'Local Area' });
   if (flags.hasFinance) navItems.push({ id: 'finances', label: 'Finances' });
   // Last, because the section renders last — the scroll-spy reads this order.
-  if (hasNearbySchools) navItems.push({ id: 'nearby', label: 'Nearby schools' });
+  if (hasSimilarSchools) navItems.push({ id: 'similar', label: 'Similar schools' });
   return navItems;
 }
 
@@ -250,7 +250,7 @@ export function buildSecondaryNavItems(
   flags: SecondaryFlags,
   {
     ofsted, admissions, admissionDistance, hasLocation,
-    hasNearbySchools, yearlyDataLength,
+    hasSimilarSchools, yearlyDataLength,
   }: NavItemsInput,
 ): NavItem[] {
   const navItems: NavItem[] = [];
@@ -270,6 +270,6 @@ export function buildSecondaryNavItems(
   if (flags.hasWellbeing) navItems.push({ id: 'wellbeing', label: 'Wellbeing' });
   if (flags.hasFinance) navItems.push({ id: 'finances', label: 'Finances' });
   // Last, because the section renders last — the scroll-spy reads this order.
-  if (hasNearbySchools) navItems.push({ id: 'nearby', label: 'Nearby schools' });
+  if (hasSimilarSchools) navItems.push({ id: 'similar', label: 'Similar schools' });
   return navItems;
 }

nextjs-app/lib/types.ts

@@ -347,20 +347,21 @@ export interface SchoolsResponse {
 }
 
 /**
- * A nearby school, from the nearest-first set the detail page shows.
+ * A nearby school of the same phase and a comparable intake.
  *
- * `shared` is what this school genuinely has in common with the one being
+ * `tier` is carried explicitly rather than inferred from `shared`, because it
- * viewed, and may be empty. It is reported, never ranked on: an earlier
+ * drives two separate decisions — whether the lede may claim a similar intake,
- * version ordered by it and buried the school down the road under faith
+ * and whether a chip renders as a fill or a muted outline — and inferring it
- * matches three times further away.
+ * from chip count would couple those decisions to the copy.
  */
-export interface NearbySchool {
+export interface SimilarSchool {
   urn: number;
   school_name: string;
   distance_miles: number;
   school_type: string | null;
   age_range: string | null;
   shared: string[];
+  tier: number;
   metric_value: number | null;
   metric_key: string;
   metric_year: number | null;
@@ -378,13 +379,13 @@ export interface SchoolDetailsResponse {
    */
   places?: SchoolPlace[];
   /**
-   * Up to six nearby eligible schools, nearest first.
+   * Up to six nearby schools of a comparable intake, nearest first.
    *
    * Optional for the same reason as `places`: a frontend deployed ahead of the
    * API that serves this must render without it. Absent and empty mean the
    * same thing here — no section.
    */
-  nearby_schools?: NearbySchool[];
+  similar_schools?: SimilarSchool[];
   yearly_data: SchoolResult[];
   absence_data: AbsenceData | null;
   // Supplementary data (null until Kestra populates)