docs(puzzle-page): document SEO description/OG/Twitter wiring + future risks

- Updated "How to configure/add a new puzzle" step 1 to mention the new
  required `description` field on PuzzleConfig, with an explicit
  instruction to write real, distinct, human-quality copy per entry
  rather than a templated string.
- Added a new "SEO: meta description, Open Graph, Twitter card"
  subsection describing exactly how render.puzzlePage.web.tsx derives
  <meta name="description">, og:title/og:description, and
  twitter:title/twitter:description from puzzleConfig.description and
  webTitle.
- Added a new, clearly-flagged "SEO risks to revisit before shipping
  calendar/archive features" subsection under "Open questions / known
  limitations", covering (not implementing) two risks for future work:
  - Date-specific URLs (V1 calendar navigation, building on
    instance.puzzleDate) risking duplicate/thin indexable pages unless a
    canonical-vs-deliberate-indexing decision is made explicitly upfront.
  - Archive/pagination features (PuzzleConfig.hasArchive exists but is
    unused/unbuilt) risking poor search indexing if built carelessly,
    referencing a concrete existing example elsewhere on the Guardian
    site (the crossword archive/search listing currently indexed with a
    generic "Crossword | Page 2 of 1082" title and a garbled,
    auto-scraped listing-style description) as a cautionary precedent to
    avoid repeating.
  - Notes this isn't an active problem today (no archive/pagination UI
    exists yet) but should be raised as a design question at the start
    of that future work, not discovered after launch.

No functional/code changes in this commit - documentation only.

tsc --noEmit clean, full-repo eslint clean, full test suite passing
(175 suites / 1272 tests).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: andresilva-guardian

dotcom-rendering/docs/puzzle-page.md

@@ -118,17 +118,43 @@ iframe-based slug:
 
 1. Add a new key to `src/model/puzzles/puzzleConfigs.ts`'s `puzzleConfigs`
    record (`slug`, `puzzleGroup`, `iframe: { provider, urlTemplate }`,
-   `shareEnabled`, `printEnabled`, `hasArchive`). If it's another
-   AmuseLabs-hosted puzzle, reuse the `amuseLabsPuzzle(slug, puzzleGroup)`
-   helper. `validatePuzzleConfigs` runs once at module load and throws
-   immediately if the entry is malformed (mismatched `slug`, unknown
-   `puzzleGroup`, or empty `iframe.provider`/`iframe.urlTemplate`).
+   `shareEnabled`, `printEnabled`, `hasArchive`, `description`). If it's
+   another AmuseLabs-hosted puzzle, reuse the
+   `amuseLabsPuzzle(slug, puzzleGroup, description)` helper.
+   `validatePuzzleConfigs` runs once at module load and throws immediately
+   if the entry is malformed (mismatched `slug`, unknown `puzzleGroup`,
+   empty `iframe.provider`/`iframe.urlTemplate`, or empty `description`).
+   **Write real, distinct, human-quality copy for `description`** — it
+   becomes the page's `<meta name="description">` and its derived Open
+   Graph/Twitter description (see "SEO" below); don't copy-paste one
+   template string across entries with only the slug swapped in.
 2. Nothing else changes on the DCR side: `PuzzlePageLayout.tsx`'s
    `PuzzlePageContent` unconditionally renders `PuzzleIframe` pointed at
    `resolveIframeUrl(puzzleConfig)` for every registry entry. The only thing
    needed from `frontend` is a request whose `slug` matches the new
    registry key exactly (see the `frontend` repo's `docs/puzzle-page.md`).
 
+### SEO: meta description, Open Graph, Twitter card
+
+Each `PuzzleConfig` entry carries a curated `description` (a short,
+genuinely-written meta description, distinct per puzzle — see step 1
+above). `render.puzzlePage.web.tsx` uses
+`puzzlePage.puzzleConfig.description` (the config already resolved by
+`handler.puzzlePage.web.ts`, not a fresh lookup) for three things:
+
+- The page's `<meta name="description">` (previously hardcoded to `''`,
+  which silently fell back to DCR's generic, site-wide description — a
+  real SEO gap, since a generic/absent description risks Google or social
+  previews auto-generating a snippet from page content instead of showing
+  clean, curated copy).
+- `openGraphData: { 'og:title': webTitle, 'og:description': description }`.
+- `twitterData: { 'twitter:title': webTitle, 'twitter:description': description }`.
+
+Puzzle Page has no separate source of Open Graph/Twitter copy (unlike
+Article, where `frontend` sends its own `openGraphData`/`twitterData`), so
+these are derived directly from `webTitle`/`description` rather than
+requiring bespoke copy per field.
+
 ### The `FEPuzzlePageType` request contract
 
 `POST /PuzzlePage` validates the body against `FEPuzzlePageType`
@@ -282,3 +308,37 @@ darkMode: boolean } }` and the `?guardian-puzzle-context=<JSON>` query
 - **The Puzzles Hub (`src/layouts/PuzzlesLayout.tsx` and friends) is a
   separate, unrelated feature** (a directory/listing page) and is not
   documented in this file.
+
+### SEO risks to revisit before shipping calendar/archive features
+
+**Read this before adding date-specific URLs (V1 calendar navigation) or
+any archive/pagination UI to Puzzle Page.** No page in Puzzle Page today
+creates unbounded or paginated URLs (there is no archive UI yet, despite
+`PuzzleConfig.hasArchive` existing — see above), so this isn't an active
+problem yet. It becomes one the moment calendar or archive work begins, and
+should be raised as an explicit design question at the _start_ of that
+work, not discovered after launch.
+
+- **Date-specific URLs risk creating duplicate/thin indexable pages.**
+  Once `instance.puzzleDate` (or a real calendar UI) lets readers reach a
+  specific past date's puzzle via a URL — whether a query param or a path
+  segment — every such URL must either (a) carry a `canonical` pointing
+  back to the puzzle's main/"today" URL, if individual dates aren't meant
+  to be indexed separately, or (b) be a deliberate, explicit decision to
+  index each date individually with genuinely distinct content/copy per
+  date. This must be decided explicitly before shipping, not left as an
+  accidental side effect of adding date-awareness to the URL.
+- **Archive/pagination features carry a known, real risk of poor search
+  indexing if built carelessly.** A concrete, existing cautionary example
+  elsewhere on the Guardian site: the crossword archive/search listing is
+  currently indexed by Google with a generic, unhelpful title
+  ("Crossword | Page 2 of 1082") and a garbled, listing-style meta
+  description auto-scraped from page content (a concatenated list of
+  puzzle names) rather than a clean, curated one — a direct consequence of
+  paginated listing pages being indexed individually without proper
+  `canonical`/`noindex`/curated-metadata handling. Any future Puzzle Page
+  archive feature must avoid this from the start: genuinely curated
+  titles/descriptions per archive page (never auto-generated from a list of
+  contents, the same principle behind `PuzzleConfig.description` above),
+  and an explicit `canonical`/`noindex`/pagination-indexing strategy decided
+  upfront — not defaulting to "index everything" and finding out later.