euparliamentmonitor 0.9.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",

package/scripts/aggregator/analysis-aggregator.js

@@ -550,30 +550,33 @@ export function aggregateAnalysisRun(options) {
     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. Placed
-    // immediately after the Executive Brief so the reader gets the BLUF
-    // followed by a digest of the strongest findings before being handed
-    // off to the Reader Intelligence Guide and the deeper sections.
+    // 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 reflects the rendered document:
+    // TOC ordering must match the rendered Markdown body 1:1. Order:
     // Executive Brief (already first in emittedSections via appendSection) →
-    // Key Takeaways (inserted right after the brief when present) →
-    // Reader Intelligence Guide → remaining sections → audit appendices.
+    // 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
         : 0;
-    if (keyTakeaways) {
+    if (readerGuide) {
         emittedSections.splice(postBriefIdx, 0, {
-            id: KEY_TAKEAWAYS_SECTION_ID,
-            title: KEY_TAKEAWAYS_SECTION_TITLE,
+            id: READER_GUIDE_SECTION_ID,
+            title: READER_GUIDE_SECTION_TITLE,
         });
         postBriefIdx += 1;
     }
-    if (readerGuide) {
+    if (keyTakeaways) {
         emittedSections.splice(postBriefIdx, 0, {
-            id: READER_GUIDE_SECTION_ID,
-            title: READER_GUIDE_SECTION_TITLE,
+            id: KEY_TAKEAWAYS_SECTION_ID,
+            title: KEY_TAKEAWAYS_SECTION_TITLE,
         });
     }
     emittedSections.push({ id: TRADECRAFT_SECTION_ID, title: TRADECRAFT_SECTION_TITLE });
@@ -583,9 +586,8 @@ export function aggregateAnalysisRun(options) {
         '',
         ...execBriefMarkdown,
         '',
+        ...(readerGuide ? [readerGuide, ''] : []),
         ...(keyTakeaways ? [keyTakeaways, ''] : []),
-        readerGuide,
-        '',
         ...sectionMarkdown,
         '',
         provenance,

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

@@ -19,7 +19,11 @@ export interface CliOptions {
      * is earlier are skipped.
      */
     readonly since?: string;
-    /** Languages to render (defaults to all 14). */
+    /**
+     * Languages to render. Defaults to all 14. The CLI always populates
+     * this with `[...ALL_LANGUAGES]` (the `--lang/--language` flags have
+     * been removed); programmatic callers (tests) can override it.
+     */
     readonly langs: readonly LanguageCode[];
     /** Output directory for HTML files (defaults to `news/`). */
     readonly outDir: string;
@@ -30,8 +34,11 @@ export interface CliOptions {
     /** Optional: override the auto-derived article description (single-run only). */
     readonly description?: string;
     /**
-     * When true, only the source Markdown is written (no HTML) — useful for
-     * upstream pipelines that translate first and then batch-render.
+     * When true, only the source Markdown is written (no HTML) — preserved
+     * for programmatic callers (tests) that need to skip HTML emission for
+     * speed. The CLI no longer exposes a flag for this and always sets
+     * `false`; every workflow-driven invocation emits HTML for all 14
+     * languages.
      */
     readonly markdownOnly: boolean;
 }

package/scripts/aggregator/article-generator.js

@@ -10,9 +10,14 @@
  *
  * Usage:
  *   npm run generate-article -- --run analysis/daily/2026-01-15/breaking-run1
- *   npm run generate-article -- --run ... --lang en --lang sv
  *   npm run generate-article -- --run ... --out-dir news --title "Headline"
  *
+ * **Always-14-languages-always-HTML contract**: every CLI invocation
+ * renders every supported language to HTML. The legacy `--lang` /
+ * `--language` / `--markdown-only` flags have been removed. The
+ * programmatic `generateArticle()` API still accepts `langs` and
+ * `markdownOnly` for tests that need to scope a render for speed.
+ *
  * Designed to be idempotent: running again with no changes overwrites
  * identical files byte-for-byte.
  */
@@ -24,7 +29,7 @@ import { resolveRunId as _resolveRunId } from './manifest/index.js';
 import { resolveArticleMetadata, extractStrongProseLine, } from './article-metadata.js';
 import { buildArticleMeta, serializeArticleMeta } from './article-meta.js';
 import { renderMarkdown } from './markdown-renderer.js';
-import { wrapArticleHtml, getArticleFilename } from './article-html.js';
+import { wrapArticleHtml, getArticleFilename, localizeArticleBody } from './article-html.js';
 import { buildReaderIntelligenceGuideHtml, stripInlineReaderGuide, } from './reader-intelligence-guide.js';
 import { ALL_LANGUAGES } from '../constants/language-core.js';
 import { blobUrl } from './infra/github-urls.js';
@@ -48,9 +53,6 @@ function applyFlagResult(acc, result) {
         case 'since':
             acc.since = result.value;
             return;
-        case 'lang':
-            acc.langs.push(result.value);
-            return;
         case 'outDir':
             acc.outDir = result.value;
             return;
@@ -60,9 +62,6 @@ function applyFlagResult(acc, result) {
         case 'description':
             acc.description = result.value;
             return;
-        case 'markdownOnly':
-            acc.markdownOnly = true;
-            return;
         default: {
             // Exhaustiveness guard — if a new FlagResult kind is added without a
             // matching case the compiler will surface the gap.
@@ -75,9 +74,7 @@ export function parseCliArgs(argv, repoRoot) {
     const acc = {
         runDir: null,
         all: false,
-        langs: [],
         outDir: path.join(repoRoot, 'news'),
-        markdownOnly: false,
     };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i] ?? '';
@@ -105,10 +102,14 @@ export function parseCliArgs(argv, repoRoot) {
     const opts = {
         runDir: acc.runDir,
         all: acc.all,
-        langs: acc.langs.length > 0 ? acc.langs : [...ALL_LANGUAGES],
+        // Always render every language — the `--lang/--language` flags have
+        // been removed in the always-14-languages contract.
+        langs: [...ALL_LANGUAGES],
         outDir: acc.outDir,
         repoRoot,
-        markdownOnly: acc.markdownOnly,
+        // 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 } : {}),
         ...(acc.description !== undefined ? { description: acc.description } : {}),
@@ -117,7 +118,7 @@ export function parseCliArgs(argv, repoRoot) {
 }
 /**
  * Resolve one CLI flag to a {@link FlagResult}. Throws `Error` for any
- * unsupported flag or language code.
+ * unsupported flag.
  *
  * @param flag - Flag name (e.g. `--run`)
  * @param takeValue - Lazily returns the value argument for value-bearing flags
@@ -137,14 +138,6 @@ function applyCliFlag(flag, takeValue) {
             }
             return { kind: 'since', value };
         }
-        case '--lang':
-        case '--language': {
-            const value = takeValue();
-            if (!ALL_LANGUAGES.includes(value)) {
-                throw new Error(`Unsupported language code: ${value}`);
-            }
-            return { kind: 'lang', value: value };
-        }
         case '--out-dir':
         case '--output':
             return { kind: 'outDir', value: path.resolve(takeValue()) };
@@ -152,13 +145,19 @@ function applyCliFlag(flag, takeValue) {
             return { kind: 'title', value: takeValue() };
         case '--description':
             return { kind: 'description', value: takeValue() };
-        case '--markdown-only':
-            return { kind: 'markdownOnly' };
         case '--help':
         case '-h':
             printHelp();
             process.exit(0);
         // eslint-disable-next-line no-fallthrough
+        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:
             throw new Error(`Unknown argument: ${flag}`);
     }
@@ -183,19 +182,22 @@ function printHelp() {
         '  generate-article --all [--since YYYY-MM-DD] [options]',
         '',
         'Aggregate analysis artifacts from an `analysis/daily/**/<run>` directory',
-        'into a canonical Markdown document and render it to HTML in all 14',
-        'languages. The `--all` form walks every run under `analysis/daily/`',
-        'and regenerates the full historic catalogue in one pass.',
+        'into a canonical Markdown document and render it to HTML in **all 14',
+        'supported languages** (en, sv, da, no, fi, de, fr, es, nl, ar, he, ja,',
+        'ko, zh). The `--all` form walks every run under `analysis/daily/` and',
+        'regenerates the full historic catalogue in one pass.',
+        '',
+        'The 14-language HTML render is **always on** — there is no flag to',
+        'scope a render to a single language or to skip HTML emission. Every',
+        'article.md always produces 14 corresponding `<slug>-<lang>.html` files.',
         '',
         'Options:',
         '  --run <path>          Analysis run directory (single-run mode)',
         '  --all                 Batch-regenerate every run under analysis/daily/',
         '  --since YYYY-MM-DD    With --all: skip runs dated before this cut-off',
-        '  --lang <code>         Language to render (repeatable; default: all 14)',
         '  --out-dir <path>      Output directory (default: news/)',
         '  --title <text>        Override article title (single-run only)',
         '  --description <text>  Override article meta description (single-run only)',
-        '  --markdown-only       Write only the source .md (skip HTML)',
         '  --help, -h            Show this help',
         '',
     ].join('\n'));
@@ -354,6 +356,9 @@ function writeLanguageVariant(lang, slug, aggregated, englishHtml, chromeOptions
         // and avoids fragile in-body heading searches.
         bodyHtml = guideHtml + '\n' + bodyHtml;
     }
+    // Localize Tradecraft References, Analysis Index, and other appendix
+    // section headings and content into the target language.
+    bodyHtml = localizeArticleBody(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

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

@@ -84,6 +84,16 @@ export declare function buildArticleHreflangLinks(articleSlug: string): string;
  * @returns HTML fragment for the sidebar, or `""` when no TOC is needed
  */
 export declare function buildArticleToc(entries: readonly ArticleTocEntry[], lang: LanguageCode): string;
+/**
+ * Localize the Tradecraft References and Analysis Index sections in the
+ * rendered article body HTML. Replaces English headings, introductions,
+ * sub-headings, and table headers with translated equivalents.
+ *
+ * @param bodyHtml - The rendered HTML body (from Markdown)
+ * @param lang - Target language code
+ * @returns HTML body with localized appendix sections
+ */
+export declare function localizeArticleBody(bodyHtml: string, lang: LanguageCode): string;
 /**
  * Render the full article HTML document with the shared chrome.
  *

package/scripts/aggregator/article-html.js

@@ -20,11 +20,31 @@
  */
 import { BASE_URL, BUILD_SHORT, MERMAID_VERSION } from '../constants/config.js';
 import { buildHeadFreshnessTags } from '../constants/build-info-meta.js';
-import { ALL_LANGUAGES, LANGUAGE_NAMES, LANGUAGE_FLAGS, PAGE_TITLES, SKIP_LINK_TEXTS, TOC_ARIA_LABELS, getLocalizedString, getTextDirection, } from '../constants/languages.js';
+import { ALL_LANGUAGES, LANGUAGE_NAMES, LANGUAGE_FLAGS, PAGE_TITLES, SKIP_LINK_TEXTS, TOC_ARIA_LABELS, ARTICLE_TYPE_LABELS, VIEW_SOURCE_MARKDOWN_LABELS, ARTICLE_TYPE_ICONS, TRADECRAFT_HEADING_LABELS, TRADECRAFT_INTRO_LABELS, TRADECRAFT_METHODOLOGIES_LABELS, TRADECRAFT_TEMPLATES_LABELS, ANALYSIS_INDEX_HEADING_LABELS, ANALYSIS_INDEX_INTRO_LABELS, ANALYSIS_INDEX_COL_SECTION_LABELS, ANALYSIS_INDEX_COL_ARTIFACT_LABELS, ANALYSIS_INDEX_COL_PATH_LABELS, KEY_TAKEAWAYS_HEADING_LABELS, SUPPLEMENTARY_HEADING_LABELS, SECTION_TITLE_LABELS, getLocalizedString, getTextDirection, } from '../constants/languages.js';
+import { ArticleCategory } from '../types/index.js';
 import { escapeHTML } from '../utils/file-utils.js';
 import { buildSiteFooter, buildSiteHeader, buildPageBanner, } from '../templates/section-builders.js';
 import { READER_GUIDE_SECTION_ID } from './reader-guide-constants.js';
 import { READER_GUIDE_TITLE_LABELS } from './reader-intelligence-guide.js';
+import { TRADECRAFT_SECTION_ID, MANIFEST_SECTION_ID, SUPPLEMENTARY_SECTION_ID, } from './artifact-order.js';
+import { KEY_TAKEAWAYS_SECTION_ID } from './key-takeaways.js';
+/**
+ * Resolve a localized article type label with icon. Falls back to the
+ * humanised slug when a translation isn't available.
+ *
+ * @param slug - Raw article type slug (e.g. "motions", "week-ahead")
+ * @param lang - Target language code
+ * @returns Localized label with preceding emoji icon (e.g. "🗳️ Plenary Votes & Resolutions")
+ */
+function getLocalizedArticleType(slug, lang) {
+    const labels = getLocalizedString(ARTICLE_TYPE_LABELS, lang);
+    const label = labels[slug] ?? slug.replace(/-/g, ' ');
+    const categoryValues = Object.values(ArticleCategory);
+    const iconEmoji = categoryValues.includes(slug)
+        ? ARTICLE_TYPE_ICONS[slug]
+        : '📄';
+    return `${iconEmoji} ${label}`;
+}
 /** Publisher organization name used in JSON-LD, meta tags. */
 const PUBLISHER_NAME = 'Hack23 AB';
 /** Site name used across meta tags and structured data. */
@@ -72,6 +92,44 @@ function buildLanguageSwitcher(articleSlug, current) {
         return `<a href="${href}" class="lang-link${active}" hreflang="${code}" lang="${code}" title="${safeName}" aria-label="${safeName}"${ariaCurrent}>${flag} ${code.toUpperCase()}</a>`;
     }).join('\n        ');
 }
+/**
+ * Resolve a localized title for a TOC entry based on its section ID.
+ * Falls back to the original English title if no translation is available.
+ *
+ * @param sectionId - The fragment identifier of the section
+ * @param fallbackTitle - The English title to fall back to
+ * @param lang - Target language code
+ * @returns Localized title string
+ */
+function getLocalizedTocTitle(sectionId, fallbackTitle, lang) {
+    // Reader Intelligence Guide
+    if (sectionId === READER_GUIDE_SECTION_ID) {
+        return getLocalizedString(READER_GUIDE_TITLE_LABELS, lang);
+    }
+    // Tradecraft References appendix
+    if (sectionId === TRADECRAFT_SECTION_ID) {
+        return getLocalizedString(TRADECRAFT_HEADING_LABELS, lang);
+    }
+    // Analysis Index appendix
+    if (sectionId === MANIFEST_SECTION_ID) {
+        return getLocalizedString(ANALYSIS_INDEX_HEADING_LABELS, lang);
+    }
+    // Key Takeaways
+    if (sectionId === KEY_TAKEAWAYS_SECTION_ID) {
+        return getLocalizedString(KEY_TAKEAWAYS_HEADING_LABELS, lang);
+    }
+    // Supplementary Intelligence
+    if (sectionId === SUPPLEMENTARY_SECTION_ID) {
+        return getLocalizedString(SUPPLEMENTARY_HEADING_LABELS, lang);
+    }
+    // Artifact section titles (strip the `section-` prefix to find the key)
+    const sectionKey = sectionId.replace(/^section-/, '');
+    const sectionLabels = SECTION_TITLE_LABELS[sectionKey];
+    if (sectionLabels) {
+        return getLocalizedString(sectionLabels, lang);
+    }
+    return fallbackTitle;
+}
 /**
  * Build the article-level Table of Contents nav. Renders a labelled
  * `<nav class="article-toc">` with one `<a>` per H2 section, keyed by the
@@ -92,17 +150,14 @@ export function buildArticleToc(entries, lang) {
     const label = escapeHTML(getLocalizedString(TOC_ARIA_LABELS, lang));
     const items = entries
         .map((e) => {
-        // Translate the Reader Intelligence Guide title into the target language
-        const displayTitle = e.id === READER_GUIDE_SECTION_ID
-            ? getLocalizedString(READER_GUIDE_TITLE_LABELS, lang)
-            : e.title;
+        const displayTitle = getLocalizedTocTitle(e.id, e.title, lang);
         return `        <li><a href="#${escapeHTML(e.id)}">${escapeHTML(displayTitle)}</a></li>`;
     })
         .join('\n');
     return [
         `  <aside class="article-toc-container" aria-label="${label}">`,
         `    <details class="article-toc-details" open>`,
-        `      <summary class="article-toc-summary">${label}</summary>`,
+        `      <summary class="article-toc-summary"><span class="guide-icon" aria-hidden="true">📑</span> ${label}</summary>`,
         `      <nav class="article-toc">`,
         `        <ol class="article-toc-list">`,
         items,
@@ -113,6 +168,131 @@ export function buildArticleToc(entries, lang) {
         '',
     ].join('\n');
 }
+/**
+ * Localize the Tradecraft References and Analysis Index sections in the
+ * rendered article body HTML. Replaces English headings, introductions,
+ * sub-headings, and table headers with translated equivalents.
+ *
+ * @param bodyHtml - The rendered HTML body (from Markdown)
+ * @param lang - Target language code
+ * @returns HTML body with localized appendix sections
+ */
+export function localizeArticleBody(bodyHtml, lang) {
+    if (lang === 'en')
+        return bodyHtml;
+    let html = bodyHtml;
+    // --- Tradecraft References heading ---
+    // Use simple string indexOf to avoid polynomial regex backtracking.
+    const tradecraftHeading = getLocalizedString(TRADECRAFT_HEADING_LABELS, lang);
+    html = replaceHeadingById(html, TRADECRAFT_SECTION_ID, 'Tradecraft References', tradecraftHeading);
+    // --- Tradecraft intro paragraph ---
+    // The rendered Markdown produces a <p> containing the intro text with an
+    // <a> link to Hack23. Replace only the known English sentence prefix.
+    // HTML-escape the localized text to prevent injection, then re-insert the
+    // intentional <a> tag via a placeholder split.
+    const tradecraftIntroRaw = getLocalizedString(TRADECRAFT_INTRO_LABELS, lang);
+    const introSentenceStart = 'This article is produced under the ';
+    const introIdx = html.indexOf(introSentenceStart);
+    if (introIdx !== -1) {
+        // Find the end of the sentence (next '</p>' or period followed by '<')
+        const sentenceEnd = html.indexOf('</p>', introIdx);
+        if (sentenceEnd !== -1) {
+            const escapedIntro = escapeHTML(tradecraftIntroRaw);
+            const localizedWithLink = escapedIntro.replace(escapeHTML('Hack23 AB'), '<a href="https://hack23.com">Hack23 AB</a>');
+            html = html.slice(0, introIdx) + localizedWithLink + html.slice(sentenceEnd);
+        }
+    }
+    // --- Methodologies sub-heading ---
+    const methodsLabel = getLocalizedString(TRADECRAFT_METHODOLOGIES_LABELS, lang);
+    html = html.replace(/<h3>Methodologies<\/h3>/, `<h3>${escapeHTML(methodsLabel)}</h3>`);
+    // --- Artifact templates sub-heading ---
+    const templatesLabel = getLocalizedString(TRADECRAFT_TEMPLATES_LABELS, lang);
+    html = html.replace(/<h3>Artifact templates<\/h3>/, `<h3>${escapeHTML(templatesLabel)}</h3>`);
+    // --- Analysis Index heading ---
+    const analysisIndexHeading = getLocalizedString(ANALYSIS_INDEX_HEADING_LABELS, lang);
+    html = replaceHeadingById(html, MANIFEST_SECTION_ID, 'Analysis Index', analysisIndexHeading);
+    // --- Analysis Index intro ---
+    const analysisIndexIntroRaw = getLocalizedString(ANALYSIS_INDEX_INTRO_LABELS, lang);
+    // Use indexOf to find the manifest.json link URL without polynomial regex
+    const manifestLinkPrefix = 'href="';
+    const manifestJsonLiteral = 'manifest.json';
+    const manifestLinkIdx = html.indexOf(manifestJsonLiteral);
+    let manifestUrl = '';
+    if (manifestLinkIdx !== -1) {
+        // Walk backward to find the preceding href="
+        const hrefIdx = html.lastIndexOf(manifestLinkPrefix, manifestLinkIdx);
+        if (hrefIdx !== -1 && manifestLinkIdx - hrefIdx < 200) {
+            const urlStart = hrefIdx + manifestLinkPrefix.length;
+            const urlEnd = html.indexOf('"', urlStart);
+            if (urlEnd !== -1) {
+                manifestUrl = html.slice(urlStart, urlEnd);
+            }
+        }
+    }
+    // HTML-escape the localized intro, then re-insert the <a> link
+    const escapedAnalysisIntro = escapeHTML(analysisIndexIntroRaw);
+    const localizedIntroWithLink = manifestUrl
+        ? escapedAnalysisIntro.replace('manifest.json', `<a href="${escapeHTML(manifestUrl)}">manifest.json</a>`)
+        : escapedAnalysisIntro;
+    // Replace the known English intro sentence using indexOf
+    const analysisIntroStart = 'Every artifact below was read by the aggregator';
+    const analysisIntroIdx = html.indexOf(analysisIntroStart);
+    if (analysisIntroIdx !== -1) {
+        const analysisIntroEnd = html.indexOf('gate-result history.', analysisIntroIdx);
+        if (analysisIntroEnd !== -1) {
+            const endOffset = analysisIntroEnd + 'gate-result history.'.length;
+            html = html.slice(0, analysisIntroIdx) + localizedIntroWithLink + html.slice(endOffset);
+        }
+    }
+    // --- Analysis Index table headers ---
+    const colSection = getLocalizedString(ANALYSIS_INDEX_COL_SECTION_LABELS, lang);
+    const colArtifact = getLocalizedString(ANALYSIS_INDEX_COL_ARTIFACT_LABELS, lang);
+    const colPath = getLocalizedString(ANALYSIS_INDEX_COL_PATH_LABELS, lang);
+    html = html.replace('<th>Section</th><th>Artifact</th><th>Path</th>', `<th>${escapeHTML(colSection)}</th><th>${escapeHTML(colArtifact)}</th><th>${escapeHTML(colPath)}</th>`);
+    // --- Key Takeaways heading ---
+    const keyTakeawaysHeading = getLocalizedString(KEY_TAKEAWAYS_HEADING_LABELS, lang);
+    html = replaceHeadingById(html, KEY_TAKEAWAYS_SECTION_ID, 'Key Takeaways', keyTakeawaysHeading);
+    // --- Supplementary Intelligence heading ---
+    const supplementaryHeading = getLocalizedString(SUPPLEMENTARY_HEADING_LABELS, lang);
+    html = replaceHeadingById(html, SUPPLEMENTARY_SECTION_ID, 'Supplementary Intelligence', supplementaryHeading);
+    return html;
+}
+/**
+ * Replace an H2 heading's text content by locating it via its `id` attribute.
+ * Uses indexOf-based search to avoid polynomial regex backtracking (CodeQL).
+ *
+ * @param html - Full HTML string
+ * @param sectionId - The id attribute value of the target `<h2>`
+ * @param englishTitle - The English title text to replace
+ * @param localizedTitle - The localized title to insert
+ * @returns Updated HTML string
+ */
+function replaceHeadingById(html, sectionId, englishTitle, localizedTitle) {
+    // Find the id attribute in the HTML — this uniquely identifies the heading
+    const idMarker = `id="${sectionId}"`;
+    let idIdx = html.indexOf(idMarker);
+    if (idIdx === -1) {
+        // Try single-quoted variant
+        const idMarkerSingle = `id='${sectionId}'`;
+        idIdx = html.indexOf(idMarkerSingle);
+    }
+    if (idIdx === -1)
+        return html;
+    // Find the closing '>' of the opening tag after the id
+    const tagCloseIdx = html.indexOf('>', idIdx);
+    if (tagCloseIdx === -1)
+        return html;
+    // The title text starts immediately after '>'
+    const titleStart = tagCloseIdx + 1;
+    const titleEnd = html.indexOf('<', titleStart);
+    if (titleEnd === -1)
+        return html;
+    // Verify this is actually the English title we expect
+    const existingTitle = html.slice(titleStart, titleEnd);
+    if (existingTitle.trim() !== englishTitle)
+        return html;
+    return html.slice(0, titleStart) + escapeHTML(localizedTitle) + html.slice(titleEnd);
+}
 /**
  * Render the full article HTML document with the shared chrome.
  *
@@ -129,8 +309,9 @@ export function wrapArticleHtml(options) {
     const indexHref = safeLang === 'en' ? '../index.html' : `../index-${safeLang}.html`;
     const hreflangLinks = buildArticleHreflangLinks(options.articleSlug);
     const langSwitcher = buildLanguageSwitcher(options.articleSlug, safeLang);
+    const sourceMdLabel = getLocalizedString(VIEW_SOURCE_MARKDOWN_LABELS, safeLang);
     const sourceMdLink = options.sourceMarkdownRelPath
-        ? `<p class="article-source-md"><a href="${BASE_URL}/${options.sourceMarkdownRelPath}" rel="alternate" type="text/markdown">View source Markdown</a></p>`
+        ? `<p class="article-source-md"><a href="${BASE_URL}/${options.sourceMarkdownRelPath}" rel="alternate" type="text/markdown"><svg class="icon icon-inline" width="16" height="16" viewBox="0 0 24 24" role="img" aria-hidden="true" focusable="false"><path d="M9 5H7a2 2 0 0 0-2 2v10a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2v-2M12 3h6a2 2 0 0 1 2 2v6M10 14 20 4" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/></svg> ${escapeHTML(sourceMdLabel)}</a></p>`
         : '';
     const tocHtml = buildArticleToc(options.toc ?? [], safeLang);
     const jsonLd = {
@@ -249,7 +430,7 @@ ${buildHeadFreshnessTags('../')}
   <main id="main" class="site-main article-main">
 ${tocHtml}    <article class="article-body" lang="${safeLang}">
       <header class="article-hero">
-        <p class="article-kicker">${escapeHTML(options.articleType.replace(/-/g, ' '))}</p>
+        <p class="article-kicker">${escapeHTML(getLocalizedArticleType(options.articleType, safeLang))}</p>
         <h1>${escapeHTML(options.title)}</h1>
         <p class="article-dek">${escapeHTML(options.description)}</p>
         <p class="article-meta"><time datetime="${options.date}">${options.date}</time> · EU Parliament Monitor</p>

package/scripts/aggregator/cli/parse.d.ts

@@ -1,16 +1,34 @@
 import type { LanguageCode } from '../../types/index.js';
-/** Successful parse → ready-to-execute options. */
+/**
+ * Successful parse → ready-to-execute options.
+ *
+ * **Always-14-languages-always-HTML contract**: the CLI no longer accepts
+ * `--lang/--language` or `--markdown-only` flags — every invocation
+ * generates HTML for **all 14 supported languages**. The `langs` and
+ * `markdownOnly` fields are preserved on the parsed options solely so the
+ * programmatic `generateArticle()` API (driven directly from unit / integration
+ * tests for speed) can still scope a single test run to a subset of
+ * languages or skip HTML emission. They are **not** settable via argv.
+ */
 export interface ParsedOptions {
     readonly kind: 'options';
     readonly value: {
         readonly runDir: string | null;
         readonly all: boolean;
         readonly since?: string;
+        /**
+         * Always `[...ALL_LANGUAGES]` when produced by this CLI parser; tests
+         * may override the field when calling {@link generateArticle} directly.
+         */
         readonly langs: readonly LanguageCode[];
         readonly outDir: string;
         readonly repoRoot: string;
         readonly title?: string;
         readonly description?: string;
+        /**
+         * Always `false` when produced by this CLI parser; tests may set
+         * `true` programmatically to skip HTML emission for speed.
+         */
         readonly markdownOnly: boolean;
     };
 }