feat(flags): put /about and /blog behind flags, dark by default

Both features ship dark. Neither is reachable in an environment where
its flag is off, and every flag in this system starts off, so a deploy
of this commit makes both disappear until someone turns them on
deliberately.

Two independent flags rather than one, which makes blog-on-about-off a
reachable state. That state is the whole reason the change is larger
than four notFound() calls: the blog leans on the About page for its
author identity. The Person entity is anchored at /about#tudor, and
that URL 404s while about_page is dark, so a post published in that
state would claim an author resolving to nothing. Worse than having no
named author. Both bylines fall back to unlinked text and the
BlogPosting attributes to the publisher instead, so every combination
of the two flags renders something correct.

Gated: /about, /blog, /blog/[slug], the RSS feed, both footer links,
and the matching content-sitemap entries. A sitemap must never
advertise a URL that 404s. With both dark it emits a valid empty
urlset rather than a 404, because robots.txt names it unconditionally.

Not gated: /admin. Posts have to be writable before the blog is worth
switching on, so flagging the panel would make the flag unflippable.

getFlags takes a revalidate rather than always using the 300s
constant. Reading a flag pins the calling route to the lowest
revalidate among its fetches, and the footer links live in the root
layout, so a naive gate there would have dropped every school and
place page from a weekly cache to a 5-minute one. The layout passes
604800, the floor those routes already declare, and the build confirms
all four SSG route families still prerender. The cost is one-way
latency: pages follow a flip in minutes, footer links within a week.

The e2e journeys follow the existing paired shape from the
admission_distance flag: a lit journey and a dark one for each flag,
reading state from whether /about and /blog respond rather than from
/api/flags, which another journey asserts is not publicly reachable.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DXnXQKnPpZBBP61fBQiFkq

nextjs-app/__tests__/app/blogMetadata.test.ts

@@ -27,14 +27,27 @@ describe('BlogPosting structured data', () => {
   it('names the same Person entity the about page declares', () => {
     // By @id, not by repeating the person: search engines must resolve every
     // post and the about page to one author entity, or the site has several.
-    const ld = blogPostingJsonLd(post);
+    const ld = blogPostingJsonLd(post, { namedAuthor: true });
     expect(ld['@type']).toBe('BlogPosting');
     expect(ld.author['@id']).toBe('https://www.schoolcompare.co.uk/about#tudor');
     expect(ld.publisher['@id']).toBe('https://www.schoolcompare.co.uk#organization');
   });
 
+  it('attributes to the organization when the about page is dark', () => {
+    /*
+     * The two flags are independent, so blog-on-about-off is a reachable
+     * state. The Person entity lives at /about#tudor and that URL 404s while
+     * the flag is dark, so claiming it would declare an author that resolves
+     * to nothing — worse for the blog's credibility than having no named
+     * author at all. Attribute to the publisher instead.
+     */
+    const ld = blogPostingJsonLd(post, { namedAuthor: false });
+    expect(ld.author['@id']).toBe('https://www.schoolcompare.co.uk#organization');
+    expect(JSON.stringify(ld)).not.toContain('/about');
+  });
+
   it('carries a self-referencing canonical url and the publish date', () => {
-    const ld = blogPostingJsonLd(post);
+    const ld = blogPostingJsonLd(post, { namedAuthor: true });
     expect(ld.url).toBe(
       'https://www.schoolcompare.co.uk/blog/what-the-data-cannot-tell-you',
     );

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

@@ -0,0 +1,47 @@
+/**
+ * The footer is the only navigational route to /about and /blog, so it is
+ * where a dark flag would otherwise leave a link into a 404.
+ *
+ * Both props default to false. A caller that forgets to pass them hides the
+ * links, which is the direction that cannot break a page — the same reasoning
+ * as backend/flags.py's "every flag defaults to False".
+ */
+import { render, screen } from '@testing-library/react';
+import { Footer } from '@/components/Footer';
+
+describe('footer feature links', () => {
+  it('links to both when both flags are on', () => {
+    render(<Footer aboutEnabled blogEnabled />);
+    expect(screen.getByRole('link', { name: /who's behind this/i }))
+      .toHaveAttribute('href', '/about');
+    expect(screen.getByRole('link', { name: /^blog$/i }))
+      .toHaveAttribute('href', '/blog');
+  });
+
+  it('omits the about link when that flag is dark', () => {
+    render(<Footer blogEnabled />);
+    expect(screen.queryByRole('link', { name: /who's behind this/i })).toBeNull();
+    expect(screen.getByRole('link', { name: /^blog$/i })).toBeInTheDocument();
+  });
+
+  it('omits the blog link when that flag is dark', () => {
+    render(<Footer aboutEnabled />);
+    expect(screen.queryByRole('link', { name: /^blog$/i })).toBeNull();
+    expect(screen.getByRole('link', { name: /who's behind this/i }))
+      .toBeInTheDocument();
+  });
+
+  it('drops the whole section when both are dark, not an empty heading', () => {
+    // Shipping dark means the footer renders as it did before the feature
+    // existed, not as a section with its contents removed.
+    render(<Footer />);
+    expect(screen.queryByRole('heading', { name: /^about$/i })).toBeNull();
+    expect(screen.queryByRole('link', { name: /who's behind this/i })).toBeNull();
+    expect(screen.queryByRole('link', { name: /^blog$/i })).toBeNull();
+  });
+
+  it('defaults to dark when a caller passes nothing', () => {
+    render(<Footer />);
+    expect(screen.queryByRole('link', { name: /who's behind this/i })).toBeNull();
+  });
+});

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

@@ -1,4 +1,4 @@
-import { getFlags } from '@/lib/flags';
+import { getFlags, FLAGS_REVALIDATE } from '@/lib/flags';
 
 // jsdom provides no global fetch, so there is nothing for jest.spyOn to attach
 // to — assign it and restore the original afterwards. This is the first test
@@ -31,4 +31,28 @@ describe('getFlags', () => {
     mockFetch(async () => ({ ok: false, status: 503 }));
     await expect(getFlags()).resolves.toEqual({});
   });
+
+  /*
+   * Reading a flag pins the calling route's ISR floor: Next uses the LOWEST
+   * revalidate among a route's fetches for the whole route. That is why the
+   * revalidate is an argument rather than the constant.
+   *
+   * Every SEO route here declares `revalidate = 604800`. A gate that read
+   * flags at the 300s default would drop the whole school and place corpus
+   * from a weekly cache to a 5-minute one, which is a large origin-load
+   * regression to pay for a feature flag.
+   */
+  it('reads at the 300s floor by default', async () => {
+    mockFetch(async () => ({ ok: true, json: async () => ({}) }));
+    await getFlags();
+    expect((global.fetch as jest.Mock).mock.calls[0][1])
+      .toEqual({ next: { revalidate: FLAGS_REVALIDATE } });
+  });
+
+  it('lets a caller pass its own route floor instead', async () => {
+    mockFetch(async () => ({ ok: true, json: async () => ({}) }));
+    await getFlags(604800);
+    expect((global.fetch as jest.Mock).mock.calls[0][1])
+      .toEqual({ next: { revalidate: 604800 } });
+  });
 });

nextjs-app/app/(frontend)/about/page.tsx

@@ -1,6 +1,8 @@
 import type { Metadata } from 'next';
 import Image from 'next/image';
+import { notFound } from 'next/navigation';
 import { absoluteUrl } from '@/lib/site';
+import { getFlags } from '@/lib/flags';
 import { personJsonLd, organizationJsonLd } from '@/lib/jsonld';
 import styles from './About.module.css';
 
@@ -11,7 +13,18 @@ export const metadata: Metadata = {
   alternates: { canonical: absoluteUrl('/about') },
 };
 
-export default function AboutPage() {
+/*
+ * Gated on about_page. The default 300s read is the right floor here: this
+ * page declares no revalidate of its own, so nothing is lost by it, and a flip
+ * lands within five minutes.
+ *
+ * notFound(), not a redirect: while the flag is dark this URL does not exist,
+ * and a 404 is what tells a crawler not to keep it.
+ */
+export default async function AboutPage() {
+  const flags = await getFlags();
+  if (flags.about_page !== true) notFound();
+
   const jsonLd = {
     '@context': 'https://schema.org',
     '@graph': [personJsonLd(), organizationJsonLd()],

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

@@ -7,6 +7,7 @@ import type { JSXConvertersFunction } from '@payloadcms/richtext-lexical/react';
 import { getCachedPayload } from '@/lib/payload';
 import type { Post, Media } from '@/payload-types';
 import { absoluteUrl } from '@/lib/site';
+import { getFlags } from '@/lib/flags';
 import {
   blogPostingJsonLd,
   breadcrumbJsonLd,
@@ -112,6 +113,15 @@ export default async function PostPage(
   { params }: { params: Promise<{ slug: string }> },
 ) {
   const { slug } = await params;
+
+  /*
+   * Flags read at this route's own declared floor, so gating costs it nothing.
+   * Checked before the post is fetched: a dark blog should not query Payload.
+   */
+  const flags = await getFlags(3600);
+  if (flags.blog !== true) notFound();
+  const namedAuthor = flags.about_page === true;
+
   const post = await findPost(slug);
   if (!post) notFound();
 
@@ -120,10 +130,15 @@ export default async function PostPage(
 
   const jsonLd = {
     '@context': 'https://schema.org',
+    /*
+     * The Person entity is anchored at /about#tudor, so it is declared only
+     * when that page exists. Claiming an author whose URL 404s is a worse
+     * signal than attributing the post to the publisher.
+     */
     '@graph': [
-      blogPostingJsonLd(summary),
+      blogPostingJsonLd(summary, { namedAuthor }),
       breadcrumbJsonLd(summary),
-      personJsonLd(),
+      ...(namedAuthor ? [personJsonLd()] : []),
       organizationJsonLd(),
     ],
   };
@@ -142,7 +157,10 @@ export default async function PostPage(
       <h1 className={styles.heading}>{summary.title}</h1>
 
       <p className={styles.byline}>
-        By <Link href="/about" className={styles.link}>Tudor</Link>
+        {/* Unlinked while about_page is dark; the flags are independent. */}
+        By {namedAuthor
+          ? <Link href="/about" className={styles.link}>Tudor</Link>
+          : 'Tudor'}
         {' · '}
         <time dateTime={summary.publishedAt}>
           {new Date(summary.publishedAt).toLocaleDateString('en-GB', {

nextjs-app/app/(frontend)/blog/page.tsx

@@ -1,7 +1,9 @@
 import type { Metadata } from 'next';
 import Link from 'next/link';
+import { notFound } from 'next/navigation';
 import { getCachedPayload } from '@/lib/payload';
 import { absoluteUrl } from '@/lib/site';
+import { getFlags } from '@/lib/flags';
 import styles from './Blog.module.css';
 
 /*
@@ -31,6 +33,9 @@ function formatDate(value: string) {
 }
 
 export default async function BlogIndexPage() {
+  const flags = await getFlags();
+  if (flags.blog !== true) notFound();
+
   const payload = await getCachedPayload();
   const { docs } = await payload.find({
     collection: 'posts',
@@ -48,7 +53,11 @@ export default async function BlogIndexPage() {
         <p className={styles.standfirst}>
           What school performance data shows, what it doesn&apos;t, and how to
           read it without being misled. Written by{' '}
-          <Link href="/about" className={styles.link}>Tudor</Link>.
+          {/* Plain text when about_page is dark: the two flags are
+              independent, so this link would otherwise point at a 404. */}
+          {flags.about_page === true
+            ? <Link href="/about" className={styles.link}>Tudor</Link>
+            : 'Tudor'}.
         </p>
       </header>
 

nextjs-app/app/(frontend)/blog/rss.xml/route.ts

@@ -1,5 +1,6 @@
 import { getCachedPayload } from '@/lib/payload';
 import { absoluteUrl } from '@/lib/site';
+import { getFlags } from '@/lib/flags';
 
 /*
  * Dynamic, not ISR.
@@ -18,6 +19,11 @@ function escapeXml(value: string): string {
 }
 
 export async function GET() {
+  // A dark blog has no feed. 404 rather than an empty channel: an empty feed
+  // is a live feed with nothing in it, which a reader would keep polling.
+  const flags = await getFlags();
+  if (flags.blog !== true) return new Response('Not found', { status: 404 });
+
   const payload = await getCachedPayload();
   const { docs } = await payload.find({
     collection: 'posts',

nextjs-app/app/(frontend)/content-sitemap.xml/route.ts

@@ -8,6 +8,7 @@
  */
 import { getCachedPayload } from '@/lib/payload';
 import { absoluteUrl } from '@/lib/site';
+import { getFlags } from '@/lib/flags';
 
 /*
  * Dynamic, not ISR.
@@ -21,18 +22,33 @@ import { absoluteUrl } from '@/lib/site';
 export const dynamic = 'force-dynamic';
 
 export async function GET() {
-  const payload = await getCachedPayload();
-  const { docs } = await payload.find({
-    collection: 'posts',
-    where: { _status: { equals: 'published' } },
-    sort: '-publishedAt',
-    limit: 500,
-    depth: 0,
-  });
+  /*
+   * A dark page must not be advertised. Submitting a URL that 404s is the one
+   * thing a sitemap is not allowed to do, so each entry is gated on the same
+   * flag that gates the page itself.
+   *
+   * With both flags dark this emits a valid, empty <urlset> rather than a 404:
+   * robots.txt names this sitemap unconditionally, and an empty sitemap is a
+   * well-formed statement that there is nothing here yet.
+   */
+  const flags = await getFlags();
+  const aboutEnabled = flags.about_page === true;
+  const blogEnabled = flags.blog === true;
+
+  // Only query Payload when the blog is actually being advertised.
+  const docs = blogEnabled
+    ? (await (await getCachedPayload()).find({
+      collection: 'posts',
+      where: { _status: { equals: 'published' } },
+      sort: '-publishedAt',
+      limit: 500,
+      depth: 0,
+    })).docs
+    : [];
 
   const urls: Array<{ loc: string; lastmod: string | null }> = [
-    { loc: absoluteUrl('/about'), lastmod: null },
-    { loc: absoluteUrl('/blog'), lastmod: null },
+    ...(aboutEnabled ? [{ loc: absoluteUrl('/about'), lastmod: null }] : []),
+    ...(blogEnabled ? [{ loc: absoluteUrl('/blog'), lastmod: null }] : []),
     ...docs.map((post) => ({
       loc: absoluteUrl(`/blog/${post.slug}`),
       lastmod: new Date(String(post.updatedAt ?? post.publishedAt)).toISOString(),

nextjs-app/app/(frontend)/layout.tsx

@@ -7,6 +7,7 @@ import { ComparisonToast } from '@/components/ComparisonToast';
 import { RouteTrail } from '@/components/RouteTrail';
 import { ComparisonProvider } from '@/context/ComparisonProvider';
 import { SITE_URL } from '@/lib/site';
+import { getFlags } from '@/lib/flags';
 import './globals.css';
 
 // Manrope carries headings and key messaging — the guideline's "friendly,
@@ -78,11 +79,28 @@ export const metadata: Metadata = {
   },
 };
 
-export default function RootLayout({
+/*
+ * The footer's About and Blog links are flagged, which makes this the one
+ * place on the site that reads a flag on every route.
+ *
+ * 604800 is deliberate and load-bearing: it is the revalidate every SEO route
+ * here already declares. Next pins a route to the LOWEST revalidate among its
+ * fetches, so reading flags at the 300s default would drop the whole school
+ * and place corpus from a weekly cache to a 5-minute one — a large origin-load
+ * regression to hide two footer links.
+ *
+ * The cost is latency in one direction only. The pages themselves read the
+ * same flags at their own floors and flip within minutes; the footer links
+ * follow within a week. Turning a feature on early therefore shows the page
+ * before its footer link, which is harmless. Turning one off leaves a link to
+ * a 404 until the cache turns over, so a rollback that matters wants a purge.
+ */
+export default async function RootLayout({
   children,
 }: Readonly<{
   children: React.ReactNode;
 }>) {
+  const flags = await getFlags(604800);
   return (
     // The font variable classes must sit on <html>, not <body>. globals.css
     // declares --font-display on :root as var(--font-manrope) and --font-ui as
@@ -126,7 +144,10 @@ export default function RootLayout({
             {children}
           </main>
           <ComparisonToast />
-          <Footer />
+          <Footer
+            aboutEnabled={flags.about_page === true}
+            blogEnabled={flags.blog === true}
+          />
         </ComparisonProvider>
       </body>
     </html>

nextjs-app/components/Footer.tsx

@@ -10,7 +10,17 @@
 import { LogoMark } from './Logo';
 import styles from './Footer.module.css';
 
-export function Footer() {
+/**
+ * Both default to false so a caller that forgets a prop hides the link rather
+ * than pointing it at a page that 404s. Same reasoning as backend/flags.py:
+ * "Every flag defaults to False."
+ */
+interface FooterProps {
+  aboutEnabled?: boolean;
+  blogEnabled?: boolean;
+}
+
+export function Footer({ aboutEnabled = false, blogEnabled = false }: FooterProps = {}) {
   const currentYear = new Date().getFullYear();
 
   return (
@@ -94,17 +104,26 @@ export function Footer() {
             </ul>
           </div>
 
-          <div className={styles.section}>
-            <h4 className={styles.sectionTitle}>About</h4>
-            <ul className={styles.links}>
-              {/* The only route to a named human. Deliberately not in the nav:
-                  the mobile bottom bar already carries four items, and both of
-                  these are lower intent than any of them. Post bylines link
-                  here too, which is where a reader actually asks the question. */}
-              <li><a href="/about" className={styles.link}>Who&apos;s behind this</a></li>
-              <li><a href="/blog" className={styles.link}>Blog</a></li>
-            </ul>
-          </div>
+          {/* Dropped entirely when both flags are dark, rather than left as an
+              empty heading: shipping dark means the footer renders as it did
+              before the feature existed. */}
+          {(aboutEnabled || blogEnabled) && (
+            <div className={styles.section}>
+              <h4 className={styles.sectionTitle}>About</h4>
+              <ul className={styles.links}>
+                {/* The only route to a named human. Deliberately not in the nav:
+                    the mobile bottom bar already carries four items, and both of
+                    these are lower intent than any of them. Post bylines link
+                    here too, which is where a reader actually asks the question. */}
+                {aboutEnabled && (
+                  <li><a href="/about" className={styles.link}>Who&apos;s behind this</a></li>
+                )}
+                {blogEnabled && (
+                  <li><a href="/blog" className={styles.link}>Blog</a></li>
+                )}
+              </ul>
+            </div>
+          )}
         </div>
 
         <div className={styles.bottom}>

nextjs-app/docs/PUBLISHING.md

@@ -4,6 +4,26 @@ The blog is Payload CMS, running inside the Next.js app. There is no separate
 service and no second deploy. Writing a post is done in the browser and takes
 effect on the live site within seconds.
 
+## Before any of this: the flags
+
+`/blog` and `/about` are behind feature flags (`blog` and `about_page`), and
+every flag in this system starts off. While `blog` is dark, `/blog`, every post
+page and the RSS feed return 404, and neither appears in the sitemap or the
+footer. Posts still save normally, because `/admin` is deliberately **not**
+flagged: you have to be able to write a post before there is anything worth
+switching on.
+
+So a new post published to a dark blog is invisible, and that is working as
+intended, not a bug. Flip the flag in Unleash when the content is ready.
+Staging and production hold their own values (`development` and `production`
+environments), so you can light it on staging first. The page follows a flip
+within five minutes; the footer link takes up to a week, because it renders in
+the root layout and is cached at the same weekly floor as the school corpus.
+
+Both flags are temporary scaffolding, like every flag here: a test starts
+failing once one is older than 90 days, at which point either the feature is
+permanent and the flag comes out, or it was never going to ship.
+
 ## Signing in
 
 `https://www.schoolcompare.co.uk/admin`, one account, no registration. If you

nextjs-app/lib/flags.ts

@@ -26,11 +26,21 @@ export const FLAGS_REVALIDATE = 300;
 const API = process.env.FASTAPI_URL || process.env.NEXT_PUBLIC_API_URL
   || 'http://localhost:8000/api';
 
-/** Every flag and its value. Never throws: an unreadable flag is a dark one. */
-export async function getFlags(): Promise<Flags> {
+/**
+ * Every flag and its value. Never throws: an unreadable flag is a dark one.
+ *
+ * `revalidate` is the caller's, because reading flags pins the whole route to
+ * the lowest revalidate among its fetches. Every SEO route here declares
+ * 604800; gating one at the 300s default would drop it from a weekly cache to
+ * a 5-minute one. Pass the route's own floor and gating costs it nothing.
+ *
+ * The trade is flag-flip latency: a route that revalidates weekly takes up to
+ * a week to notice a flip. Pass a smaller number where a flip must land fast.
+ */
+export async function getFlags(revalidate: number = FLAGS_REVALIDATE): Promise<Flags> {
   try {
     const res = await fetch(`${API}/flags`, {
-      next: { revalidate: FLAGS_REVALIDATE },
+      next: { revalidate },
     });
     if (!res.ok) return {};
     return await res.json();

nextjs-app/lib/jsonld.ts

@@ -44,15 +44,27 @@ interface PostSummary {
  * References the Person and Organization by @id rather than repeating them, so
  * search engines resolve every post and the About page to the one author
  * entity. Repeating the shape would declare several people with one name.
+ *
+ * `namedAuthor` is the about_page flag. The Person entity is anchored at
+ * /about#tudor, and that URL 404s while the flag is dark, so a post published
+ * in that state must not claim it: an author @id resolving to nothing is a
+ * worse signal than no named author. It falls back to the publisher, which is
+ * always live. The parameter is required rather than defaulted because every
+ * call site has the flag to hand and the wrong default is silent.
  */
-export function blogPostingJsonLd(post: PostSummary) {
+export function blogPostingJsonLd(
+  post: PostSummary,
+  { namedAuthor }: { namedAuthor: boolean },
+) {
   return {
     '@type': 'BlogPosting',
     headline: post.title,
     description: post.excerpt,
     url: absoluteUrl(`/blog/${post.slug}`),
     datePublished: post.publishedAt,
-    author: { '@id': `${SITE_URL}/about#tudor` },
+    author: {
+      '@id': namedAuthor ? `${SITE_URL}/about#tudor` : `${SITE_URL}#organization`,
+    },
     publisher: { '@id': `${SITE_URL}#organization` },
   } as const;
 }