euparliamentmonitor 0.9.5 → 0.9.7

package/README.md

@@ -136,7 +136,7 @@ The published site is the audience-facing companion to this npm/TypeScript packa
 
 **MCP Server Integration**: The project uses the
 [European-Parliament-MCP-Server](https://github.com/Hack23/European-Parliament-MCP-Server)
-v1.3.2 for accessing real EU Parliament data via the Model Context Protocol.
+v1.3.3 for accessing real EU Parliament data via the Model Context Protocol.
 
 - **MCP Server Status**: ✅ Fully operational — 60+ EP data tools available
   (feeds, direct lookups, analytical tools, intelligence correlation)
@@ -432,7 +432,7 @@ import type { ArticleCategory, LanguageCode } from 'euparliamentmonitor/types';
 
 ## 🔌 Data Sources
 
-**Primary — European Parliament MCP Server** ([Hack23/European-Parliament-MCP-Server](https://github.com/Hack23/European-Parliament-MCP-Server) v1.3.2+, fully operational):
+**Primary — European Parliament MCP Server** ([Hack23/European-Parliament-MCP-Server](https://github.com/Hack23/European-Parliament-MCP-Server) v1.3.3+, fully operational):
 
 - 🗳️ Plenary sessions, voting records, roll-call votes
 - 📜 Adopted texts, motions, resolutions, urgency files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",
@@ -70,6 +70,8 @@
     "generate-article:all": "node scripts/aggregator/article-generator.js --all",
     "generate-news-indexes": "node scripts/generators/news-indexes.js",
     "generate-sitemap": "node scripts/generators/sitemap.js",
+    "optimize-css": "node scripts/optimize-css.js",
+    "minify-assets": "node scripts/minify-assets.js",
     "validate-ep-api": "npx tsx src/utils/validate-ep-api.ts",
     "lint:prompts": "node scripts/lint-prompts.js",
     "htmlhint": "sh -c 'htmlhint *.html; set -- news/*.html; if [ -e \"$1\" ]; then htmlhint \"$@\"; else echo \"No news/*.html files to lint\"; fi'",
@@ -143,17 +145,18 @@
   "devDependencies": {
     "@axe-core/playwright": "4.11.3",
     "@eslint/js": "10.0.1",
-    "@playwright/test": "1.59.1",
+    "@playwright/test": "1.60.0",
     "@types/d3": "7.4.3",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "25.6.2",
+    "@types/node": "25.7.0",
     "@types/papaparse": "5.5.2",
-    "@typescript-eslint/eslint-plugin": "8.59.2",
-    "@typescript-eslint/parser": "8.59.2",
-    "@vitest/coverage-v8": "4.1.5",
-    "@vitest/ui": "4.1.5",
+    "@typescript-eslint/eslint-plugin": "8.59.3",
+    "@typescript-eslint/parser": "8.59.3",
+    "@vitest/coverage-v8": "4.1.6",
+    "@vitest/ui": "4.1.6",
     "chart.js": "4.5.1",
     "chartjs-plugin-annotation": "3.1.0",
+    "clean-css": "^5.3.3",
     "d3": "7.9.0",
     "eslint": "10.3.0",
     "eslint-config-prettier": "10.1.8",
@@ -161,25 +164,28 @@
     "eslint-plugin-security": "4.0.0",
     "eslint-plugin-sonarjs": "4.0.3",
     "happy-dom": "20.9.0",
+    "html-minifier-terser": "^7.2.0",
     "htmlhint": "1.9.2",
     "husky": "9.1.7",
-    "jscpd": "4.1.0",
+    "jscpd": "4.1.1",
     "knip": "^6.7.0",
     "lint-staged": "17.0.4",
-    "mermaid": "11.14.0",
+    "mermaid": "11.15.0",
     "papaparse": "5.5.3",
     "prettier": "3.8.3",
+    "purgecss": "7.0.2",
+    "terser": "^5.47.1",
     "ts-api-utils": "2.5.0",
     "tsx": "4.21.0",
     "typedoc": "0.28.19",
     "typescript": "6.0.3",
-    "vitest": "4.1.5"
+    "vitest": "4.1.6"
   },
   "engines": {
     "node": ">=26"
   },
   "dependencies": {
-    "european-parliament-mcp-server": "1.3.2",
+    "european-parliament-mcp-server": "1.3.3",
     "markdown-it": "^14.1.1",
     "markdown-it-anchor": "^9.2.0",
     "markdown-it-attrs": "^4.3.1",

package/scripts/aggregator/analysis-aggregator.d.ts

@@ -154,7 +154,7 @@ export declare function renderReaderIntelligenceGuide(sections: readonly TocSect
  *
  * Thin re-export of {@link _resolveArticleType} from
  * `aggregator/manifest/index.js`. Resolution order: `articleType` →
- * `articleTypes[0]` → `runType` → `'unknown'`.
+ * `articleTypeSlug` → `articleTypes[0]` → `runType` → `'unknown'`.
  *
  * @param manifest - Parsed manifest (any of the supported schemas)
  * @returns Article-type slug usable as a filename component

package/scripts/aggregator/analysis-aggregator.js

@@ -72,9 +72,6 @@ export function expandSectionArtifacts(section, available, consumed) {
         else if (available.has(entry) && !consumed.has(entry)) {
             out.push(entry);
             consumed.add(entry);
-            // `executive-brief.md` is the canonical Riksdagsmonitor-aligned path;
-            // `extended/executive-brief.md` remains a compatibility fallback. When
-            // both exist, render only the canonical root file.
             if (section.id === 'executive-brief')
                 break;
         }
@@ -140,8 +137,6 @@ function collectRunArtifacts(runDir) {
             const full = path.join(dir, entry.name);
             const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
             if (entry.isDirectory()) {
-                // Skip raw payloads, prior-run snapshots, and Pass-1 work-in-progress
-                // snapshots so they are not rendered as supplementary artifacts.
                 if (entry.name === 'data' || entry.name === 'runs' || entry.name === 'pass1')
                     continue;
                 walk(full, rel);
@@ -213,12 +208,6 @@ export function renderTradecraftAppendix(files) {
         'This article is produced under the [Hack23 AB](https://hack23.com) intelligence tradecraft library. Every methodology and artifact template applied to this run is linked below.',
         '',
     ];
-    // Order: Artifact templates first (concrete deliverables readers
-    // recognise from the article body), then Methodologies (the underlying
-    // tradecraft library). This matches the natural reader flow — the
-    // article is built from artifacts, and the methodologies explain how
-    // each artifact is produced — and pairs with the contextual, kind-
-    // aware "View …" CTAs rendered in `enhanceTradecraftCards`.
     if (templates.length > 0) {
         block.push('### Artifact templates');
         block.push('');
@@ -295,6 +284,10 @@ const READER_GUIDE_EN = {
         need: 'Significance scoring',
         value: 'why this story outranks or trails other same-day European Parliament signals',
     },
+    'section-actors-forces': {
+        need: 'Actors and forces',
+        value: 'who is driving the story, what political forces line up behind them, and which institutional levers they can pull',
+    },
     'section-coalitions-voting': {
         need: 'Coalitions and voting',
         value: 'political group alignment, voting evidence, and coalition pressure points',
@@ -315,6 +308,50 @@ const READER_GUIDE_EN = {
         need: 'Risk assessment',
         value: 'policy, institutional, coalition, communications, and implementation risk register',
     },
+    'section-threat': {
+        need: 'Threat landscape',
+        value: 'hostile actors, attack vectors, consequence trees, and legislative-disruption pathways',
+    },
+    'section-forward-projection': {
+        need: 'What to watch',
+        value: 'dated trigger events, calendar dependencies, and legislative-pipeline forecasts',
+    },
+    'section-electoral-arc': {
+        need: 'Electoral arc and mandate',
+        value: 'where the story sits in the EP term, mandate fulfilment, seat projection, and presidency-trio context',
+    },
+    'section-pestle-context': {
+        need: 'PESTLE and structural context',
+        value: 'political, economic, social, technological, legal, and environmental forces plus the historical baseline',
+    },
+    'section-continuity': {
+        need: 'Cross-run continuity',
+        value: 'what changed since prior sessions and how confidence shifted between runs',
+    },
+    'section-deep-analysis': {
+        need: 'Deep analysis',
+        value: 'long-form Economist-style explanation for readers who want the full argument',
+    },
+    'section-documents': {
+        need: 'Document trail',
+        value: 'the document index and per-file analysis behind the public judgement',
+    },
+    'section-extended-intel': {
+        need: 'Extended intelligence',
+        value: "devil's-advocate critique, comparative parallels, historical precedents, and media framing",
+    },
+    'section-mcp-reliability': {
+        need: 'MCP data reliability',
+        value: 'which feeds were healthy, which were degraded, and how data limits bound conclusions',
+    },
+    'section-quality-reflection': {
+        need: 'Analytical quality and reflection',
+        value: 'self-assessment scores, methodology audit, structured analytic techniques, and known limitations',
+    },
+    'section-supplementary-intelligence': {
+        need: 'Supplementary intelligence',
+        value: 'additional markdown discovered in the run that has not yet been assigned to a canonical section',
+    },
 };
 /**
  * Render the generated reader-intelligence guide that appears before the
@@ -332,7 +369,6 @@ const READER_GUIDE_EN = {
 export function renderReaderIntelligenceGuide(sections, included) {
     const rows = sections
         .map((section) => {
-        // Guard: only include sections whose IDs are in the canonical list
         if (!READER_GUIDE_SECTION_IDS.includes(section.id))
             return '';
         const copy = Object.getOwnPropertyDescriptor(READER_GUIDE_EN, section.id)?.value;
@@ -386,10 +422,6 @@ function renderArtifactFragment(runDir, runRel, runDirRelPath, seenMermaid, sect
     });
     const stem = runRel.split('/').pop()?.replace(/\.md$/i, '') ?? runRel;
     const headerLines = suppressHeader ? [] : ['', `### ${humanize(stem)}`];
-    // Per-section "View source" links are intentionally omitted — references
-    // are consolidated in the end-of-document Analysis Index appendix so the
-    // body reads as a journalistic / political-intelligence narrative rather
-    // than as a per-paragraph artifact dump.
     const lines = [...headerLines, '', cleaned.markdown];
     const included = {
         runRelPath: runRel,
@@ -467,9 +499,6 @@ function appendSection(runDir, runDirRelPath, sectionId, sectionTitle, paths, se
         fragments.push(...fragment.lines);
         included.push(fragment.included);
     }
-    // Only emit the section H2 + body when at least one artifact was rendered;
-    // an empty heading with no content is a workflow-metadata leak (used to
-    // happen for the Supplementary bucket when leftovers were missing on disk).
     if (fragments.length === 0)
         return;
     sectionMarkdown.push(`<h2 id="${emittedId}">${sectionTitle}</h2>`);
@@ -482,7 +511,7 @@ function appendSection(runDir, runDirRelPath, sectionId, sectionTitle, paths, se
  *
  * Thin re-export of {@link _resolveArticleType} from
  * `aggregator/manifest/index.js`. Resolution order: `articleType` →
- * `articleTypes[0]` → `runType` → `'unknown'`.
+ * `articleTypeSlug` → `articleTypes[0]` → `runType` → `'unknown'`.
  *
  * @param manifest - Parsed manifest (any of the supported schemas)
  * @returns Article-type slug usable as a filename component
@@ -513,11 +542,6 @@ export function aggregateAnalysisRun(options) {
     }
     const manifestFiles = flattenManifestFiles(manifest.files);
     const discovered = collectRunArtifacts(runDir);
-    // Merge manifest-declared files with discovered files; manifest gives order
-    // priority, discovery ensures nothing is missed. Filter to renderable
-    // markdown only and exclude raw payload directories (`data/`, `runs/`,
-    // `pass1/`) — these are workflow-internal and would leak into the
-    // Supplementary bucket as JSON dumps if the manifest declared them.
     const availableSet = new Set([...manifestFiles, ...discovered].filter((p) => p.endsWith('.md') &&
         !p.startsWith('data/') &&
         !p.startsWith('runs/') &&
@@ -529,10 +553,6 @@ export function aggregateAnalysisRun(options) {
     const sectionMarkdown = [];
     const seenMermaid = new Set();
     const runDirRelPath = path.relative(repoRoot, runDir).split(path.sep).join('/');
-    // Render the Executive Brief section first into a dedicated buffer so it
-    // can be placed BEFORE the Reader Intelligence Guide — analysts and
-    // journalists need the BLUF up front; the TOC-style guide then orients
-    // the reader for the deeper sections that follow.
     const execBriefMarkdown = [];
     const [execBriefSection, ...remainingSections] = ARTIFACT_SECTIONS;
     if (execBriefSection) {
@@ -543,7 +563,6 @@ export function aggregateAnalysisRun(options) {
         const paths = expandSectionArtifacts(section, new Set(available), consumed);
         appendSection(runDir, runDirRelPath, section.id, section.title, paths, seenMermaid, sectionMarkdown, includedArtifacts, emittedSections);
     }
-    // Supplementary bucket: anything that didn't match a declared section
     const leftovers = available.filter((p) => !consumed.has(p));
     if (leftovers.length > 0) {
         appendSection(runDir, runDirRelPath, SUPPLEMENTARY_SECTION_ID, SUPPLEMENTARY_SECTION_TITLE, leftovers, seenMermaid, sectionMarkdown, includedArtifacts, emittedSections);
@@ -568,19 +587,7 @@ export function aggregateAnalysisRun(options) {
     const tradecraft = renderTradecraftAppendix(tradecraftFiles);
     const analysisIndex = renderAnalysisIndex(includedArtifacts, manifestRelPath);
     const readerGuide = renderReaderIntelligenceGuide(emittedSections, includedArtifacts);
-    // Deterministic 3–7 bullet "Key takeaways" block, harvested from the
-    // synthesis-summary / intelligence-assessment artifacts. Sits between
-    // the Reader Intelligence Guide and the deep sections: the reader gets
-    // the BLUF (Executive Brief) → a navigation map (Reader Guide) → a
-    // bullet digest of the strongest findings (Key Takeaways) → the deep
-    // analysis. This is the order requested for reader UX so navigation
-    // is established before the reader commits to scanning takeaways.
     const keyTakeaways = buildKeyTakeaways({ runDir });
-    // TOC ordering must match the rendered Markdown body 1:1. Order:
-    // Executive Brief (already first in emittedSections via appendSection) →
-    // Reader Intelligence Guide (inserted right after the brief when present) →
-    // Key Takeaways (inserted right after the guide when present) →
-    // remaining sections → audit appendices.
     let postBriefIdx = emittedSections.length > 0 &&
         emittedSections[0]?.id === namespacedSectionId(execBriefSection?.id ?? '')
         ? 1

package/scripts/aggregator/article-generator.d.ts

@@ -42,7 +42,7 @@ export interface CliOptions {
      */
     readonly markdownOnly: boolean;
 }
-/** Result summary returned by {@link generateArticle}. */
+/** Result summary returned by `generateArticle`. */
 export interface GenerateResult {
     /** Repo-relative path of the English source Markdown that was written. */
     readonly sourceMarkdownRelPath: string;
@@ -63,6 +63,19 @@ export interface GenerateResult {
     /** Metadata from {@link aggregateAnalysisRun}. */
     readonly aggregated: AggregatedRun;
 }
+/**
+ * Parse the article-generator CLI argv into a {@link CliOptions} struct.
+ *
+ * Recognises `--run-dir <dir>` (or `--run-dir=<dir>`), `--all`, `--out-dir <dir>`,
+ * `--title <s>`, `--description <s>`, `--help`/`-h`, and rejects the historical
+ * `--lang` / `--language` / `--markdown-only` flags now that the CLI always
+ * renders all 14 languages with HTML output.
+ *
+ * @param argv - Argument vector excluding `node` and the script path.
+ * @param repoRoot - Absolute path to the repository root, used to default `outDir`.
+ * @returns Parsed CLI options ready to feed into `generateArticle`.
+ * @throws {Error} On unknown flags, missing values, or removed flags.
+ */
 export declare function parseCliArgs(argv: readonly string[], repoRoot: string): CliOptions;
 /**
  * Build the article slug `YYYY-MM-DD-<article-type>[-<runSuffix>]`.

package/scripts/aggregator/article-generator.js

@@ -63,13 +63,24 @@ function applyFlagResult(acc, result) {
             acc.description = result.value;
             return;
         default: {
-            // Exhaustiveness guard — if a new FlagResult kind is added without a
-            // matching case the compiler will surface the gap.
             const exhaustive = result;
             throw new Error(`Unhandled flag result: ${JSON.stringify(exhaustive)}`);
         }
     }
 }
+/**
+ * Parse the article-generator CLI argv into a {@link CliOptions} struct.
+ *
+ * Recognises `--run-dir <dir>` (or `--run-dir=<dir>`), `--all`, `--out-dir <dir>`,
+ * `--title <s>`, `--description <s>`, `--help`/`-h`, and rejects the historical
+ * `--lang` / `--language` / `--markdown-only` flags now that the CLI always
+ * renders all 14 languages with HTML output.
+ *
+ * @param argv - Argument vector excluding `node` and the script path.
+ * @param repoRoot - Absolute path to the repository root, used to default `outDir`.
+ * @returns Parsed CLI options ready to feed into `generateArticle`.
+ * @throws {Error} On unknown flags, missing values, or removed flags.
+ */
 export function parseCliArgs(argv, repoRoot) {
     const acc = {
         runDir: null,
@@ -102,13 +113,9 @@ export function parseCliArgs(argv, repoRoot) {
     const opts = {
         runDir: acc.runDir,
         all: acc.all,
-        // Always render every language — the `--lang/--language` flags have
-        // been removed in the always-14-languages contract.
         langs: [...ALL_LANGUAGES],
         outDir: acc.outDir,
         repoRoot,
-        // Always emit HTML — the `--markdown-only` flag has been removed in
-        // the always-HTML contract.
         markdownOnly: false,
         ...(acc.since !== undefined ? { since: acc.since } : {}),
         ...(acc.title !== undefined ? { title: acc.title } : {}),
@@ -153,9 +160,6 @@ function applyCliFlag(flag, takeValue) {
         case '--lang':
         case '--language':
         case '--markdown-only':
-            // Removed in the always-14-languages-always-HTML contract — every
-            // article.md now always renders to all 14 supported languages and
-            // HTML emission cannot be skipped from the CLI.
             throw new Error(`Flag ${flag} has been removed. The CLI always renders all 14 languages with HTML output. ` +
                 `See Article-Generation.md § "CLI contract" for the new always-on contract.`);
         default:
@@ -265,8 +269,6 @@ const FALLBACK_DESCRIPTION = 'EU Parliament intelligence summary derived from co
  * @returns Plain-text description, truncated to ≤300 characters
  */
 export function extractDefaultDescription(markdown) {
-    // Suppress unused warning: keep `shouldSkipDescriptionLine` for any
-    // historic consumer importing it transitively.
     void shouldSkipDescriptionLine;
     const strong = extractStrongProseLine(markdown);
     return strong.length > 0 ? strong : FALLBACK_DESCRIPTION;
@@ -290,15 +292,20 @@ function yamlEscape(value) {
  * @param metadata - English metadata resolved for SEO
  * @param metadata.title - Resolved English article title
  * @param metadata.description - Resolved English article description
+ * @param metadata.keywords - Resolved English SEO keywords
  * @param slug - Article slug used by generated news paths
  * @param sourceFolder - Repo-relative analysis run directory
  * @returns Markdown with YAML front matter followed by the aggregate body
  */
 function buildJekyllArticleMarkdown(aggregated, metadata, slug, sourceFolder) {
+    const keywords = metadata.keywords?.length
+        ? `keywords: [${metadata.keywords.map((keyword) => `"${yamlEscape(keyword)}"`).join(', ')}]`
+        : 'keywords: []';
     const frontMatter = [
         '---',
         `title: "${yamlEscape(metadata.title)}"`,
         `description: "${yamlEscape(metadata.description)}"`,
+        keywords,
         `date: ${aggregated.date}`,
         `article_type: ${aggregated.articleType}`,
         `slug: ${slug}`,
@@ -314,7 +321,7 @@ function buildJekyllArticleMarkdown(aggregated, metadata, slug, sourceFolder) {
 /**
  * Render a single language-variant article. Pulls from a pre-translated
  * `<slug>.<lang>.md` file when it exists, otherwise renders the English
- * aggregate. Extracted from {@link generateArticle} so the outer function
+ * aggregate. Extracted from `generateArticle` so the outer function
  * stays under the cognitive-complexity budget.
  *
  * @param lang - Target language code
@@ -323,7 +330,7 @@ function buildJekyllArticleMarkdown(aggregated, metadata, slug, sourceFolder) {
  * @param englishHtml - Pre-rendered HTML of the English aggregate
  * @param chromeOptions - Shared chrome options
  * @param chromeOptions.metadata - Per-language `{title, description}` map
- *        resolved by {@link resolveArticleMetadata}
+ *        resolved by `resolveArticleMetadata`
  * @param chromeOptions.sourceMarkdownRelPath - Repo-relative path of the
  *        canonical English Markdown source written by the same run
  * @param chromeOptions.articleCount - Total article count surfaced in the
@@ -340,41 +347,15 @@ function writeLanguageVariant(lang, slug, aggregated, englishHtml, chromeOptions
         metaSource = fs.readFileSync(langMdAbs, 'utf8');
         bodyHtml = renderMarkdown(metaSource).html;
     }
-    // Strip any AI-authored inline Reader Intelligence Guide and inject the
-    // renderer-owned, language-aware version so exactly one guide appears.
     bodyHtml = stripInlineReaderGuide(bodyHtml);
-    // The article chrome (wrapArticleHtml) renders its own <h1> in the hero
-    // header. Strip the in-body <h1> emitted from the Markdown `# Title` to
-    // avoid a duplicate H1 and broken heading hierarchy (H2 preceding H1).
     bodyHtml = bodyHtml.replace(/<h1[^>]*>[\s\S]*?<\/h1>\s*/, '');
     const guideHtml = buildReaderIntelligenceGuideHtml(lang, aggregated.sectionToc, aggregated.includedArtifacts);
     if (guideHtml) {
-        // Insert the guide IMMEDIATELY AFTER the Executive Brief section so
-        // the rendered HTML body order matches the documented article
-        // skeleton (Article-Generation.md §"Article skeleton"):
-        //   1. Executive Brief
-        //   2. Reader Intelligence Guide
-        //   3. Key Takeaways
-        //   4. … deep sections
-        // We splice at the start of the next H2 after the Executive Brief
-        // anchor; when the brief is missing (sparse runs) we fall back to
-        // prepending so the guide still appears at the top of the body.
         bodyHtml = insertReaderGuideAfterExecutiveBrief(bodyHtml, guideHtml);
     }
-    // Localize Tradecraft References, Analysis Index, and other appendix
-    // section headings and content into the target language.
     bodyHtml = localizeArticleBody(bodyHtml, lang);
-    // Replace the plain Tradecraft References bullet lists and the
-    // Analysis Index table with `pi-card-grid` cards. Runs for every
-    // language (including English) so the "much nicer" rendering matches
-    // the political-intelligence.html visual vocabulary site-wide.
     bodyHtml = enhanceTradecraftCards(bodyHtml, lang);
     bodyHtml = enhanceAnalysisIndexCards(bodyHtml, lang);
-    // When a per-language translated source exists, prefer a summary derived
-    // from it so the `<meta description>` matches the visible prose. The
-    // editorial title still comes from the English resolver (per-language
-    // translations of the headline are a future enhancement tracked as
-    // out-of-scope).
     const entry = getMetadataEntry(chromeOptions.metadata, lang);
     const perLangDescription = lang !== 'en' && metaSource !== aggregated.markdown
         ? extractStrongProseLine(metaSource) || entry.description
@@ -385,6 +366,7 @@ function writeLanguageVariant(lang, slug, aggregated, englishHtml, chromeOptions
         body: bodyHtml,
         title: entry.title,
         description: perLangDescription,
+        keywords: entry.keywords,
         date: aggregated.date,
         articleType: aggregated.articleType,
         sourceMarkdownRelPath: chromeOptions.sourceMarkdownRelPath,
@@ -419,16 +401,11 @@ export function insertReaderGuideAfterExecutiveBrief(bodyHtml, guideHtml) {
     if (briefIdx === -1) {
         return guideHtml + '\n' + bodyHtml;
     }
-    // Skip the Executive Brief opening tag itself, then walk forward to the
-    // next H2 — that's where the next section starts and where we want to
-    // splice the guide. `<h2 ` matches a tag with attributes; `<h2>` matches
-    // a bare tag (defensive).
     const afterBrief = briefIdx + execBriefAnchor.length;
     const nextH2Tagged = bodyHtml.indexOf('<h2 ', afterBrief);
     const nextH2Bare = bodyHtml.indexOf('<h2>', afterBrief);
     const nextH2 = pickEarliestIndex(nextH2Tagged, nextH2Bare);
     if (nextH2 === -1) {
-        // Executive Brief is the only section — append the guide at the end.
         return bodyHtml + '\n' + guideHtml;
     }
     return bodyHtml.slice(0, nextH2) + guideHtml + '\n' + bodyHtml.slice(nextH2);
@@ -459,7 +436,7 @@ function pickEarliestIndex(a, b) {
  * @param map - Resolved per-language metadata
  * @param lang - Target language code
  * @returns The entry for `lang` (always populated by
- *          {@link resolveArticleMetadata})
+ *          `resolveArticleMetadata`)
  */
 function getMetadataEntry(map, lang) {
     const descriptor = Object.getOwnPropertyDescriptor(map, lang);
@@ -467,7 +444,7 @@ function getMetadataEntry(map, lang) {
         return descriptor.value;
     }
     const en = Object.getOwnPropertyDescriptor(map, 'en')?.value;
-    return en ?? { title: '', description: '' };
+    return en ?? { title: '', description: '', keywords: [] };
 }
 /**
  * Count the number of articles the site currently publishes, derived
@@ -475,7 +452,7 @@ function getMetadataEntry(map, lang) {
  * set that `npm run generate-article:all` would materialise. Using the
  * analysis-run catalogue (rather than the `<outDir>` filesystem) keeps
  * the derived count stable across repeated invocations of
- * {@link generateArticle}, preserving determinism for reproducible-build
+ * `generateArticle`, preserving determinism for reproducible-build
  * tests and preventing the footer from drifting as a batch run
  * progresses.
  *
@@ -513,11 +490,6 @@ export function generateArticle(opts, runSuffix, articleCountOverride) {
         repoRoot: opts.repoRoot,
     });
     const slug = buildArticleSlug(aggregated.date, aggregated.articleType, runSuffix);
-    // Resolve per-language {title, description} from the real article
-    // content (manifest override → artefact H1 → aggregated H1 → strong
-    // prose → localized template). This replaces the previous
-    // `defaultTitle()` + `extractDefaultDescription()` approach which
-    // produced boring, repeated metadata.
     const manifestMetadata = readManifestMetadata(opts.runDir);
     const resolvedMetadata = resolveArticleMetadata({
         articleType: aggregated.articleType,
@@ -526,28 +498,17 @@ export function generateArticle(opts, runSuffix, articleCountOverride) {
         manifest: manifestMetadata,
         runDir: opts.runDir,
     });
-    // CLI `--title` / `--description` overrides still win over everything
-    // (used by ad-hoc curator runs and by the existing test suite).
     const effectiveMetadata = opts.title || opts.description
         ? applyCliOverrides(resolvedMetadata, opts.title, opts.description)
         : resolvedMetadata;
     const runDirRelPath = path.relative(opts.repoRoot, opts.runDir).split(path.sep).join('/');
     const sourceMarkdown = buildJekyllArticleMarkdown(aggregated, getMetadataEntry(effectiveMetadata, 'en'), slug, runDirRelPath);
-    // Write article.md INTO the analysis run directory — canonical Markdown
-    // source that lives alongside the artifacts that produced it.
-    // This mirrors the riksdagsmonitor pattern where `article.md` is committed
-    // inside `analysis/daily/<date>/<type>/` so every run has a browsable,
-    // version-controlled Markdown source in its own directory.
     const runArticleMdAbs = path.join(opts.runDir, 'article.md');
     fs.writeFileSync(runArticleMdAbs, sourceMarkdown, 'utf8');
     const runArticleMdRelPath = path
         .relative(opts.repoRoot, runArticleMdAbs)
         .split(path.sep)
         .join('/');
-    // Emit `article-meta.json` next to `article.md` — a deterministic
-    // structured-data sidecar consumed by HTML SEO, news indexes, and RSS.
-    // Same artifact bytes in → same JSON bytes out (asserted by the
-    // determinism test).
     const runArticleMetaAbs = path.join(opts.runDir, 'article-meta.json');
     const articleMeta = buildArticleMeta({
         runDir: opts.runDir,
@@ -563,8 +524,6 @@ export function generateArticle(opts, runSuffix, articleCountOverride) {
         .relative(opts.repoRoot, runArticleMetaAbs)
         .split(path.sep)
         .join('/');
-    // Also write source Markdown under <outDir>/<slug>.en.md for search
-    // indexing and backwards compatibility with existing news-index scripts.
     ensureDir(opts.outDir);
     const sourceMdFilename = `${slug}.en.md`;
     const sourceMdAbs = path.join(opts.outDir, sourceMdFilename);
@@ -574,8 +533,6 @@ export function generateArticle(opts, runSuffix, articleCountOverride) {
         const rendered = renderMarkdown(sourceMarkdown);
         const chromeOptions = {
             metadata: effectiveMetadata,
-            // Point the "View source Markdown" link at the canonical run-directory
-            // article.md so readers can trace the HTML back to the analysis tree.
             sourceMarkdownRelPath: runArticleMdRelPath,
             articleCount: articleCountOverride ?? countPublishedArticles(opts.repoRoot),
         };
@@ -632,9 +589,6 @@ export function generateAllArticles(opts) {
     const filtered = opts.since ? allRuns.filter((r) => r.date >= opts.since) : allRuns;
     const groups = groupRunsForCollision(filtered);
     const results = [];
-    // Pre-compute the total article count so every footer in the batch
-    // surfaces a stable number rather than the directory size at the moment
-    // each run is rendered (which would grow from 0 → N during the batch).
     const articleCountOverride = filtered.length;
     for (const run of filtered) {
         const key = `${run.date}|${run.articleType}`;
@@ -670,7 +624,7 @@ function readManifestRunId(runDir, defaultRunId) {
 }
 /**
  * Read the raw manifest.json from a run directory and return the subset
- * of fields consumed by {@link resolveArticleMetadata}. Returns an empty
+ * of fields consumed by `resolveArticleMetadata`. Returns an empty
  * object when the manifest is missing or unreadable so the resolver
  * simply falls through to the artefact / aggregator tiers.
  *
@@ -744,6 +698,7 @@ function applyCliOverrides(base, titleOverride, descriptionOverride) {
             value: {
                 title: titleOverride ?? entry.title,
                 description: descriptionOverride ?? entry.description,
+                keywords: entry.keywords,
             },
             enumerable: true,
             writable: true,
@@ -755,7 +710,7 @@ function applyCliOverrides(base, titleOverride, descriptionOverride) {
 /**
  * Derive a default article title from the aggregated run metadata.
  * Preserved as a thin back-compat wrapper — production callers now go
- * through {@link resolveArticleMetadata}.
+ * through `resolveArticleMetadata`.
  *
  * @param run - Aggregated run metadata
  * @returns Human-readable title like `EU Parliament Breaking — 2026-01-15`

package/scripts/aggregator/article-html.d.ts

@@ -15,12 +15,14 @@ export interface WrapArticleOptions {
      * `2026-01-15-breaking`. Used to build the `<link rel="alternate">` set.
      */
     readonly articleSlug: string;
-    /** Pre-rendered HTML body fragment (from {@link renderMarkdown}). */
+    /** Pre-rendered HTML body fragment (from `renderMarkdown`). */
     readonly body: string;
     /** Article title — shown in `<title>`, breadcrumb, OG/Twitter meta. */
     readonly title: string;
     /** Article description — shown in `<meta name="description">` and OG. */
     readonly description: string;
+    /** SEO keywords — shown in `<meta name="keywords">`. */
+    readonly keywords?: readonly string[];
     /** Canonical ISO date of the run (YYYY-MM-DD). */
     readonly date: string;
     /** Article type slug (e.g. `breaking`, `motions`). */