euparliamentmonitor 0.8.43 → 0.8.45

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.43",
+  "version": "0.8.45",
   "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
@@ -165,4 +179,13 @@ export declare function renderAnalysisIndex(included: readonly IncludedArtifact[
  * @returns {@link AggregatedRun} describing the rendered document
  */
 export declare function aggregateAnalysisRun(options: AggregateOptions): AggregatedRun;
+/**
+ * Extract a `YYYY-MM-DD` date from a path like
+ * `analysis/daily/2026-01-15/run`. Falls back to the epoch date when no
+ * ISO date is embedded in the path.
+ *
+ * @param runDirRelPath - Repo-relative path of the run directory
+ * @returns ISO date string in `YYYY-MM-DD` form
+ */
+export declare function guessDateFromRunDir(runDirRelPath: string): string;
 //# sourceMappingURL=analysis-aggregator.d.ts.map

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;
@@ -119,6 +128,24 @@ export function discoverTradecraftFiles(repoRoot) {
     }
     return result.sort();
 }
+/**
+ * Return `true` when a `.md` filename should be excluded from the run
+ * artifact set. Keeps the walk closure under the cognitive-complexity limit.
+ *
+ * Excluded names:
+ *  - `article.md` and translated variants (`article.sv.md`, etc.) — these are
+ *    outputs of the aggregator, not inputs.
+ *  - `README.md` (case-insensitive) — required for the analysis gate but not
+ *    relevant to the published article.
+ *
+ * @param name - Bare filename (no directory prefix)
+ * @returns `true` when the file should be skipped
+ */
+function isExcludedArtifact(name) {
+    if (name.toLowerCase() === 'readme.md')
+        return true;
+    return name.startsWith('article.') && name.endsWith('.md');
+}
 /**
  * Walk the run directory and return every `.md` file as a run-relative
  * POSIX path, excluding files under `data/` (raw MCP payloads, not meant
@@ -137,11 +164,13 @@ function collectRunArtifacts(runDir) {
             const full = path.join(dir, entry.name);
             const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
             if (entry.isDirectory()) {
-                if (entry.name === 'data' || entry.name === 'runs')
+                // Skip raw payloads, legacy 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);
             }
-            else if (entry.isFile() && entry.name.endsWith('.md')) {
+            else if (entry.isFile() && entry.name.endsWith('.md') && !isExcludedArtifact(entry.name)) {
                 result.push(rel);
             }
         }
@@ -254,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
@@ -435,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 = [
@@ -444,6 +545,8 @@ export function aggregateAnalysisRun(options) {
         '',
         provenance,
         '',
+        readerGuide,
+        '',
         ...sectionMarkdown,
         '',
         tradecraft,
@@ -471,7 +574,7 @@ export function aggregateAnalysisRun(options) {
  * @param runDirRelPath - Repo-relative path of the run directory
  * @returns ISO date string in `YYYY-MM-DD` form
  */
-function guessDateFromRunDir(runDirRelPath) {
+export function guessDateFromRunDir(runDirRelPath) {
     const match = /(\d{4}-\d{2}-\d{2})/.exec(runDirRelPath);
     return match ? (match[1] ?? '1970-01-01') : '1970-01-01';
 }

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

@@ -38,6 +38,12 @@ export interface CliOptions {
 export interface GenerateResult {
     /** Repo-relative path of the English source Markdown that was written. */
     readonly sourceMarkdownRelPath: string;
+    /**
+     * Repo-relative path of the `article.md` written directly into the
+     * analysis run directory — canonical Markdown source that lives alongside
+     * the artifacts that produced it (riksdagsmonitor pattern).
+     */
+    readonly runArticleMdRelPath: string;
     /** Filenames written under `outDir`, relative to `outDir`. */
     readonly writtenFiles: readonly string[];
     /** Metadata from {@link aggregateAnalysisRun}. */

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
@@ -310,6 +350,7 @@ function writeLanguageVariant(lang, slug, aggregated, englishHtml, chromeOptions
         sourceMarkdownRelPath: chromeOptions.sourceMarkdownRelPath,
         toc: aggregated.sectionToc,
         articleCount: chromeOptions.articleCount,
+        isBasedOn: aggregated.includedArtifacts.map((a) => `https://github.com/Hack23/euparliamentmonitor/blob/main/${a.repoRelPath}`),
     });
     const filename = getArticleFilename(slug, lang);
     fs.writeFileSync(path.join(opts.outDir, filename), html, 'utf8');
@@ -396,18 +437,33 @@ export function generateArticle(opts, runSuffix, articleCountOverride) {
     const effectiveMetadata = opts.title || opts.description
         ? applyCliOverrides(resolvedMetadata, opts.title, opts.description)
         : resolvedMetadata;
-    // Write source Markdown under <outDir>/<slug>.en.md for transparency.
+    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('/');
+    // 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);
-    fs.writeFileSync(sourceMdAbs, aggregated.markdown, 'utf8');
-    const sourceMdRelPath = path.relative(opts.repoRoot, sourceMdAbs).split(path.sep).join('/');
+    fs.writeFileSync(sourceMdAbs, sourceMarkdown, 'utf8');
     const written = [sourceMdFilename];
     if (!opts.markdownOnly) {
-        const rendered = renderMarkdown(aggregated.markdown);
+        const rendered = renderMarkdown(sourceMarkdown);
         const chromeOptions = {
             metadata: effectiveMetadata,
-            sourceMarkdownRelPath: sourceMdRelPath,
+            // 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),
         };
         for (const lang of opts.langs) {
@@ -415,7 +471,12 @@ export function generateArticle(opts, runSuffix, articleCountOverride) {
             written.push(filename);
         }
     }
-    return { sourceMarkdownRelPath: sourceMdRelPath, writtenFiles: written, aggregated };
+    return {
+        sourceMarkdownRelPath: runArticleMdRelPath,
+        runArticleMdRelPath,
+        writtenFiles: written,
+        aggregated,
+    };
 }
 /**
  * Walk `analysis/daily/` recursively and return every subdirectory that

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

@@ -44,6 +44,11 @@ export interface WrapArticleOptions {
      * the line is omitted.
      */
     readonly articleCount?: number;
+    /**
+     * Optional: URLs of source artifacts included in the aggregated article.
+     * Emitted as `isBasedOn` in the JSON-LD `NewsArticle` schema for provenance.
+     */
+    readonly isBasedOn?: readonly string[];
 }
 /**
  * Build the canonical filename for an article in a given language. English

package/scripts/aggregator/article-html.js

@@ -134,6 +134,11 @@ export function wrapArticleHtml(options) {
             name: 'EU Parliament Monitor',
             url: BASE_URL,
         },
+        ...(options.isBasedOn && options.isBasedOn.length > 0
+            ? {
+                isBasedOn: options.isBasedOn.map((url) => ({ '@type': 'CreativeWork', url })),
+            }
+            : {}),
     };
     const jsonLdString = JSON.stringify(jsonLd).replace(/</g, '\\u003c');
     const pageTitle = `${options.title} — ${siteTitle}`;
@@ -176,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>
@@ -203,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/clean-artifact.d.ts

@@ -35,6 +35,8 @@ export interface CleanArtifactResult {
     readonly strippedH1s: number;
     /** Banner/metadata lines removed. */
     readonly strippedBannerLines: number;
+    /** Operational metadata preamble lines removed (e.g. **Run:** / **Window:** blocks). */
+    readonly strippedMetaLines: number;
     /** Mermaid blocks deduplicated as a reference to a previous occurrence. */
     readonly dedupedMermaidBlocks: number;
 }
@@ -126,6 +128,28 @@ export declare function dedupMermaid(md: string, seen: Set<string>): {
     md: string;
     deduped: number;
 };
+/**
+ * Strip the operational metadata preamble that agent pipelines prepend to
+ * artifacts. These are lines of the form `**Run:** …`, `**Window:** …`,
+ * `**Methodology:** …`, etc., followed optionally by a standalone `---`
+ * horizontal rule. They are agent-operational metadata that should not appear
+ * in the published article.
+ *
+ * Algorithm:
+ *  1. Skip leading blank lines (they don't count as metadata).
+ *  2. If the first non-blank line does NOT match the metadata pattern, return
+ *     the document unchanged (`lines: 0`).
+ *  3. Otherwise consume all metadata lines and interspersed blank lines.
+ *  4. If the next non-blank line is a standalone `---`, consume that too.
+ *  5. Return the stripped Markdown and the count of lines removed.
+ *
+ * @param md - Markdown source (after banner/heading passes)
+ * @returns `{ md, lines }` — stripped Markdown and number of lines removed
+ */
+export declare function stripArtifactMetadataPreamble(md: string): {
+    md: string;
+    lines: number;
+};
 /**
  * Apply all cleanup passes and return the normalised Markdown plus
  * simple counters for telemetry/tests.