euparliamentmonitor 0.8.53 → 0.8.55

package/README.md

@@ -55,7 +55,7 @@ This repository is the open-source platform behind **[euparliamentmonitor.com](h
 | 🧠 **Political Intelligence** | Structured analytic techniques (ACH, SWOT/TOWS, PESTLE, scenario forecasting, devil's-advocate), Admiralty source grading, Words of Estimative Probability (WEP) bands, ICD-203 standards, and a 6-dimension political-threat framework — applied daily to live EP data. |
 | 🔍 **Radical Transparency** | Every article links back to the analysis run it was rendered from. Every artifact links to its methodology. Every methodology is published. No black box. |
 | 🗳️ **Democratic Accountability** | Public-data only. GDPR-clean. No personal profiling. Multi-language so a Finnish farmer, a Greek student, and a Polish journalist all get the same intelligence in their own language. |
-| 🤖 **AI-Generated News** | 8 unified gh-aw agentic workflows + 1 translation workflow run autonomously, produce structured analysis, render deterministic HTML, and open publication-ready pull requests for human review. |
+| 🤖 **AI-Generated News** | 14 unified gh-aw agentic workflows + 1 translation workflow run autonomously, produce structured analysis, render deterministic HTML, and open publication-ready pull requests for human review. |
 
 ### Documentation & Reports
 [![API Docs](https://img.shields.io/badge/API-Documentation-blue?logo=javascript)](https://euparliamentmonitor.com/docs/api/)
@@ -124,7 +124,7 @@ The published site is the audience-facing companion to this npm/TypeScript packa
 - [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) — 9 `news-*.md` agentic workflows (8 unified `news-<type>.md` + `news-translate.md`) + CI workflows
+- [Workflows](.github/workflows/README.md) + [WORKFLOWS.md](WORKFLOWS.md) — 15 `news-*.md` agentic workflows (14 unified `news-<type>.md` covering 14 article types — including the long-horizon `quarter-ahead`/`quarter-in-review`/`year-ahead`/`year-in-review`/`term-outlook`/`election-cycle` set added in 2026-Q2 — plus `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 +136,11 @@ The published site is the audience-facing companion to this npm/TypeScript packa
 
 **MCP Server Integration**: The project uses the
 [European-Parliament-MCP-Server](https://github.com/Hack23/European-Parliament-MCP-Server)
-v1.2.19 for accessing real EU Parliament data via the Model Context Protocol.
+v1.2.20 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
+- **Agentic Workflows**: 15 unified gh-aw markdown workflows — 14 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` (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
@@ -338,21 +338,27 @@ flowchart LR
 
 ## 📰 Live News Streams
 
-**Eight unified gh-aw article workflows** plus a **14-language translation helper** run on precision schedules, autonomously generating *Economist-style* political intelligence and opening publication-ready pull requests. Every workflow follows the same Stage A → E contract documented in [Article-Generation.md](Article-Generation.md).
+**Fourteen unified gh-aw article workflows** plus a **14-language translation helper** run on precision schedules, autonomously generating *Economist-style* political intelligence and opening publication-ready pull requests. Every workflow follows the same Stage A → E contract documented in [Article-Generation.md](Article-Generation.md). The single source of truth for every horizon's data window, cadence, mandatory artifacts, stage budgets, scenario depth and electoral overlay is the [`ARTICLE_HORIZONS` registry in `src/config/article-horizons.ts`](src/config/article-horizons.ts).
 
 | Workflow | Article Type | Focus |
 |----------|--------------|-------|
 | 🚨 **[news-breaking.md](.github/workflows/news-breaking.md)** | `breaking` | Rapid-response coverage of significant EP developments. |
 | 📋 **[news-week-ahead.md](.github/workflows/news-week-ahead.md)** | `week-ahead` | Forward calendar, committee agenda, urgency-file outlook. |
 | 🔭 **[news-month-ahead.md](.github/workflows/news-month-ahead.md)** | `month-ahead` | 30-day strategic horizon and risk forecast. |
+| 🌐 **[news-quarter-ahead.md](.github/workflows/news-quarter-ahead.md)** | `quarter-ahead` | 90-day legislative pipeline forecast + presidency-trio overlay. |
+| 🛰️ **[news-year-ahead.md](.github/workflows/news-year-ahead.md)** | `year-ahead` | 12-month strategic outlook with seat-projection sensitivity. |
+| 🗓️ **[news-term-outlook.md](.github/workflows/news-term-outlook.md)** | `term-outlook` | Full EP-term outlook anchored to the next-EP-election week. |
+| 🗳️ **[news-election-cycle.md](.github/workflows/news-election-cycle.md)** | `election-cycle` | EP-election span (±6 mo) — mandate scorecard + seat projection + Spitzenkandidaten arithmetic. |
 | 📊 **[news-week-in-review.md](.github/workflows/news-week-in-review.md)** | `week-in-review` | Past-week retrospective intelligence (D-8 → D-36 reporting window). |
 | 📈 **[news-month-in-review.md](.github/workflows/news-month-in-review.md)** | `month-in-review` | Monthly retrospective with cross-run continuity analysis. |
+| 📚 **[news-quarter-in-review.md](.github/workflows/news-quarter-in-review.md)** | `quarter-in-review` | Quarterly retrospective with pipeline transit + presidency-trio overlay. |
+| 📜 **[news-year-in-review.md](.github/workflows/news-year-in-review.md)** | `year-in-review` | Annual retrospective with mandate-fulfilment + term-arc + historical parallels. |
 | 🏛️ **[news-committee-reports.md](.github/workflows/news-committee-reports.md)** | `committee-reports` | Committee activity, rapporteur work, legislative-production analysis. |
 | ⚖️ **[news-motions.md](.github/workflows/news-motions.md)** | `motions` | Plenary motions, resolutions, urgency files, political signals. |
 | 📜 **[news-propositions.md](.github/workflows/news-propositions.md)** | `propositions` | Legislative proposals and pipeline analysis. |
 | 🌍 **[news-translate.md](.github/workflows/news-translate.md)** | translation helper | 14-language flush translation (manual dispatch only). |
 
-Each unified workflow runs Stages A–E **in a single 45-minute session** and produces exactly one PR containing both the analysis artifacts and the rendered HTML. The earlier split-pair `news-<type>-analysis.md` + `news-<type>-article.md` layout was retired in the April-2026 aggregator migration. See **[.github/workflows/README.md](.github/workflows/README.md)** for compile / lock-file / safe-output mechanics, and **[WORKFLOWS.md](WORKFLOWS.md)** for the full CI/CD catalog.
+Each unified workflow runs Stages A–E **in a single 60-minute session** (`engine.mcp.session-timeout: 65m`) and produces exactly one PR containing both the analysis artifacts and the rendered HTML. The earlier split-pair `news-<type>-analysis.md` + `news-<type>-article.md` layout was retired in the April-2026 aggregator migration. See **[.github/workflows/README.md](.github/workflows/README.md)** for compile / lock-file / safe-output mechanics, **[WORKFLOWS.md](WORKFLOWS.md)** for the full CI/CD catalog, and **[Article-Generation.md § Forward-looking horizons & election cycle](Article-Generation.md)** for the new long-horizon and electoral pipeline.
 
 > 📚 **Prompt Library (`.github/prompts/`)** — 10 bounded-context prompt files (`00-scope-and-ground-rules.md` → `09-troubleshooting.md`) shared across every workflow. The `npm run lint:prompts` drift-guard fails CI on banned patterns (`checkpoint pr`, `keep-alive`, `heartbeat`, `progressive safe output`, `push_repo_memory`).
 
@@ -426,7 +432,7 @@ import type { ArticleCategory, LanguageCode } from 'euparliamentmonitor/types';
 
 ## 🔌 Data Sources
 
-**Primary — European Parliament MCP Server** ([Hack23/European-Parliament-MCP-Server](https://github.com/Hack23/European-Parliament-MCP-Server) v1.2.19+, fully operational):
+**Primary — European Parliament MCP Server** ([Hack23/European-Parliament-MCP-Server](https://github.com/Hack23/European-Parliament-MCP-Server) v1.2.20+, fully operational):
 
 - 🗳️ Plenary sessions, voting records, roll-call votes
 - 📜 Adopted texts, motions, resolutions, urgency files
@@ -560,7 +566,7 @@ Six-phase roadmap from current agentic news generation to AGI-enhanced transform
 timeline
     title EU Parliament Monitor — AI Evolution Roadmap
     section Phase 1 (2026)
-        Agentic News : 8 unified workflows
+        Agentic News : 14 unified workflows
                      : 14-language generation
                      : Deterministic aggregator
                      : 51-artifact analysis catalog

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.8.53",
+  "version": "0.8.55",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",
@@ -55,6 +55,8 @@
     "build:check-tests": "tsc --project tsconfig.test.json --noEmit",
     "copy-vendor": "node scripts/copy-vendor.js",
     "validate-analysis": "node scripts/validate-analysis-completeness.js",
+    "sync:templates": "node scripts/templates/sync-template-frontmatter.js",
+    "sync:templates:check": "node scripts/templates/sync-template-frontmatter.js --check",
     "prior-run-diff": "node scripts/aggregator/prior-run-diff.js",
     "generate-article": "node scripts/aggregator/article-generator.js",
     "generate-article:all": "node scripts/aggregator/article-generator.js --all",
@@ -169,7 +171,7 @@
     "node": ">=25"
   },
   "dependencies": {
-    "european-parliament-mcp-server": "1.2.19",
+    "european-parliament-mcp-server": "1.2.20",
     "markdown-it": "^14.1.1",
     "markdown-it-anchor": "^9.2.0",
     "markdown-it-attrs": "^4.3.1",

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

@@ -1,5 +1,8 @@
 import { type ArtifactSection } from './artifact-order.js';
 import { type Manifest, type ManifestFiles } from './manifest/index.js';
+import type { TocSection, IncludedArtifact } from './reader-guide-constants.js';
+export type { TocSection, IncludedArtifact } from './reader-guide-constants.js';
+export { READER_GUIDE_SECTION_ID, READER_GUIDE_SECTION_IDS, READER_GUIDE_SECTION_TITLE, } from './reader-guide-constants.js';
 /** Result of {@link aggregateAnalysisRun}. */
 export interface AggregatedRun {
     /** Final Markdown document (provenance + sections + appendices). */
@@ -23,26 +26,6 @@ export interface AggregatedRun {
      */
     readonly sectionToc: readonly TocSection[];
 }
-/** One entry in the article-level table of contents (H2 level). */
-export interface TocSection {
-    /** Fragment identifier — matches the `id="…"` on the rendered H2. */
-    readonly id: string;
-    /** Display title shown in the sidebar nav. */
-    readonly title: string;
-}
-/** Metadata for one artifact included in the aggregate. */
-export interface IncludedArtifact {
-    /** Path relative to the run dir. */
-    readonly runRelPath: string;
-    /** Path relative to the repo root. */
-    readonly repoRelPath: string;
-    /** 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. */
@@ -146,6 +129,10 @@ export declare function renderAnalysisIndex(included: readonly IncludedArtifact[
  * artifact sections. It gives readers a Riksdagsmonitor-style navigation layer
  * without requiring agents to hand-author another artifact.
  *
+ * Section membership is checked against `READER_GUIDE_SECTION_IDS` (the
+ * canonical list shared with the HTML renderer in `reader-intelligence-guide.ts`)
+ * to prevent drift between the two renderers.
+ *
  * @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

package/scripts/aggregator/analysis-aggregator.js

@@ -14,11 +14,10 @@ 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';
 import { treeUrl } from './infra/github-urls.js';
+import { buildKeyTakeaways, KEY_TAKEAWAYS_SECTION_ID, KEY_TAKEAWAYS_SECTION_TITLE, } from './key-takeaways.js';
 import { flattenManifestFiles as _flattenManifestFiles, latestGateResult as _latestGateResult, resolveArticleType as _resolveArticleType, resolveRunId as _resolveRunId, } from './manifest/index.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';
+import { READER_GUIDE_SECTION_ID, READER_GUIDE_SECTION_IDS, READER_GUIDE_SECTION_TITLE, } from './reader-guide-constants.js';
+export { READER_GUIDE_SECTION_ID, READER_GUIDE_SECTION_IDS, READER_GUIDE_SECTION_TITLE, } from './reader-guide-constants.js';
 /**
  * Normalise `manifest.files` into a flat list of `runRelPath` strings.
  *
@@ -258,8 +257,13 @@ export function renderAnalysisIndex(included, manifestRelPath) {
         '',
     ].join('\n');
 }
-/** Reader-guide copy for high-value intelligence sections. */
-const READER_GUIDE_VALUES = {
+/**
+ * English-only reader-guide copy for the Markdown guide embedded in the
+ * aggregated source document. Section membership is gated by
+ * `READER_GUIDE_SECTION_IDS` (imported from `reader-guide-constants.ts`)
+ * so both renderers stay in sync automatically.
+ */
+const READER_GUIDE_EN = {
     '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',
@@ -298,6 +302,10 @@ const READER_GUIDE_VALUES = {
  * artifact sections. It gives readers a Riksdagsmonitor-style navigation layer
  * without requiring agents to hand-author another artifact.
  *
+ * Section membership is checked against `READER_GUIDE_SECTION_IDS` (the
+ * canonical list shared with the HTML renderer in `reader-intelligence-guide.ts`)
+ * to prevent drift between the two renderers.
+ *
  * @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
@@ -305,7 +313,10 @@ const READER_GUIDE_VALUES = {
 export function renderReaderIntelligenceGuide(sections, included) {
     const rows = sections
         .map((section) => {
-        const copy = Object.getOwnPropertyDescriptor(READER_GUIDE_VALUES, section.id)?.value;
+        // Guard: only include sections whose IDs are in the canonical list
+        if (!READER_GUIDE_SECTION_IDS.includes(section.id))
+            return '';
+        const copy = Object.getOwnPropertyDescriptor(READER_GUIDE_EN, section.id)?.value;
         if (!copy)
             return '';
         const source = included.find((artifact) => artifact.sectionId === section.id)?.runRelPath;
@@ -538,16 +549,29 @@ export function aggregateAnalysisRun(options) {
     const tradecraft = renderTradecraftAppendix(tradecraftFiles);
     const analysisIndex = renderAnalysisIndex(includedArtifacts, manifestRelPath);
     const readerGuide = renderReaderIntelligenceGuide(emittedSections, includedArtifacts);
+    // Deterministic 3–7 bullet "Key takeaways" block, harvested from the
+    // synthesis-summary / intelligence-assessment artifacts. 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.
+    const keyTakeaways = buildKeyTakeaways({ runDir });
     // TOC ordering reflects the rendered document:
     // Executive Brief (already first in emittedSections via appendSection) →
-    // Reader Intelligence Guide (inserted at position 1, after Exec Brief) →
-    // remaining sections → audit appendices.
+    // Key Takeaways (inserted right after the brief when present) →
+    // Reader Intelligence Guide → remaining sections → audit appendices.
+    let postBriefIdx = emittedSections.length > 0 &&
+        emittedSections[0]?.id === namespacedSectionId(execBriefSection?.id ?? '')
+        ? 1
+        : 0;
+    if (keyTakeaways) {
+        emittedSections.splice(postBriefIdx, 0, {
+            id: KEY_TAKEAWAYS_SECTION_ID,
+            title: KEY_TAKEAWAYS_SECTION_TITLE,
+        });
+        postBriefIdx += 1;
+    }
     if (readerGuide) {
-        const insertIdx = emittedSections.length > 0 &&
-            emittedSections[0]?.id === namespacedSectionId(execBriefSection?.id ?? '')
-            ? 1
-            : 0;
-        emittedSections.splice(insertIdx, 0, {
+        emittedSections.splice(postBriefIdx, 0, {
             id: READER_GUIDE_SECTION_ID,
             title: READER_GUIDE_SECTION_TITLE,
         });
@@ -559,6 +583,7 @@ export function aggregateAnalysisRun(options) {
         '',
         ...execBriefMarkdown,
         '',
+        ...(keyTakeaways ? [keyTakeaways, ''] : []),
         readerGuide,
         '',
         ...sectionMarkdown,

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

@@ -45,6 +45,12 @@ export interface GenerateResult {
      * the artifacts that produced it (riksdagsmonitor pattern).
      */
     readonly runArticleMdRelPath: string;
+    /**
+     * Repo-relative path of the `article-meta.json` sidecar written next to
+     * `article.md` — structured data consumed by HTML SEO, news indexes,
+     * and RSS rendering. Always emitted, deterministic.
+     */
+    readonly runArticleMetaRelPath: string;
     /** Filenames written under `outDir`, relative to `outDir`. */
     readonly writtenFiles: readonly string[];
     /** Metadata from {@link aggregateAnalysisRun}. */

package/scripts/aggregator/article-generator.js

@@ -20,9 +20,12 @@ import fs from 'fs';
 import path from 'path';
 import { pathToFileURL } from 'url';
 import { aggregateAnalysisRun, resolveArticleTypeFromManifest, } from './analysis-aggregator.js';
+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 { buildReaderIntelligenceGuideHtml, stripInlineReaderGuide, } from './reader-intelligence-guide.js';
 import { ALL_LANGUAGES } from '../constants/language-core.js';
 import { blobUrl } from './infra/github-urls.js';
 import { buildArticleSlug as _buildArticleSlug, sanitizeRunSuffix as _sanitizeRunSuffix, } from './slug/index.js';
@@ -335,6 +338,22 @@ function writeLanguageVariant(lang, slug, aggregated, englishHtml, chromeOptions
         metaSource = fs.readFileSync(langMdAbs, 'utf8');
         bodyHtml = renderMarkdown(metaSource).html;
     }
+    // Strip any AI-authored inline Reader Intelligence Guide and inject the
+    // renderer-owned, language-aware version so exactly one guide appears.
+    bodyHtml = stripInlineReaderGuide(bodyHtml);
+    // The article chrome (wrapArticleHtml) renders its own <h1> in the hero
+    // header. Strip the in-body <h1> emitted from the Markdown `# Title` to
+    // avoid a duplicate H1 and broken heading hierarchy (H2 preceding H1).
+    bodyHtml = bodyHtml.replace(/<h1[^>]*>[\s\S]*?<\/h1>\s*/, '');
+    const guideHtml = buildReaderIntelligenceGuideHtml(lang, aggregated.sectionToc, aggregated.includedArtifacts);
+    if (guideHtml) {
+        // Prepend the guide to the body so it always appears at the top of
+        // the rendered content, immediately after the chrome header. The
+        // article chrome in wrapArticleHtml wraps the body in an <article>
+        // with its own <header>/<h1>, so prepending here is deterministic
+        // and avoids fragile in-body heading searches.
+        bodyHtml = guideHtml + '\n' + bodyHtml;
+    }
     // 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
@@ -455,6 +474,25 @@ export function generateArticle(opts, runSuffix, articleCountOverride) {
         .relative(opts.repoRoot, runArticleMdAbs)
         .split(path.sep)
         .join('/');
+    // Emit `article-meta.json` next to `article.md` — a deterministic
+    // structured-data sidecar consumed by HTML SEO, news indexes, and RSS.
+    // Same artifact bytes in → same JSON bytes out (asserted by the
+    // determinism test).
+    const runArticleMetaAbs = path.join(opts.runDir, 'article-meta.json');
+    const articleMeta = buildArticleMeta({
+        runDir: opts.runDir,
+        repoRoot: opts.repoRoot,
+        date: aggregated.date,
+        articleType: aggregated.articleType,
+        runId: readManifestRunId(opts.runDir, path.basename(opts.runDir)),
+        gateResult: aggregated.gateResult,
+        slug,
+    });
+    fs.writeFileSync(runArticleMetaAbs, serializeArticleMeta(articleMeta), 'utf8');
+    const runArticleMetaRelPath = path
+        .relative(opts.repoRoot, runArticleMetaAbs)
+        .split(path.sep)
+        .join('/');
     // Also write source Markdown under <outDir>/<slug>.en.md for search
     // indexing and backwards compatibility with existing news-index scripts.
     ensureDir(opts.outDir);
@@ -479,6 +517,7 @@ export function generateArticle(opts, runSuffix, articleCountOverride) {
     return {
         sourceMarkdownRelPath: runArticleMdRelPath,
         runArticleMdRelPath,
+        runArticleMetaRelPath,
         writtenFiles: written,
         aggregated,
     };
@@ -536,6 +575,29 @@ export function generateAllArticles(opts) {
     }
     return results;
 }
+/**
+ * Read the run identifier from `manifest.json`, falling back to the
+ * directory basename when the manifest is missing or unparsable. Wraps
+ * the canonical resolver from `aggregator/manifest/index.ts` so callers
+ * outside the aggregator core (here, the article-meta sidecar emitter)
+ * stay decoupled from the internal manifest schema.
+ *
+ * @param runDir - Absolute run directory path
+ * @param defaultRunId - Fall-back run id (typically the directory basename)
+ * @returns Resolved run id, never empty
+ */
+function readManifestRunId(runDir, defaultRunId) {
+    const manifestPath = path.join(runDir, 'manifest.json');
+    if (!fs.existsSync(manifestPath))
+        return defaultRunId;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        return _resolveRunId(parsed, defaultRunId);
+    }
+    catch {
+        return defaultRunId;
+    }
+}
 /**
  * Read the raw manifest.json from a run directory and return the subset
  * of fields consumed by {@link resolveArticleMetadata}. Returns an empty

package/scripts/aggregator/article-html.js

@@ -23,6 +23,12 @@ import { buildHeadFreshnessTags } from '../constants/build-info-meta.js';
 import { ALL_LANGUAGES, LANGUAGE_NAMES, LANGUAGE_FLAGS, PAGE_TITLES, SKIP_LINK_TEXTS, TOC_ARIA_LABELS, UPDATE_AVAILABLE_LABELS, UPDATE_REFRESH_CTA_LABELS, UPDATE_DISMISS_LABELS, getLocalizedString, getTextDirection, } from '../constants/languages.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';
+/** Publisher organization name used in JSON-LD, meta tags. */
+const PUBLISHER_NAME = 'Hack23 AB';
+/** Site name used across meta tags and structured data. */
+const SITE_NAME = 'EU Parliament Monitor';
 /**
  * Build the canonical filename for an article in a given language. English
  * uses the bare stem (`2026-01-15-breaking-en.html`); other languages share
@@ -85,7 +91,13 @@ export function buildArticleToc(entries, lang) {
         return '';
     const label = escapeHTML(getLocalizedString(TOC_ARIA_LABELS, lang));
     const items = entries
-        .map((e) => `        <li><a href="#${escapeHTML(e.id)}">${escapeHTML(e.title)}</a></li>`)
+        .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;
+        return `        <li><a href="#${escapeHTML(e.id)}">${escapeHTML(displayTitle)}</a></li>`;
+    })
         .join('\n');
     return [
         `  <aside class="article-toc-container" aria-label="${label}">`,
@@ -111,7 +123,7 @@ export function buildArticleToc(entries, lang) {
 export function wrapArticleHtml(options) {
     const safeLang = ALL_LANGUAGES.includes(options.lang) ? options.lang : 'en';
     const dir = getTextDirection(safeLang);
-    const siteTitle = getLocalizedString(PAGE_TITLES, safeLang).split(' - ')[0] ?? 'EU Parliament Monitor';
+    const siteTitle = getLocalizedString(PAGE_TITLES, safeLang).split(' - ')[0] ?? SITE_NAME;
     const skipLinkText = getLocalizedString(SKIP_LINK_TEXTS, safeLang);
     const canonicalUrl = `${BASE_URL}/news/${getArticleFilename(options.articleSlug, safeLang)}`;
     const indexHref = safeLang === 'en' ? '../index.html' : `../index-${safeLang}.html`;
@@ -127,14 +139,21 @@ export function wrapArticleHtml(options) {
         headline: options.title,
         description: options.description,
         datePublished: options.date,
+        dateModified: options.date,
         inLanguage: safeLang,
         url: canonicalUrl,
-        author: { '@type': 'Organization', name: 'Hack23 AB', url: 'https://hack23.com' },
-        publisher: { '@type': 'Organization', name: 'Hack23 AB', url: 'https://hack23.com' },
+        image: `${BASE_URL}/images/og-image.jpg`,
+        author: { '@type': 'Organization', name: PUBLISHER_NAME, url: 'https://hack23.com' },
+        publisher: {
+            '@type': 'Organization',
+            name: PUBLISHER_NAME,
+            url: 'https://hack23.com',
+            logo: { '@type': 'ImageObject', url: `${BASE_URL}/images/apple-touch-icon.png` },
+        },
         articleSection: options.articleType,
         isPartOf: {
             '@type': 'WebSite',
-            name: 'EU Parliament Monitor',
+            name: SITE_NAME,
             url: BASE_URL,
         },
         ...(options.isBasedOn && options.isBasedOn.length > 0
@@ -143,7 +162,32 @@ export function wrapArticleHtml(options) {
             }
             : {}),
     };
-    const jsonLdString = JSON.stringify(jsonLd).replace(/</g, '\\u003c');
+    const breadcrumbLd = {
+        '@context': 'https://schema.org',
+        '@type': 'BreadcrumbList',
+        itemListElement: [
+            {
+                '@type': 'ListItem',
+                position: 1,
+                name: SITE_NAME,
+                item: BASE_URL,
+            },
+            {
+                '@type': 'ListItem',
+                position: 2,
+                name: options.articleType.replace(/-/g, ' '),
+                item: `${BASE_URL}/news/`,
+            },
+            {
+                '@type': 'ListItem',
+                position: 3,
+                name: options.title,
+                item: canonicalUrl,
+            },
+        ],
+    };
+    const structuredData = [jsonLd, breadcrumbLd];
+    const jsonLdString = JSON.stringify(structuredData).replace(/</g, '\\u003c');
     const pageTitle = `${options.title} — ${siteTitle}`;
     const header = buildSiteHeader({
         lang: safeLang,
@@ -163,8 +207,8 @@ export function wrapArticleHtml(options) {
   <title>${escapeHTML(pageTitle)}</title>
   <meta name="description" content="${escapeHTML(options.description)}">
   <meta name="robots" content="index, follow, max-image-preview:large">
-  <meta name="author" content="Hack23 AB">
-  <meta name="publisher" content="Hack23 AB">
+  <meta name="author" content="${PUBLISHER_NAME}">
+  <meta name="publisher" content="${PUBLISHER_NAME}">
   <meta name="date" content="${options.date}">
   <meta name="article:published_time" content="${options.date}">
   <link rel="canonical" href="${canonicalUrl}">

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

@@ -0,0 +1,121 @@
+import { buildKeyTakeaways as _buildKeyTakeaways } from './key-takeaways.js';
+/** Shape of `article-meta.json`. */
+export interface ArticleMeta {
+    /** ISO date of the run (`YYYY-MM-DD`). */
+    readonly date: string;
+    /** Article type slug (e.g. `breaking`). */
+    readonly articleType: string;
+    /** Stable run identifier from the manifest. */
+    readonly runId: string;
+    /** Latest non-PENDING gate result. */
+    readonly gateResult: string;
+    /** Article slug used by the news pages (`<date>-<type>[-<suffix>]`). */
+    readonly slug: string;
+    /** Run-relative path of the canonical `article.md`. */
+    readonly articlePath: string;
+    /** One-sentence executive lead — the strongest finding, distilled. */
+    readonly topFinding: string;
+    /** 3–7 deterministic key takeaways harvested from synthesis-summary. */
+    readonly keyTakeaways: readonly string[];
+    /** Top political risks (artifact-driven, may be empty). */
+    readonly topRisks: readonly string[];
+    /** Key dated triggers / "what to watch" items. */
+    readonly keyDates: readonly string[];
+    /** Key actors / political groups identified by the artifacts. */
+    readonly keyActors: readonly string[];
+    /** Optional IMF / WorldBank macro hook surfaced as a sidebar callout. */
+    readonly macroContext: string;
+    /**
+     * Run-relative paths of every artifact whose content fed into this meta
+     * record — emitted so the HTML SEO layer can build `isBasedOn` arrays
+     * without re-walking the run directory.
+     */
+    readonly sources: readonly string[];
+}
+/** Options for {@link buildArticleMeta}. */
+export interface BuildArticleMetaOptions {
+    /** Absolute path to the analysis run directory. */
+    readonly runDir: string;
+    /** Absolute path to the repository root (used for repo-relative paths). */
+    readonly repoRoot: string;
+    /** ISO date of the run (`YYYY-MM-DD`). */
+    readonly date: string;
+    /** Article type slug. */
+    readonly articleType: string;
+    /** Stable run identifier from the manifest. */
+    readonly runId: string;
+    /** Latest non-PENDING gate result. */
+    readonly gateResult: string;
+    /** Article slug used by the news pages. */
+    readonly slug: string;
+}
+/**
+ * Mine top political risks from `risk-scoring/risk-matrix.md` (or its
+ * historic variants under the same directory). Falls back to the first
+ * bullets in `risk-scoring/quantitative-swot.md` when the matrix is
+ * absent. Returns at most {@link MAX_LIST_ENTRIES} bullets.
+ *
+ * @param runDir - Absolute path to the analysis run directory
+ * @returns Ordered list of risk bullet bodies
+ */
+export declare function extractTopRisks(runDir: string): string[];
+/**
+ * Mine forward-looking dated items from
+ * `intelligence/parliamentary-calendar-projection.md` and
+ * `extended/forward-indicators.md`. Returns at most
+ * {@link MAX_LIST_ENTRIES} bullets, de-duplicated across the two sources.
+ *
+ * @param runDir - Absolute path to the analysis run directory
+ * @returns Ordered list of dated trigger bullet bodies
+ */
+export declare function extractKeyDates(runDir: string): string[];
+/**
+ * Mine key actors / political groups from
+ * `classification/actor-mapping.md` and `intelligence/stakeholder-map.md`.
+ * Falls through to coalition-dynamics when the canonical actor map is
+ * missing. Returns at most {@link MAX_LIST_ENTRIES} bullets.
+ *
+ * @param runDir - Absolute path to the analysis run directory
+ * @returns Ordered list of actor bullet bodies
+ */
+export declare function extractKeyActors(runDir: string): string[];
+/**
+ * Resolve a one-line IMF / WorldBank macro context callout from
+ * `intelligence/economic-context.md`. Returns the trimmed lead sentence
+ * of the artifact, or `''` when the artifact is missing.
+ *
+ * @param runDir - Absolute path to the analysis run directory
+ * @returns IMF-backed macro hook, or `''`
+ */
+export declare function extractMacroContext(runDir: string): string;
+/**
+ * Resolve the deterministic 3–7 key-takeaway bullets used in both the
+ * Markdown article body and `article-meta.json`.
+ *
+ * @param runDir - Absolute path to the analysis run directory
+ * @returns Ordered list of takeaway bodies (3–7 entries)
+ */
+export declare function extractKeyTakeaways(runDir: string): string[];
+/**
+ * Build the deterministic `ArticleMeta` record for one run. Pure function
+ * of the on-disk artifacts plus the resolved manifest fields.
+ *
+ * @param options - Run-level metadata + absolute run directory
+ * @returns Frozen, JSON-serialisable {@link ArticleMeta}
+ */
+export declare function buildArticleMeta(options: BuildArticleMetaOptions): ArticleMeta;
+/**
+ * Serialise an {@link ArticleMeta} as a stable JSON string with a trailing
+ * newline. Keys are emitted in declaration order (insertion-order, matching
+ * the interface layout). Determinism guarantee: same input → same bytes.
+ *
+ * @param meta - Article meta record
+ * @returns JSON string ready to be written next to `article.md`
+ */
+export declare function serializeArticleMeta(meta: ArticleMeta): string;
+/**
+ * Convenience wrapper that re-exports {@link _buildKeyTakeaways} so the
+ * aggregator can import the rendered Markdown block from a single module.
+ */
+export { _buildKeyTakeaways as buildKeyTakeawaysMarkdown };
+//# sourceMappingURL=article-meta.d.ts.map