euparliamentmonitor 0.8.44 → 0.8.46

package/README.md

@@ -87,6 +87,10 @@ import {
 - 📊 **Article Quality** — Score and validate generated content with comprehensive quality metrics
 - 🌍 **Multilingual** — Full i18n support: EN, SV, DA, NO, FI, DE, FR, ES, NL, AR, HE, JA, KO, ZH
 
+**Explore the live platform** — [🌐 euparliamentmonitor.com](https://euparliamentmonitor.com) · [🧠 Political Intelligence Hub](https://euparliamentmonitor.com/political-intelligence.html) (methodology + artifact transparency, all 14 languages) · [🗺️ Site Map](https://euparliamentmonitor.com/sitemap.html) (every page, every language) · [📔 API Reference](https://euparliamentmonitor.com/docs/api/index.html)
+
+> 📦 **About this package** — `euparliamentmonitor` is the open-source TypeScript library powering [euparliamentmonitor.com](https://euparliamentmonitor.com), an automated **European Parliament transparency platform** that publishes daily AI-generated, *Economist-style* political-intelligence articles in 14 languages. The package bundles the **EU Parliament MCP client** (60+ open-data tools — plenary sessions, committee reports, voting records, parliamentary questions, adopted texts, procedures, MEPs, declarations), the **deterministic article aggregator** (analysis-artifact → Markdown → HTML, with 14-language hreflang and shared site chrome), the **political-intelligence analytics** (voting-anomaly detection, coalition dynamics, MEP influence scoring, OSINT correlation), and the **multi-language renderer** with WCAG 2.1 AA accessibility, structured data, and SEO-ready sitemap generation. Designed for civic-tech, data-journalism, OSINT, and democratic-transparency use cases. ISO 27001 / NIST CSF 2.0 / CIS Controls v8.1 / GDPR / NIS2 / EU CRA aligned.
+
 > Published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) for supply chain security. [SLSA Level 3](https://github.com/Hack23/euparliamentmonitor/attestations) build attestations included.
 
 ## 🎯 Status Badges
@@ -105,9 +109,37 @@ import {
 [![E2E Report](https://img.shields.io/badge/E2E-Report-purple?logo=playwright)](https://euparliamentmonitor.com/playwright-report/index.html)
 [![SLSA 3](https://img.shields.io/badge/SLSA-Level%203-brightgreen?logo=github)](https://github.com/Hack23/euparliamentmonitor/attestations)
 
+## 🌐 Live Site — Explore the Platform
+
+The published platform at **[euparliamentmonitor.com](https://euparliamentmonitor.com)** is the audience-facing companion to this npm package. Two hub pages give the fastest entry into the daily output and the underlying tradecraft:
+
+<table>
+  <tr>
+    <td width="120" align="center" valign="top">
+      <a href="https://euparliamentmonitor.com/political-intelligence.html"><img src="https://img.shields.io/badge/🧠-Political%20Intelligence-003399?style=for-the-badge&logoColor=FFCC00" alt="Political Intelligence Hub"/></a>
+    </td>
+    <td>
+      <strong><a href="https://euparliamentmonitor.com/political-intelligence.html">🧠 Political Intelligence Hub</a></strong><br>
+      Audit-ready transparency layer behind every published article. Indexes the <strong>10-step AI-driven analysis protocol</strong>, the <strong>39 artifact templates</strong>, the per-artifact <strong>methodologies</strong> (BLUF, Admiralty WEP source-grading, SAT, Heuer's ACH, OSINT tradecraft), and links every run-level artifact under <code>analysis/daily/&lt;date&gt;/&lt;slug&gt;/</code> directly to GitHub so readers can <em>verify the analysis behind the prose</em>. Available in all 14 supported languages.
+    </td>
+  </tr>
+  <tr>
+    <td width="120" align="center" valign="top">
+      <a href="https://euparliamentmonitor.com/sitemap.html"><img src="https://img.shields.io/badge/🗺️-Site%20Map-0A66C2?style=for-the-badge&logoColor=FFCC00" alt="Site Map"/></a>
+    </td>
+    <td>
+      <strong><a href="https://euparliamentmonitor.com/sitemap.html">🗺️ Site Map</a></strong><br>
+      Human-readable index of <strong>every page</strong> on the platform — landing pages, news articles, and technical documentation — across all <strong>14 languages</strong> (EN, SV, DA, NO, FI, DE, FR, ES, NL, AR, HE, JA, KO, ZH). Best starting point for SEO crawlers, audience navigation, and discovering the latest articles. Companion to the machine-readable <code>sitemap.xml</code> and per-language <code>sitemap_&lt;lang&gt;.html</code> variants.
+    </td>
+  </tr>
+</table>
+
 ## 📚 Documentation Hub
 
 **📖 Quick Links:**
+- [🌐 Live Site](https://euparliamentmonitor.com) - Public news platform (14 languages, daily AI-generated articles)
+- [🧠 Political Intelligence Hub](https://euparliamentmonitor.com/political-intelligence.html) - Methodology + artifact transparency layer
+- [🗺️ Site Map](https://euparliamentmonitor.com/sitemap.html) - All pages across all 14 languages
 - [📘 Architecture Documentation](SECURITY_ARCHITECTURE.md) - Complete security architecture with C4 diagrams
 - [📗 Security Flows](FLOWCHART.md) - Process flows with security controls
 - [📙 Data Model](DATA_MODEL.md) - Data structures and API integration
@@ -119,7 +151,7 @@ import {
 - [Agent Catalog](.github/agents/README.md) — custom Copilot agents (analysis producers / consumers / gh-aw infrastructure)
 - [Skills Library](.github/skills/README.md) — shared skills (security, compliance, intelligence, gh-aw)
 - [Prompt Library](.github/prompts/README.md) — 10-file bounded-context prompt set (`00`→`09`) + `npm run lint:prompts` drift-guard
-- [Workflows](.github/workflows/README.md) + [WORKFLOWS.md](WORKFLOWS.md) — 10 `news-*.md` agentic workflows + CI workflows
+- [Workflows](.github/workflows/README.md) + [WORKFLOWS.md](WORKFLOWS.md) — 9 `news-*.md` agentic workflows (8 unified `news-<type>.md` + `news-translate.md`) + CI workflows
 - [Analysis Chain](analysis/README.md) — 5-stage pipeline (Data → Analysis → Completeness Gate → Article → Single PR), methodologies, 39 templates, quality thresholds
 
 **🔒 ISMS Compliance:**
@@ -136,11 +168,12 @@ v1.2.13 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)
 - **Agentic Workflows**: 9 unified gh-aw markdown workflows — 8 article types (`news-<type>.md`, Stages A → B → C → D → E in one session) + `news-translate.md` (14-language flush translation) — compiled with
-  `gh-aw v0.69.3` to `.lock.yml` for automated news generation with AI-driven political
+  `gh-aw v0.69.3` (pin in `.github/workflows/compile-agentic-workflows.yml`) to `.lock.yml` for automated news generation with AI-driven political
   intelligence analysis. See [`.github/workflows/README.md`](.github/workflows/README.md).
 - **Analysis-Artifact-Driven Article Pipeline**: Agents author the full
-  Stage-B analysis-artifact set (`analysis/daily/<date>/<slug>-run<NN>/`, 39
-  structured templates per run) and commit it; the deterministic aggregator
+  Stage-B analysis-artifact set (`analysis/daily/<date>/<slug>/`, 39
+  structured templates per run; repeat same-day runs reuse the folder and
+  append to `manifest.json.history[]`) and commit it; the deterministic aggregator
   (`src/aggregator/**`, invoked via
   `npm run generate-article -- --run <analysis-run-dir>` or
   `npm run generate-article:all` for batch regen) then walks `manifest.json`,
@@ -598,6 +631,36 @@ npm run serve
 # Open http://localhost:8080 in your browser
 ```
 
+#### Same-Origin JS Bundle (Mermaid + Chart.js + D3)
+
+The static site loads **every** executable bundle from same-origin
+`js/vendor/` under a strict `script-src 'self'` CSP — no external CDN. Vendored
+libraries are copied from `node_modules/` at build time:
+
+```bash
+npm run copy-vendor    # writes js/vendor/{chart.umd.min.js,d3.min.js,…,mermaid/}
+```
+
+The CI deploy workflow ([`deploy-s3.yml`](.github/workflows/deploy-s3.yml))
+runs `copy-vendor` before `aws s3 sync` and includes both `*.js` and `*.mjs`
+files (Mermaid 11 ships as code-split ESM under `js/vendor/mermaid/chunks/`).
+If you add a new diagram type to a template, no extra wiring is needed — the
+chunk loader is part of the vendored bundle.
+
+#### Stage-C Analysis Validator
+
+Before opening an article PR, validate the analysis run completeness:
+
+```bash
+npm run validate-analysis -- analysis/daily/<date>/<run-dir>
+```
+
+The validator enforces per-artifact line floors, mandatory Mermaid diagrams,
+Admiralty/WEP/SAT/BLUF tradecraft signals, required H2 sections, and
+placeholder leakage. RED output ⇒ Pass-3 the offending artifacts; never ship
+an article without a green gate. See
+[`.github/prompts/03-analysis-completeness-gate.md`](.github/prompts/03-analysis-completeness-gate.md).
+
 ## Project Structure
 
 ```

package/SECURITY.md

@@ -130,7 +130,7 @@ EU Parliament Monitor aligns with:
 
 Current security posture (updated monthly):
 
-- **Zero** known vulnerabilities (npm audit clean)
+- **Zero** known vulnerabilities (npm audit clean) — *except 2 documented accepted-risk transitive devDep advisories: see "Accepted Risks" below*
 - **82%+** code coverage with security tests
 - **100%** dependency scanning coverage
 - **0** CodeQL critical/high findings
@@ -138,6 +138,17 @@ Current security posture (updated monthly):
 
 See [SECURITY_ARCHITECTURE.md - Security Metrics](SECURITY_ARCHITECTURE.md#-security-metrics) for detailed metrics.
 
+### Accepted Risks (Documented False Positives)
+
+The following advisories are detected by `npm audit` and explicitly allow-listed in `.github/workflows/test-and-report.yml` (Security Check job). They are accepted as residual risk because both are dev-only and do not reach end-user runtime:
+
+| GHSA | Package | Severity | Path | Justification |
+| --- | --- | --- | --- | --- |
+| `GHSA-2g4f-4pwh-qvx6` | `ajv` (via ESLint) | moderate (ReDoS) | devDep | ESLint does not invoke ajv with the `$data` option; only triggered on attacker-controlled JSON schemas, which we never feed it. Resolves with the ESLint 10 upgrade. |
+| `GHSA-w5hq-g745-h8pq` | `uuid <14.0.0` (via `mermaid`) | moderate (buffer bounds) | devDep | `mermaid` is a build-time-only dependency. The library is vendored to `js/vendor/mermaid/` and renders diagrams from analyst-authored markdown that goes through the Stage-C completeness gate; user input never reaches `uuid.v3/v5/v6` with an attacker-controlled `buf` argument. The site is fully static — no server-side `mermaid` execution. |
+
+If `npm audit` reports any GHSA outside this list, the Security Check job MUST fail. Allow-listing requires a pull request that updates this table and the workflow allow-list together.
+
 ## Security Resources
 
 - **Threat Model**: [SECURITY_ARCHITECTURE.md - Threat Model](SECURITY_ARCHITECTURE.md#-threat-model)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.8.44",
+  "version": "0.8.46",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",
@@ -60,7 +60,8 @@
     "build": "tsc",
     "build:check": "tsc --noEmit",
     "build:check-tests": "tsc --project tsconfig.test.json --noEmit",
-    "copy-vendor": "mkdir -p js/vendor && cp node_modules/chart.js/dist/chart.umd.min.js js/vendor/ && cp node_modules/chartjs-plugin-annotation/dist/chartjs-plugin-annotation.min.js js/vendor/ && cp node_modules/d3/dist/d3.min.js js/vendor/ && (test -f node_modules/mermaid/dist/mermaid.esm.min.mjs && cp node_modules/mermaid/dist/mermaid.esm.min.mjs js/vendor/ || echo 'mermaid vendor asset not installed; skipping')",
+    "copy-vendor": "node scripts/copy-vendor.js",
+    "validate-analysis": "node scripts/validate-analysis-completeness.js",
     "generate-article": "node scripts/aggregator/article-generator.js",
     "generate-article:all": "node scripts/aggregator/article-generator.js --all",
     "generate-news-indexes": "node scripts/generators/news-indexes.js",
@@ -157,6 +158,7 @@
     "husky": "9.1.7",
     "jscpd": "4.0.9",
     "lint-staged": "16.4.0",
+    "mermaid": "^11.14.0",
     "papaparse": "5.5.3",
     "prettier": "3.8.3",
     "ts-api-utils": "2.5.0",
@@ -169,7 +171,7 @@
     "node": ">=25"
   },
   "dependencies": {
-    "european-parliament-mcp-server": "1.2.13",
+    "european-parliament-mcp-server": "1.2.14",
     "markdown-it": "^14.1.1",
     "markdown-it-anchor": "^9.2.0",
     "markdown-it-attrs": "^4.3.1",

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

@@ -60,6 +60,10 @@ export interface IncludedArtifact {
     /** Id of the section this artifact belongs to. */
     readonly sectionId: string;
 }
+/** Id of the generated reader guide section. */
+export declare const READER_GUIDE_SECTION_ID = "reader-intelligence-guide";
+/** Display title of the generated reader guide section. */
+export declare const READER_GUIDE_SECTION_TITLE = "Reader Intelligence Guide";
 /** Options for {@link aggregateAnalysisRun}. */
 export interface AggregateOptions {
     /** Absolute path to the analysis run directory. */
@@ -153,6 +157,16 @@ export declare function renderTradecraftAppendix(files: readonly string[]): stri
  * @returns Markdown block with the index table
  */
 export declare function renderAnalysisIndex(included: readonly IncludedArtifact[], manifestRelPath: string): string;
+/**
+ * Render the generated reader-intelligence guide that appears before the
+ * artifact sections. It gives readers a Riksdagsmonitor-style navigation layer
+ * without requiring agents to hand-author another artifact.
+ *
+ * @param sections - Emitted section TOC entries, in document order
+ * @param included - Included artifacts, used to name each section's source
+ * @returns Markdown block containing the guide table
+ */
+export declare function renderReaderIntelligenceGuide(sections: readonly TocSection[], included: readonly IncludedArtifact[]): string;
 /**
  * Read, clean, and concatenate every artifact declared by the run's manifest
  * (with discovery fallback when manifest.files is missing), returning a

package/scripts/aggregator/analysis-aggregator.js

@@ -13,6 +13,10 @@ import fs from 'fs';
 import path from 'path';
 import { ARTIFACT_SECTIONS, MANIFEST_SECTION_ID, MANIFEST_SECTION_TITLE, SUPPLEMENTARY_SECTION_ID, SUPPLEMENTARY_SECTION_TITLE, TRADECRAFT_SECTION_ID, TRADECRAFT_SECTION_TITLE, } from './artifact-order.js';
 import { cleanArtifact, githubBlobUrl } from './clean-artifact.js';
+/** Id of the generated reader guide section. */
+export const READER_GUIDE_SECTION_ID = 'reader-intelligence-guide';
+/** Display title of the generated reader guide section. */
+export const READER_GUIDE_SECTION_TITLE = 'Reader Intelligence Guide';
 /**
  * Extract every string entry from a single `files` value (which may be an
  * array of strings or a `path → description` object). Split out so
@@ -92,6 +96,11 @@ 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;
         }
     }
     return out;
@@ -274,6 +283,74 @@ export function renderAnalysisIndex(included, manifestRelPath) {
         '',
     ].join('\n');
 }
+/** Reader-guide copy for high-value intelligence sections. */
+const READER_GUIDE_VALUES = {
+    'section-executive-brief': {
+        need: 'BLUF and editorial decisions',
+        value: 'fast answer to what happened, why it matters, who is accountable, and the next dated trigger',
+    },
+    'section-synthesis': {
+        need: 'Integrated thesis',
+        value: 'the lead political reading that connects facts, actors, risks, and confidence',
+    },
+    'section-significance': {
+        need: 'Significance scoring',
+        value: 'why this story outranks or trails other same-day European Parliament signals',
+    },
+    'section-coalitions-voting': {
+        need: 'Coalitions and voting',
+        value: 'political group alignment, voting evidence, and coalition pressure points',
+    },
+    'section-stakeholder-map': {
+        need: 'Stakeholder impact',
+        value: 'who gains, who loses, and which institutions or citizens feel the policy effect',
+    },
+    'section-economic-context': {
+        need: 'IMF-backed economic context',
+        value: 'macro, fiscal, trade, or monetary evidence that changes the political interpretation',
+    },
+    'section-scenarios': {
+        need: 'Forward indicators',
+        value: 'dated watch items that let readers verify or falsify the assessment later',
+    },
+    'section-risk': {
+        need: 'Risk assessment',
+        value: 'policy, institutional, coalition, communications, and implementation risk register',
+    },
+};
+/**
+ * Render the generated reader-intelligence guide that appears before the
+ * artifact sections. It gives readers a Riksdagsmonitor-style navigation layer
+ * without requiring agents to hand-author another artifact.
+ *
+ * @param sections - Emitted section TOC entries, in document order
+ * @param included - Included artifacts, used to name each section's source
+ * @returns Markdown block containing the guide table
+ */
+export function renderReaderIntelligenceGuide(sections, included) {
+    const rows = sections
+        .map((section) => {
+        const copy = Object.getOwnPropertyDescriptor(READER_GUIDE_VALUES, section.id)?.value;
+        if (!copy)
+            return '';
+        const source = included.find((artifact) => artifact.sectionId === section.id)?.runRelPath;
+        const label = source ? `\`${source}\`` : section.title;
+        return `| [${copy.need}](#${section.id}) | ${copy.value} | ${label} |`;
+    })
+        .filter(Boolean);
+    if (rows.length === 0)
+        return '';
+    return [
+        `<h2 id="${READER_GUIDE_SECTION_ID}">${READER_GUIDE_SECTION_TITLE}</h2>`,
+        '',
+        'Use this guide to read the article as a political-intelligence product rather than a raw artifact dump. High-value reader lenses appear first; technical provenance remains available in the audit appendices.',
+        '',
+        "| Reader need | What you'll get | Source artifact |",
+        '|---|---|---|',
+        ...rows,
+        '',
+    ].join('\n');
+}
 /**
  * Read a single artifact, clean it, and return the Markdown lines that
  * should be appended to the aggregated document along with the provenance
@@ -455,8 +532,12 @@ export function aggregateAnalysisRun(options) {
     });
     const tradecraft = renderTradecraftAppendix(tradecraftFiles);
     const analysisIndex = renderAnalysisIndex(includedArtifacts, manifestRelPath);
+    const readerGuide = renderReaderIntelligenceGuide(emittedSections, includedArtifacts);
     // Both appendices emit their own <h2 id="…"> blocks — record them so the
     // article TOC mirrors the rendered document in document order.
+    if (readerGuide) {
+        emittedSections.unshift({ id: READER_GUIDE_SECTION_ID, title: READER_GUIDE_SECTION_TITLE });
+    }
     emittedSections.push({ id: TRADECRAFT_SECTION_ID, title: TRADECRAFT_SECTION_TITLE });
     emittedSections.push({ id: MANIFEST_SECTION_ID, title: MANIFEST_SECTION_TITLE });
     const markdown = [
@@ -464,6 +545,8 @@ export function aggregateAnalysisRun(options) {
         '',
         provenance,
         '',
+        readerGuide,
+        '',
         ...sectionMarkdown,
         '',
         tradecraft,

package/scripts/aggregator/article-generator.js

@@ -261,6 +261,46 @@ export function extractDefaultDescription(markdown) {
     const strong = extractStrongProseLine(markdown);
     return strong.length > 0 ? strong : FALLBACK_DESCRIPTION;
 }
+/**
+ * Escape a string for a conservative double-quoted YAML scalar.
+ *
+ * @param value - Raw metadata value
+ * @returns YAML-safe quoted string content (without surrounding quotes)
+ */
+function yamlEscape(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, ' ');
+}
+/**
+ * Build the Jekyll-compatible Markdown source committed as `article.md`.
+ * The renderer strips this front matter before HTML conversion, while the
+ * source file stays portable to Jekyll/GitHub Pages and aligned with the
+ * Riksdagsmonitor article contract.
+ *
+ * @param aggregated - Aggregated analysis body and run metadata
+ * @param metadata - English metadata resolved for SEO
+ * @param metadata.title - Resolved English article title
+ * @param metadata.description - Resolved English article description
+ * @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 frontMatter = [
+        '---',
+        `title: "${yamlEscape(metadata.title)}"`,
+        `description: "${yamlEscape(metadata.description)}"`,
+        `date: ${aggregated.date}`,
+        `article_type: ${aggregated.articleType}`,
+        `slug: ${slug}`,
+        `source_folder: ${sourceFolder}`,
+        `generated_at: ${aggregated.date}T00:00:00.000Z`,
+        'language: en',
+        'layout: article',
+        '---',
+        '',
+    ].join('\n');
+    return `${frontMatter}${aggregated.markdown}`;
+}
 /**
  * Render a single language-variant article. Pulls from a pre-translated
  * `<slug>.<lang>.md` file when it exists, otherwise renders the English
@@ -397,13 +437,15 @@ export function generateArticle(opts, runSuffix, articleCountOverride) {
     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, aggregated.markdown, 'utf8');
+    fs.writeFileSync(runArticleMdAbs, sourceMarkdown, 'utf8');
     const runArticleMdRelPath = path
         .relative(opts.repoRoot, runArticleMdAbs)
         .split(path.sep)
@@ -413,10 +455,10 @@ export function generateArticle(opts, runSuffix, articleCountOverride) {
     ensureDir(opts.outDir);
     const sourceMdFilename = `${slug}.en.md`;
     const sourceMdAbs = path.join(opts.outDir, sourceMdFilename);
-    fs.writeFileSync(sourceMdAbs, aggregated.markdown, 'utf8');
+    fs.writeFileSync(sourceMdAbs, sourceMarkdown, 'utf8');
     const written = [sourceMdFilename];
     if (!opts.markdownOnly) {
-        const rendered = renderMarkdown(aggregated.markdown);
+        const rendered = renderMarkdown(sourceMarkdown);
         const chromeOptions = {
             metadata: effectiveMetadata,
             // Point the "View source Markdown" link at the canonical run-directory

package/scripts/aggregator/article-html.js

@@ -181,7 +181,6 @@ ${hreflangLinks}
   <meta name="theme-color" content="#003399">
   <link rel="stylesheet" href="../styles.css">
   <script type="application/ld+json">${jsonLdString}</script>
-  <script type="module" src="../js/vendor/mermaid.esm.min.mjs" defer></script>
   <script type="module" src="../js/mermaid-init.js" defer></script>
 </head>
 <body>
@@ -208,6 +207,12 @@ ${hreflangLinks}
 
   <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>
+        <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>
+      </header>
       ${sourceMdLink}
       ${options.body}
     </article>

package/scripts/aggregator/artifact-order.js

@@ -12,7 +12,7 @@ export const ARTIFACT_SECTIONS = [
     {
         id: 'executive-brief',
         title: 'Executive Brief',
-        artifacts: ['extended/executive-brief.md'],
+        artifacts: ['executive-brief.md', 'extended/executive-brief.md'],
     },
     {
         id: 'synthesis',

package/scripts/aggregator/markdown-renderer.d.ts

@@ -51,6 +51,15 @@ export interface TocEntry {
  *          deflist, mermaid fence override, and table wrapping installed
  */
 export declare function buildMarkdownIt(): MarkdownIt;
+/**
+ * Strip a leading YAML front matter block from a Markdown document. Generated
+ * `article.md` files are Jekyll-compatible, but the deterministic HTML
+ * renderer must render the body, not the metadata fence.
+ *
+ * @param markdown - Markdown with optional `---` front matter at byte 0
+ * @returns Markdown body with the front matter removed
+ */
+export declare function stripMarkdownFrontMatter(markdown: string): string;
 /**
  * Slugify a heading text into a stable URL fragment.
  *

package/scripts/aggregator/markdown-renderer.js

@@ -47,6 +47,22 @@ export function buildMarkdownIt() {
     installTableWrapper(md);
     return md;
 }
+/**
+ * Strip a leading YAML front matter block from a Markdown document. Generated
+ * `article.md` files are Jekyll-compatible, but the deterministic HTML
+ * renderer must render the body, not the metadata fence.
+ *
+ * @param markdown - Markdown with optional `---` front matter at byte 0
+ * @returns Markdown body with the front matter removed
+ */
+export function stripMarkdownFrontMatter(markdown) {
+    if (!markdown.startsWith('---\n'))
+        return markdown;
+    const end = markdown.indexOf('\n---\n', 4);
+    if (end === -1)
+        return markdown;
+    return markdown.slice(end + 5).replace(/^\n+/, '');
+}
 /**
  * Slugify a heading text into a stable URL fragment.
  *
@@ -122,7 +138,7 @@ export function renderMarkdown(markdown, options = {}) {
     const env = {};
     if (options.mermaidLabel)
         env.mermaidLabel = options.mermaidLabel;
-    const tokens = md.parse(markdown, env);
+    const tokens = md.parse(stripMarkdownFrontMatter(markdown), env);
     const toc = harvestToc(tokens);
     const html = md.renderer.render(tokens, md.options, env);
     const mermaidCount = countMermaidTokens(tokens);

package/scripts/copy-vendor.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: 2024-2026 Hack23 AB
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Copy vendored JS libraries from `node_modules/` into `js/vendor/` so the
+ * static site can serve every executable bundle from the same origin
+ * (S3 + CloudFront) under the strict `script-src 'self'` CSP. No external
+ * CDN is allowed (per the EU Parliament Monitor deployment contract).
+ *
+ * Vendored libraries:
+ *   - chart.js                 → js/vendor/chart.umd.min.js
+ *   - chartjs-plugin-annotation → js/vendor/chartjs-plugin-annotation.min.js
+ *   - d3                        → js/vendor/d3.min.js
+ *   - mermaid                   → js/vendor/mermaid/  (entry + chunks/)
+ *
+ * Mermaid is special: v11+ ships as code-split ESM. The entry
+ * `mermaid.esm.min.mjs` does dynamic `import()` on diagram-specific chunks
+ * under `dist/chunks/mermaid.esm.min/*.mjs`. To make every diagram type render
+ * without external network calls, we copy the **entire mermaid `dist/`
+ * directory** (filtered to the `.esm.min` flavour to keep payload small).
+ *
+ * Idempotent: rerunning overwrites prior copies and leaves licenses in place.
+ *
+ * Failure modes:
+ *   - Missing chart.js / d3 / chartjs-plugin-annotation → hard error (these
+ *     are pinned `devDependencies` and must always be present after `npm ci`).
+ *   - Missing mermaid → soft error (logged, exit 0). Mermaid is also a pinned
+ *     `devDependency`, but optional installs (e.g. `npm ci --omit=dev`) may
+ *     skip it; we want the deploy to succeed without diagrams rather than fail.
+ */
+
+import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const ROOT = process.cwd();
+const NODE_MODULES = path.join(ROOT, 'node_modules');
+const VENDOR_DIR = path.join(ROOT, 'js', 'vendor');
+
+function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true });
+}
+
+function writeLicense(targetPath, copyrightText, licenseId) {
+  // REUSE-compliant sidecar — see REUSE.toml for path-level annotations.
+  writeFileSync(
+    `${targetPath}.license`,
+    `SPDX-FileCopyrightText: ${copyrightText}\nSPDX-License-Identifier: ${licenseId}\n`,
+    'utf8',
+  );
+}
+
+function copyOrFail(label, srcRel, dstRel, license) {
+  const src = path.join(NODE_MODULES, srcRel);
+  const dst = path.join(VENDOR_DIR, dstRel);
+  if (!existsSync(src)) {
+    process.stderr.write(`error: ${label} not installed at ${srcRel}\n`);
+    process.exit(1);
+  }
+  ensureDir(path.dirname(dst));
+  copyFileSync(src, dst);
+  writeLicense(dst, license.copyright, license.spdx);
+  process.stdout.write(`  ✓ ${dstRel}\n`);
+}
+
+function copyMermaid() {
+  const mermaidDist = path.join(NODE_MODULES, 'mermaid', 'dist');
+  const target = path.join(VENDOR_DIR, 'mermaid');
+  if (!existsSync(mermaidDist)) {
+    process.stdout.write(
+      '  ⚠ mermaid not installed (devDependency); skipping diagram bundle.\n',
+    );
+    return;
+  }
+  // Idempotency: wipe the existing mermaid tree before copying so stale
+  // chunks from a previous mermaid version (or a previous filter set) cannot
+  // leak into the deployed bundle. cpSync({force:true}) only overwrites
+  // matching paths; it does not remove orphans.
+  if (existsSync(target)) {
+    rmSync(target, { recursive: true, force: true });
+  }
+  ensureDir(target);
+
+  // Copy the minified ESM entry plus its chunk directory. Skip the dev /
+  // unminified flavours (`mermaid.esm.mjs`, `mermaid.core.mjs`,
+  // `mermaid.js`, etc.) AND skip sourcemaps to keep the deployed payload
+  // small (saves ~6 MB and 60+ HTTP requests).
+  const wantedTopLevel = new Set(['mermaid.esm.min.mjs']);
+
+  cpSync(mermaidDist, target, {
+    recursive: true,
+    force: true,
+    filter: (src) => {
+      const rel = path.relative(mermaidDist, src);
+      if (rel === '') return true; // root dist dir
+      // Skip sourcemaps — we deploy minified-only.
+      if (src.endsWith('.map')) return false;
+      const segments = rel.split(path.sep);
+      const top = segments[0];
+      // Always allow the chunks directory tree we need.
+      if (top === 'chunks') {
+        if (segments.length === 1) return true;
+        const flavour = segments[1];
+        return flavour === 'mermaid.esm.min';
+      }
+      // Top-level: only allow the minified ESM entry.
+      if (segments.length === 1) {
+        return wantedTopLevel.has(top);
+      }
+      return false;
+    },
+  });
+
+  // REUSE sidecar for the entry file + flavour directory.
+  const entry = path.join(target, 'mermaid.esm.min.mjs');
+  if (existsSync(entry)) {
+    writeLicense(entry, '2014-2026 Mermaid contributors', 'MIT');
+  }
+  // Also drop a license file at the chunks dir so REUSE lint passes for the
+  // generated tree without us having to enumerate every chunk by name.
+  const chunksDir = path.join(target, 'chunks', 'mermaid.esm.min');
+  if (existsSync(chunksDir)) {
+    writeFileSync(
+      path.join(target, 'chunks', 'mermaid.esm.min.license'),
+      'SPDX-FileCopyrightText: 2014-2026 Mermaid contributors\nSPDX-License-Identifier: MIT\n',
+      'utf8',
+    );
+  }
+  process.stdout.write(`  ✓ mermaid/ (entry + ${countMjs(target)} mjs chunks)\n`);
+}
+
+function countMjs(dir) {
+  let n = 0;
+  function walk(d) {
+    if (!existsSync(d)) return;
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, entry.name);
+      if (entry.isDirectory()) walk(p);
+      else if (entry.isFile() && entry.name.endsWith('.mjs')) n += 1;
+    }
+  }
+  walk(dir);
+  return n;
+}
+
+function main() {
+  ensureDir(VENDOR_DIR);
+  process.stdout.write(`Copying vendor JS libraries to ${path.relative(ROOT, VENDOR_DIR)}/\n`);
+
+  copyOrFail(
+    'chart.js',
+    'chart.js/dist/chart.umd.min.js',
+    'chart.umd.min.js',
+    { copyright: '2014-2024 Chart.js Contributors', spdx: 'MIT' },
+  );
+  copyOrFail(
+    'chartjs-plugin-annotation',
+    'chartjs-plugin-annotation/dist/chartjs-plugin-annotation.min.js',
+    'chartjs-plugin-annotation.min.js',
+    { copyright: '2016-2024 chartjs-plugin-annotation contributors', spdx: 'MIT' },
+  );
+  copyOrFail(
+    'd3',
+    'd3/dist/d3.min.js',
+    'd3.min.js',
+    { copyright: '2010-2024 Mike Bostock', spdx: 'ISC' },
+  );
+
+  copyMermaid();
+
+  process.stdout.write('✅ Vendor copy complete.\n');
+}
+
+main();