euparliamentmonitor 0.9.2 → 0.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",
@@ -163,9 +163,9 @@
     "happy-dom": "20.9.0",
     "htmlhint": "1.9.2",
     "husky": "9.1.7",
-    "jscpd": "4.0.9",
+    "jscpd": "4.1.0",
     "knip": "^6.7.0",
-    "lint-staged": "17.0.3",
+    "lint-staged": "17.0.4",
     "mermaid": "11.14.0",
     "papaparse": "5.5.3",
     "prettier": "3.8.3",

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

@@ -115,6 +115,17 @@ export declare function renderProvenanceBlock(params: {
  * @returns Markdown block with two subsections (methodologies, templates)
  */
 export declare function renderTradecraftAppendix(files: readonly string[]): string;
+/**
+ * Public re-export of the internal `humanize` helper so other aggregator
+ * modules (in particular `article-html.ts`) can derive the same display
+ * title from a file stem when no curated title is available. Keeping the
+ * single canonical implementation here avoids duplicate humanisation
+ * rules drifting across modules.
+ *
+ * @param stem - File stem (e.g. `electoral-cycle-methodology`)
+ * @returns Humanised title (e.g. `Electoral Cycle Methodology`)
+ */
+export declare function humanizeStem(stem: string): string;
 /**
  * Render the analysis-index appendix — a compact table of every included
  * artifact and its section, plus a direct link to the manifest.

package/scripts/aggregator/analysis-aggregator.js

@@ -213,19 +213,25 @@ export function renderTradecraftAppendix(files) {
         'This article is produced under the [Hack23 AB](https://hack23.com) intelligence tradecraft library. Every methodology and artifact template applied to this run is linked below.',
         '',
     ];
-    if (methods.length > 0) {
-        block.push('### Methodologies');
+    // Order: Artifact templates first (concrete deliverables readers
+    // recognise from the article body), then Methodologies (the underlying
+    // tradecraft library). This matches the natural reader flow — the
+    // article is built from artifacts, and the methodologies explain how
+    // each artifact is produced — and pairs with the contextual, kind-
+    // aware "View …" CTAs rendered in `enhanceTradecraftCards`.
+    if (templates.length > 0) {
+        block.push('### Artifact templates');
         block.push('');
-        for (const rel of methods) {
+        for (const rel of templates) {
             const stem = rel.split('/').pop()?.replace(/\.md$/i, '') ?? rel;
             block.push(`- [${humanize(stem)}](${githubBlobUrl(rel)})`);
         }
         block.push('');
     }
-    if (templates.length > 0) {
-        block.push('### Artifact templates');
+    if (methods.length > 0) {
+        block.push('### Methodologies');
         block.push('');
-        for (const rel of templates) {
+        for (const rel of methods) {
             const stem = rel.split('/').pop()?.replace(/\.md$/i, '') ?? rel;
             block.push(`- [${humanize(stem)}](${githubBlobUrl(rel)})`);
         }
@@ -233,6 +239,19 @@ export function renderTradecraftAppendix(files) {
     }
     return block.join('\n');
 }
+/**
+ * Public re-export of the internal `humanize` helper so other aggregator
+ * modules (in particular `article-html.ts`) can derive the same display
+ * title from a file stem when no curated title is available. Keeping the
+ * single canonical implementation here avoids duplicate humanisation
+ * rules drifting across modules.
+ *
+ * @param stem - File stem (e.g. `electoral-cycle-methodology`)
+ * @returns Humanised title (e.g. `Electoral Cycle Methodology`)
+ */
+export function humanizeStem(stem) {
+    return humanize(stem);
+}
 /**
  * Render the analysis-index appendix — a compact table of every included
  * artifact and its section, plus a direct link to the manifest.

package/scripts/aggregator/article-generator.js

@@ -29,7 +29,7 @@ import { resolveRunId as _resolveRunId } from './manifest/index.js';
 import { resolveArticleMetadata, extractStrongProseLine, } from './article-metadata.js';
 import { buildArticleMeta, serializeArticleMeta } from './article-meta.js';
 import { renderMarkdown } from './markdown-renderer.js';
-import { wrapArticleHtml, getArticleFilename, localizeArticleBody } from './article-html.js';
+import { wrapArticleHtml, getArticleFilename, localizeArticleBody, enhanceTradecraftCards, enhanceAnalysisIndexCards, } 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';
@@ -364,6 +364,12 @@ function writeLanguageVariant(lang, slug, aggregated, englishHtml, chromeOptions
     // Localize Tradecraft References, Analysis Index, and other appendix
     // section headings and content into the target language.
     bodyHtml = localizeArticleBody(bodyHtml, lang);
+    // Replace the plain Tradecraft References bullet lists and the
+    // Analysis Index table with `pi-card-grid` cards. Runs for every
+    // language (including English) so the "much nicer" rendering matches
+    // the political-intelligence.html visual vocabulary site-wide.
+    bodyHtml = enhanceTradecraftCards(bodyHtml, lang);
+    bodyHtml = enhanceAnalysisIndexCards(bodyHtml, lang);
     // When a per-language translated source exists, prefer a summary derived
     // from it so the `<meta description>` matches the visible prose. The
     // editorial title still comes from the English resolver (per-language

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

@@ -73,8 +73,10 @@ export declare function buildArticleHreflangLinks(articleSlug: string): string;
  * Build the article-level Table of Contents nav. Renders a labelled
  * `<nav class="article-toc">` with one `<a>` per H2 section, keyed by the
  * stable fragment ids produced by the aggregator. The containing `<aside>`
- * is styled as a sticky sidebar on wide viewports and collapses into a
- * `<details>` disclosure on narrow viewports via `styles.css`.
+ * is styled as a sticky, full-height sidebar on wide viewports and
+ * collapses into a `<details>` disclosure on narrow viewports via
+ * `styles.css`. Each entry is prefixed with a contextual emoji icon so
+ * readers can scan the navigation visually as well as textually.
  *
  * Returns an empty string when `entries` is empty so low-signal
  * `ANALYSIS_ONLY` articles (few sections, no value in a TOC) stay compact.
@@ -94,6 +96,46 @@ export declare function buildArticleToc(entries: readonly ArticleTocEntry[], lan
  * @returns HTML body with localized appendix sections
  */
 export declare function localizeArticleBody(bodyHtml: string, lang: LanguageCode): string;
+/**
+ * Replace the rendered Tradecraft References bullet lists with a
+ * `pi-card-grid` of richly described cards (icon, curated title,
+ * curated description, kind-aware CTA). The cards reuse the exact same
+ * class hooks as `political-intelligence.html`, so the site-wide CSS
+ * already styles them — no additional CSS is required.
+ *
+ * After the April-2026 reorder the rendered Markdown emits Artifact
+ * templates as the first sub-heading and Methodologies as the second,
+ * matching how readers encounter the run (artifacts first, methodology
+ * library second). The card upgrade follows the same order so the H3
+ * positions stay aligned with the kind-aware CTA labels.
+ *
+ * Falls back to the original Markdown-rendered list when the expected
+ * structure (H2 → intro paragraph → Artifact-templates sub-heading →
+ * `<ul>` → Methodologies sub-heading → `<ul>`) is missing, so partially
+ * stripped or unusual articles are not silently corrupted.
+ *
+ * @param bodyHtml - The (already-localised) article body HTML
+ * @param lang - Target language code for curated titles/descriptions
+ * @returns Body HTML with the tradecraft section upgraded to cards
+ */
+export declare function enhanceTradecraftCards(bodyHtml: string, lang: LanguageCode): string;
+/**
+ * Replace the Analysis Index `<table>` with a `pi-card-grid` of cards,
+ * one per included artifact. Each card renders the artifact's curated
+ * localised title + description, the section it contributed to, the
+ * run-relative path as inline `<code>`, and a "View on GitHub" CTA.
+ *
+ * Strategy: parse the rendered table's `<tbody>` rows (each row carries
+ * `[sectionId, <a href="…">stem</a>, runRelPath]`) and re-render the
+ * region between the table's opening wrapper and `</table>` as a card
+ * grid. The wrapping `<div class="table-scroll">` is dropped because
+ * the card grid handles its own responsive layout via flex/grid.
+ *
+ * @param bodyHtml - Article body HTML
+ * @param lang - Target language code
+ * @returns Body HTML with the Analysis Index upgraded to a card grid
+ */
+export declare function enhanceAnalysisIndexCards(bodyHtml: string, lang: LanguageCode): string;
 /**
  * Render the full article HTML document with the shared chrome.
  *

package/scripts/aggregator/article-html.js

@@ -25,11 +25,13 @@ import { ArticleCategory } from '../types/index.js';
 import { escapeHTML } from '../utils/file-utils.js';
 import { buildSiteFooter, buildSiteHeader, buildPageBanner, } from '../templates/section-builders.js';
 import { READER_GUIDE_SECTION_ID } from './reader-guide-constants.js';
-import { READER_GUIDE_TITLE_LABELS } from './reader-intelligence-guide.js';
+import { READER_GUIDE_TITLE_LABELS, getReaderGuideSectionIcon, } from './reader-intelligence-guide.js';
 import { TRADECRAFT_SECTION_ID, MANIFEST_SECTION_ID, SUPPLEMENTARY_SECTION_ID, } from './artifact-order.js';
+import { humanizeStem } from './analysis-aggregator.js';
 import { KEY_TAKEAWAYS_SECTION_ID } from './key-takeaways.js';
 import { getPoliticalIntelligenceFilename } from '../generators/political-intelligence.js';
 import { getSitemapFilename } from '../generators/sitemap/index.js';
+import { getCuratedTitle, getCuratedDescription, getArtifactInfo, } from '../generators/political-intelligence-descriptions.js';
 /**
  * Resolve a localized article type label with icon. Falls back to the
  * humanised slug when a translation isn't available.
@@ -132,12 +134,38 @@ function getLocalizedTocTitle(sectionId, fallbackTitle, lang) {
     }
     return fallbackTitle;
 }
+/**
+ * Resolve the visual icon glyph used as the Table-of-Contents bullet for
+ * a given section. Reuses {@link getReaderGuideSectionIcon} for the
+ * canonical artifact sections (so the TOC and the Reader Intelligence
+ * Guide share the same visual vocabulary), and adds dedicated icons for
+ * the aggregator-owned appendix anchors that the guide does not list.
+ *
+ * @param sectionId - Anchor id of the section (e.g. `section-risk`,
+ *                    `aggregator-tradecraft-references`)
+ * @returns Single emoji glyph used as the `guide-icon` for that entry
+ */
+function getTocSectionIcon(sectionId) {
+    if (sectionId === READER_GUIDE_SECTION_ID)
+        return '🧭';
+    if (sectionId === KEY_TAKEAWAYS_SECTION_ID)
+        return '🔑';
+    if (sectionId === SUPPLEMENTARY_SECTION_ID)
+        return '🗂️';
+    if (sectionId === TRADECRAFT_SECTION_ID)
+        return '🛠️';
+    if (sectionId === MANIFEST_SECTION_ID)
+        return '📚';
+    return getReaderGuideSectionIcon(sectionId);
+}
 /**
  * Build the article-level Table of Contents nav. Renders a labelled
  * `<nav class="article-toc">` with one `<a>` per H2 section, keyed by the
  * stable fragment ids produced by the aggregator. The containing `<aside>`
- * is styled as a sticky sidebar on wide viewports and collapses into a
- * `<details>` disclosure on narrow viewports via `styles.css`.
+ * is styled as a sticky, full-height sidebar on wide viewports and
+ * collapses into a `<details>` disclosure on narrow viewports via
+ * `styles.css`. Each entry is prefixed with a contextual emoji icon so
+ * readers can scan the navigation visually as well as textually.
  *
  * Returns an empty string when `entries` is empty so low-signal
  * `ANALYSIS_ONLY` articles (few sections, no value in a TOC) stay compact.
@@ -153,7 +181,8 @@ export function buildArticleToc(entries, lang) {
     const items = entries
         .map((e) => {
         const displayTitle = getLocalizedTocTitle(e.id, e.title, lang);
-        return `        <li><a href="#${escapeHTML(e.id)}">${escapeHTML(displayTitle)}</a></li>`;
+        const icon = getTocSectionIcon(e.id);
+        return `        <li><a href="#${escapeHTML(e.id)}"><span class="article-toc-icon" aria-hidden="true">${icon}</span> <span class="article-toc-text">${escapeHTML(displayTitle)}</span></a></li>`;
     })
         .join('\n');
     return [
@@ -205,11 +234,20 @@ export function localizeArticleBody(bodyHtml, lang) {
         }
     }
     // --- Methodologies sub-heading ---
+    // markdown-it's anchor plugin renders sub-headings as
+    // `<h3 id="methodologies" tabindex="-1"><a class="header-anchor"
+    //   href="#methodologies"><span>Methodologies</span></a></h3>`.
+    // Localise the inner `<span>Methodologies</span>` text without using
+    // regular expressions to avoid catastrophic backtracking on long
+    // inputs. We accept either the anchor-prefixed form above or the
+    // bare `<h3>Methodologies</h3>` form some renderers emit.
     const methodsLabel = getLocalizedString(TRADECRAFT_METHODOLOGIES_LABELS, lang);
-    html = html.replace(/<h3>Methodologies<\/h3>/, `<h3>${escapeHTML(methodsLabel)}</h3>`);
+    html = replaceFirstStringIn(html, '<span>Methodologies</span>', `<span>${escapeHTML(methodsLabel)}</span>`);
+    html = replaceFirstStringIn(html, '<h3>Methodologies</h3>', `<h3>${escapeHTML(methodsLabel)}</h3>`);
     // --- Artifact templates sub-heading ---
     const templatesLabel = getLocalizedString(TRADECRAFT_TEMPLATES_LABELS, lang);
-    html = html.replace(/<h3>Artifact templates<\/h3>/, `<h3>${escapeHTML(templatesLabel)}</h3>`);
+    html = replaceFirstStringIn(html, '<span>Artifact templates</span>', `<span>${escapeHTML(templatesLabel)}</span>`);
+    html = replaceFirstStringIn(html, '<h3>Artifact templates</h3>', `<h3>${escapeHTML(templatesLabel)}</h3>`);
     // --- Analysis Index heading ---
     const analysisIndexHeading = getLocalizedString(ANALYSIS_INDEX_HEADING_LABELS, lang);
     html = replaceHeadingById(html, MANIFEST_SECTION_ID, 'Analysis Index', analysisIndexHeading);
@@ -259,6 +297,24 @@ export function localizeArticleBody(bodyHtml, lang) {
     html = replaceHeadingById(html, SUPPLEMENTARY_SECTION_ID, 'Supplementary Intelligence', supplementaryHeading);
     return html;
 }
+/**
+ * Replace the first literal occurrence of `needle` in `haystack` with
+ * `replacement`. Uses `indexOf` rather than `String.prototype.replace`
+ * with a regex so we don't fall foul of the security/detect-unsafe-regex
+ * lint rule, and so we never accidentally interpret regex metacharacters
+ * inside `needle` or `$1`-style references inside `replacement`.
+ *
+ * @param haystack - String to search in
+ * @param needle - Literal substring to replace
+ * @param replacement - Literal replacement text (no `$` escaping needed)
+ * @returns Modified string, or `haystack` unchanged when `needle` is absent
+ */
+function replaceFirstStringIn(haystack, needle, replacement) {
+    const idx = haystack.indexOf(needle);
+    if (idx === -1)
+        return haystack;
+    return haystack.slice(0, idx) + replacement + haystack.slice(idx + needle.length);
+}
 /**
  * Replace an H2 heading's text content by locating it via its `id` attribute.
  * Uses indexOf-based search to avoid polynomial regex backtracking (CodeQL).
@@ -295,6 +351,575 @@ function replaceHeadingById(html, sectionId, englishTitle, localizedTitle) {
         return html;
     return html.slice(0, titleStart) + escapeHTML(localizedTitle) + html.slice(titleEnd);
 }
+/* ─── Tradecraft & Analysis Index card-grid enhancement ─────────── */
+/**
+ * Default emoji used for cards that do not have a curated icon mapped to
+ * their stem. Mirrors the fallback used in
+ * {@link political-intelligence/html.buildPiCard}.
+ */
+const DEFAULT_CARD_ICON = '🧭';
+/**
+ * Curated icon overrides keyed by the methodology / template stem (the
+ * filename without the `.md` extension). Mirrors a subset of the icon
+ * map used by `generators/political-intelligence/html.ts` so the cards
+ * embedded inside news articles match the icons on the dedicated
+ * Political Intelligence index page.
+ */
+const STEM_ICONS = {
+    README: '📘',
+    'ai-driven-analysis-guide': '🧭',
+    'analytical-supplementary-methodology': '🧭',
+    'artifact-catalog': '📚',
+    'electoral-cycle-methodology': '🗳️',
+    'electoral-domain-methodology': '🗳️',
+    'forward-projection-methodology': '🔭',
+    'imf-indicator-mapping': '💶',
+    'osint-tradecraft-standards': '🛳️',
+    'per-artifact-methodologies': '🧭',
+    'per-document-methodology': '🧭',
+    'political-classification-guide': '🏷️',
+    'political-risk-methodology': '⚠️',
+    'political-style-guide': '✒️',
+    'political-swot-framework': '⚖️',
+    'political-threat-framework': '🛡️',
+    'strategic-extensions-methodology': '🧭',
+    'structural-metadata-methodology': '🧭',
+    'synthesis-methodology': '🔗',
+    'worldbank-indicator-mapping': '🌍',
+    'actor-mapping': '🎭',
+    'actor-threat-profiles': '🛡️',
+    'analysis-index': '📚',
+    'coalition-dynamics': '🤝',
+    'coalition-mathematics': '🧮',
+    'commission-wp-alignment': '📋',
+    'comparative-international': '🌐',
+    'consequence-trees': '🌳',
+    'cross-reference-map': '🗺️',
+    'cross-run-diff': '🔁',
+    'cross-session-intelligence': '🔁',
+    'data-download-manifest': '📦',
+    'deep-analysis': '🔍',
+    'devils-advocate-analysis': '🪞',
+    'economic-context': '💶',
+    'executive-brief': '📋',
+    'forces-analysis': '⚙️',
+    'forward-indicators': '🔭',
+    'forward-projection': '🔭',
+    'historical-baseline': '📜',
+    'historical-parallels': '📜',
+    'imf-vintage-audit': '💶',
+    'impact-matrix': '📊',
+    'implementation-feasibility': '🔧',
+    'intelligence-assessment': '🧠',
+    'legislative-disruption': '🛡️',
+    'legislative-pipeline-forecast': '🛤️',
+    'legislative-velocity-risk': '⏱️',
+    'mandate-fulfilment-scorecard': '📋',
+    'mcp-reliability-audit': '📡',
+    'media-framing-analysis': '📰',
+    'methodology-reflection': '🪞',
+    'parliamentary-calendar-projection': '📅',
+    'per-file-political-intelligence': '🧭',
+    'pestle-analysis': '🌍',
+    'political-capital-risk': '💼',
+    'political-classification': '🏷️',
+    'political-threat-landscape': '🛡️',
+    'presidency-trio-context': '🇪🇺',
+    'quantitative-swot': '⚖️',
+    'reference-analysis-quality': '✅',
+    'risk-assessment': '⚠️',
+    'risk-matrix': '⚠️',
+    'scenario-forecast': '🔮',
+    'seat-projection': '🪑',
+    'session-baseline': '📊',
+    'significance-classification': '⚖️',
+    'significance-scoring': '⚖️',
+    'stakeholder-impact': '👥',
+    'stakeholder-map': '👥',
+    'swot-analysis': '⚖️',
+    'synthesis-summary': '🔗',
+    'term-arc': '🗳️',
+    'threat-analysis': '🛡️',
+    'threat-model': '🛡️',
+    'voter-segmentation': '👥',
+    'voting-patterns': '🤝',
+    'wildcards-blackswans': '⚡',
+    'workflow-audit': '🔧',
+};
+/**
+ * Resolve the icon for a tradecraft / artifact card by file stem.
+ *
+ * @param stem - File stem (filename without `.md`)
+ * @returns Single emoji glyph for the card icon
+ */
+function getStemIcon(stem) {
+    return STEM_ICONS[stem] ?? DEFAULT_CARD_ICON;
+}
+/**
+ * Extract `<a href="…">label</a>` link tokens from the slice of HTML
+ * between two indices. Used to harvest the methodology / template list
+ * the Markdown renderer emitted as `<ul><li><a>…</a></li>…</ul>` so we
+ * can re-render it as a card grid.
+ *
+ * Anchors whose `href` does not point at an `analysis/<methodologies|
+ * templates>/<…>.md` blob URL are silently skipped — the tradecraft
+ * appendix only contains those, and any stray external link (e.g. the
+ * Hack23 URL inside the intro paragraph) must not be promoted to a card.
+ *
+ * @param html - HTML slice to scan
+ * @param expectedPrefix - Path prefix (e.g. `analysis/methodologies/`)
+ * @returns List of extracted `{ href, repoRelPath }` tuples
+ */
+function extractTradecraftLinks(html, expectedPrefix) {
+    const out = [];
+    // Walk anchor tags one at a time using indexOf to avoid catastrophic
+    // backtracking on long inputs (CodeQL js/polynomial-redos).
+    let cursor = 0;
+    while (cursor < html.length) {
+        const aIdx = html.indexOf('<a ', cursor);
+        if (aIdx === -1)
+            break;
+        const hrefIdx = html.indexOf('href="', aIdx);
+        if (hrefIdx === -1)
+            break;
+        const urlStart = hrefIdx + 'href="'.length;
+        const urlEnd = html.indexOf('"', urlStart);
+        if (urlEnd === -1)
+            break;
+        const href = html.slice(urlStart, urlEnd);
+        const closeIdx = html.indexOf('>', urlEnd);
+        if (closeIdx === -1)
+            break;
+        const endIdx = html.indexOf('</a>', closeIdx);
+        if (endIdx === -1)
+            break;
+        cursor = endIdx + '</a>'.length;
+        // Only keep links pointing at the expected analysis/* path under the
+        // GitHub blob URL — every other anchor is intro chrome.
+        const blobMarker = `/blob/main/${expectedPrefix}`;
+        const blobIdx = href.indexOf(blobMarker);
+        if (blobIdx === -1)
+            continue;
+        const repoRelPath = href.slice(blobIdx + '/blob/main/'.length);
+        out.push({ href, repoRelPath });
+    }
+    return out;
+}
+/**
+ * Render a single tradecraft / artifact card. Mirrors the structure
+ * used on `political-intelligence.html` so the visual vocabulary stays
+ * consistent (same `.pi-card-grid`, `.pi-card`, `.pi-card__icon`,
+ * `.pi-card__body`, `.pi-card__title`, `.pi-card__desc`,
+ * `.pi-card__cta` class hooks).
+ *
+ * The `.pi-card__path` filename row that the political-intelligence
+ * page emits is intentionally omitted here — inside an article body the
+ * curated title plus the curated description already convey the
+ * artifact's purpose, and the raw `analysis/.../foo.md` filename adds
+ * visual noise without providing reader-relevant context. Readers who
+ * need the path can hover the card link or click through.
+ *
+ * The CTA is kind-aware ("View methodology" for the Methodologies
+ * sub-section, "View artifact template" for the Artifact templates
+ * sub-section) — the older generic "View on GitHub" leaked workflow
+ * jargon into a reader-facing surface and provided no context about
+ * what the link targets.
+ *
+ * @param link - Extracted link with absolute href + repo-relative path
+ * @param lang - Target language code for title/description lookup
+ * @param ctaLabel - Pre-resolved localised CTA text (kind-aware)
+ * @returns HTML fragment for one `<li class="pi-card">…</li>` element
+ */
+function renderTradecraftCard(link, lang, ctaLabel) {
+    const stem = link.repoRelPath.split('/').pop()?.replace(/\.md$/i, '') ?? link.repoRelPath;
+    // Use the humanised stem (e.g. "Electoral Cycle Methodology") as the
+    // fallback title, matching how the political-intelligence page
+    // resolves titles for files without a curated entry. The previous
+    // raw-stem fallback ("electoral-cycle-methodology") leaked filename
+    // noise into reader-facing card titles.
+    const fallbackTitle = humanizeStem(stem);
+    const title = getCuratedTitle(link.repoRelPath, lang, fallbackTitle);
+    const description = getCuratedDescription(link.repoRelPath, lang, fallbackTitle);
+    const icon = getStemIcon(stem);
+    return [
+        `          <li class="pi-card">`,
+        `            <a class="pi-card__link" href="${escapeHTML(link.href)}" rel="noopener external" target="_blank">`,
+        `              <span class="pi-card__icon" aria-hidden="true">${icon}</span>`,
+        `              <span class="pi-card__body">`,
+        `                <span class="pi-card__title">${escapeHTML(title)}</span>`,
+        `                <span class="pi-card__desc">${escapeHTML(description)}</span>`,
+        `                <span class="pi-card__cta">${escapeHTML(ctaLabel)} <span aria-hidden="true">↗</span></span>`,
+        `              </span>`,
+        `            </a>`,
+        `          </li>`,
+    ].join('\n');
+}
+/**
+ * Localised "View methodology" CTA used on every Tradecraft References
+ * methodology card. Tells the reader exactly what the link surface
+ * targets — a methodology guide — so the call-to-action is informative
+ * even when the card is read in isolation.
+ *
+ * @param lang - Target language code
+ * @returns Localised CTA text
+ */
+function getViewMethodologyLabel(lang) {
+    const labels = {
+        en: 'View methodology',
+        sv: 'Visa metodologi',
+        da: 'Se metode',
+        no: 'Se metodologi',
+        fi: 'Näytä metodologia',
+        de: 'Methodologie ansehen',
+        fr: 'Voir la méthodologie',
+        es: 'Ver metodología',
+        nl: 'Methodologie bekijken',
+        ar: 'عرض المنهجية',
+        he: 'הצג מתודולוגיה',
+        ja: '方法論を表示',
+        ko: '방법론 보기',
+        zh: '查看方法论',
+    };
+    return labels[lang] ?? labels.en ?? 'View methodology';
+}
+/**
+ * Localised "View artifact template" CTA used on every Tradecraft
+ * References artifact-template card. Tells the reader exactly what the
+ * link surface targets — a structured template that defines the shape
+ * of the artifact behind the article.
+ *
+ * @param lang - Target language code
+ * @returns Localised CTA text
+ */
+function getViewTemplateLabel(lang) {
+    const labels = {
+        en: 'View artifact template',
+        sv: 'Visa artefaktmall',
+        da: 'Se artefaktskabelon',
+        no: 'Se artefaktmal',
+        fi: 'Näytä artefaktipohja',
+        de: 'Artefaktvorlage ansehen',
+        fr: 'Voir le modèle d’artefact',
+        es: 'Ver plantilla de artefacto',
+        nl: 'Artefactsjabloon bekijken',
+        ar: 'عرض قالب القطعة',
+        he: 'הצג תבנית פריט',
+        ja: 'アーティファクト テンプレートを表示',
+        ko: '아티팩트 템플릿 보기',
+        zh: '查看构件模板',
+    };
+    return labels[lang] ?? labels.en ?? 'View artifact template';
+}
+/**
+ * Localised "View artifact" CTA used on every Analysis Index card.
+ * Tells the reader the link opens a specific committed artifact from
+ * this article's analysis run on GitHub, providing audit context that
+ * the older generic "View on GitHub" CTA lacked.
+ *
+ * @param lang - Target language code
+ * @returns Localised CTA text
+ */
+function getViewArtifactLabel(lang) {
+    const labels = {
+        en: 'View artifact',
+        sv: 'Visa artefakt',
+        da: 'Se artefakt',
+        no: 'Se artefakt',
+        fi: 'Näytä artefakti',
+        de: 'Artefakt ansehen',
+        fr: 'Voir l’artefact',
+        es: 'Ver artefacto',
+        nl: 'Artefact bekijken',
+        ar: 'عرض القطعة',
+        he: 'הצג פריט',
+        ja: 'アーティファクトを表示',
+        ko: '아티팩트 보기',
+        zh: '查看构件',
+    };
+    return labels[lang] ?? labels.en ?? 'View artifact';
+}
+/**
+ * Replace the `<ul>` block that follows a sub-heading with a card-grid
+ * `<ul class="pi-card-grid">` rendering. Matching is bounded to the
+ * first `<ul>` that appears after `searchFromIdx` and that closes with
+ * `</ul>` — so the function is safe to call on partial HTML.
+ *
+ * @param html - HTML to transform
+ * @param searchFromIdx - Index after which the first `<ul>` is located
+ * @param cardsHtml - Pre-rendered `<li class="pi-card">…</li>` joined by `\n`
+ * @returns `{ html, endIdx }` with the new HTML and the index just after
+ *          the inserted card grid (so successive calls can chain)
+ */
+function replaceFollowingUlWithCardGrid(html, searchFromIdx, cardsHtml) {
+    const ulIdx = html.indexOf('<ul>', searchFromIdx);
+    if (ulIdx === -1)
+        return { html, endIdx: searchFromIdx };
+    const ulEnd = html.indexOf('</ul>', ulIdx);
+    if (ulEnd === -1)
+        return { html, endIdx: searchFromIdx };
+    const replacement = `<ul class="pi-card-grid">\n${cardsHtml}\n        </ul>`;
+    const closeIdx = ulEnd + '</ul>'.length;
+    const next = html.slice(0, ulIdx) + replacement + html.slice(closeIdx);
+    return { html: next, endIdx: ulIdx + replacement.length };
+}
+/**
+ * Replace the rendered Tradecraft References bullet lists with a
+ * `pi-card-grid` of richly described cards (icon, curated title,
+ * curated description, kind-aware CTA). The cards reuse the exact same
+ * class hooks as `political-intelligence.html`, so the site-wide CSS
+ * already styles them — no additional CSS is required.
+ *
+ * After the April-2026 reorder the rendered Markdown emits Artifact
+ * templates as the first sub-heading and Methodologies as the second,
+ * matching how readers encounter the run (artifacts first, methodology
+ * library second). The card upgrade follows the same order so the H3
+ * positions stay aligned with the kind-aware CTA labels.
+ *
+ * Falls back to the original Markdown-rendered list when the expected
+ * structure (H2 → intro paragraph → Artifact-templates sub-heading →
+ * `<ul>` → Methodologies sub-heading → `<ul>`) is missing, so partially
+ * stripped or unusual articles are not silently corrupted.
+ *
+ * @param bodyHtml - The (already-localised) article body HTML
+ * @param lang - Target language code for curated titles/descriptions
+ * @returns Body HTML with the tradecraft section upgraded to cards
+ */
+export function enhanceTradecraftCards(bodyHtml, lang) {
+    const anchorIdx = bodyHtml.indexOf(`id="${TRADECRAFT_SECTION_ID}"`);
+    if (anchorIdx === -1)
+        return bodyHtml;
+    // The next H2 marks the end of the tradecraft section.
+    const nextH2 = bodyHtml.indexOf('<h2 ', anchorIdx + 1);
+    const sectionEnd = nextH2 === -1 ? bodyHtml.length : nextH2;
+    const section = bodyHtml.slice(anchorIdx, sectionEnd);
+    // Harvest the methodology + template links from the rendered HTML.
+    const methodLinks = extractTradecraftLinks(section, 'analysis/methodologies/');
+    const templateLinks = extractTradecraftLinks(section, 'analysis/templates/');
+    if (methodLinks.length === 0 && templateLinks.length === 0)
+        return bodyHtml;
+    const methodCta = getViewMethodologyLabel(lang);
+    const templateCta = getViewTemplateLabel(lang);
+    let next = bodyHtml;
+    // Replace Artifact-templates <ul> first, then the Methodologies <ul>.
+    // Use the returned end index from the first replacement to seed the
+    // search for the second <ul> so we never double-replace.
+    // Note: markdown-it adds `id` and `tabindex` attributes to headings
+    // (`<h3 id="artifact-templates" tabindex="-1">…`), so we search for
+    // `<h3` (no terminator) rather than `<h3>` to match either form.
+    const firstHeadingIdx = next.indexOf('<h3', anchorIdx);
+    if (firstHeadingIdx !== -1 && templateLinks.length > 0) {
+        const templateCards = templateLinks
+            .map((l) => renderTradecraftCard(l, lang, templateCta))
+            .join('\n');
+        const result = replaceFollowingUlWithCardGrid(next, firstHeadingIdx, templateCards);
+        next = result.html;
+    }
+    const secondHeadingSearchStart = next.indexOf(`id="${TRADECRAFT_SECTION_ID}"`);
+    if (secondHeadingSearchStart !== -1 && methodLinks.length > 0) {
+        // Find the second <h3 after the tradecraft anchor (Artifact templates
+        // is the first; Methodologies is the second).
+        const firstH3 = next.indexOf('<h3', secondHeadingSearchStart);
+        if (firstH3 !== -1) {
+            const secondH3 = next.indexOf('<h3', firstH3 + 1);
+            if (secondH3 !== -1) {
+                const methodCards = methodLinks
+                    .map((l) => renderTradecraftCard(l, lang, methodCta))
+                    .join('\n');
+                const result = replaceFollowingUlWithCardGrid(next, secondH3, methodCards);
+                next = result.html;
+            }
+        }
+    }
+    return next;
+}
+/**
+ * Replace the Analysis Index `<table>` with a `pi-card-grid` of cards,
+ * one per included artifact. Each card renders the artifact's curated
+ * localised title + description, the section it contributed to, the
+ * run-relative path as inline `<code>`, and a "View on GitHub" CTA.
+ *
+ * Strategy: parse the rendered table's `<tbody>` rows (each row carries
+ * `[sectionId, <a href="…">stem</a>, runRelPath]`) and re-render the
+ * region between the table's opening wrapper and `</table>` as a card
+ * grid. The wrapping `<div class="table-scroll">` is dropped because
+ * the card grid handles its own responsive layout via flex/grid.
+ *
+ * @param bodyHtml - Article body HTML
+ * @param lang - Target language code
+ * @returns Body HTML with the Analysis Index upgraded to a card grid
+ */
+export function enhanceAnalysisIndexCards(bodyHtml, lang) {
+    const anchorIdx = bodyHtml.indexOf(`id="${MANIFEST_SECTION_ID}"`);
+    if (anchorIdx === -1)
+        return bodyHtml;
+    // Locate the table and its end.
+    const tableIdx = bodyHtml.indexOf('<table>', anchorIdx);
+    if (tableIdx === -1)
+        return bodyHtml;
+    const tableEnd = bodyHtml.indexOf('</table>', tableIdx);
+    if (tableEnd === -1)
+        return bodyHtml;
+    const tableHtml = bodyHtml.slice(tableIdx, tableEnd + '</table>'.length);
+    const rows = parseAnalysisIndexRows(tableHtml);
+    if (rows.length === 0)
+        return bodyHtml;
+    const cards = rows.map((row) => renderAnalysisIndexCard(row, lang)).join('\n');
+    // Walk back to the start of the wrapping <div class="table-scroll"> if
+    // present, so we replace the responsive wrapper too.
+    const wrapperOpen = bodyHtml.lastIndexOf('<div class="table-scroll"', tableIdx);
+    const replaceFrom = wrapperOpen !== -1 && wrapperOpen > anchorIdx ? wrapperOpen : tableIdx;
+    // Walk forward past the matching </div> when we kicked off from the
+    // wrapper, otherwise stop right after </table>.
+    let replaceTo = tableEnd + '</table>'.length;
+    if (wrapperOpen !== -1 && wrapperOpen > anchorIdx) {
+        const wrapperClose = bodyHtml.indexOf('</div>', tableEnd);
+        if (wrapperClose !== -1)
+            replaceTo = wrapperClose + '</div>'.length;
+    }
+    const replacement = `<ul class="pi-card-grid analysis-index-grid">\n${cards}\n        </ul>`;
+    return bodyHtml.slice(0, replaceFrom) + replacement + bodyHtml.slice(replaceTo);
+}
+/**
+ * Parse the `<tbody>` rows of the rendered Analysis Index table. Each
+ * row has the shape `<tr><td>section-id</td><td><a href="…">stem</a>
+ * </td><td><code>relPath</code></td></tr>`.
+ *
+ * @param tableHtml - Slice of HTML from `<table>` to `</table>`
+ * @returns Parsed rows (skipping malformed ones)
+ */
+function parseAnalysisIndexRows(tableHtml) {
+    const out = [];
+    let cursor = 0;
+    while (cursor < tableHtml.length) {
+        const trIdx = tableHtml.indexOf('<tr>', cursor);
+        if (trIdx === -1)
+            break;
+        const trEnd = tableHtml.indexOf('</tr>', trIdx);
+        if (trEnd === -1)
+            break;
+        const row = tableHtml.slice(trIdx, trEnd);
+        cursor = trEnd + '</tr>'.length;
+        // Skip the header row (which only has <th> not <td>).
+        if (row.indexOf('<td>') === -1)
+            continue;
+        const cells = parseRowCells(row);
+        if (cells.length < 3)
+            continue;
+        const anchorMatch = parseAnchor(cells[1] ?? '');
+        if (!anchorMatch)
+            continue;
+        const runRelPath = stripCodeWrapper(cells[2] ?? '');
+        out.push({
+            sectionId: (cells[0] ?? '').trim(),
+            anchorText: anchorMatch.text,
+            href: anchorMatch.href,
+            runRelPath,
+        });
+    }
+    return out;
+}
+/**
+ * Extract the `<td>…</td>` cell contents from a single `<tr>…</tr>`
+ * fragment. Uses `indexOf` to avoid backtracking.
+ *
+ * @param row - HTML for one row (no `</tr>` terminator required)
+ * @returns Array of inner-HTML strings, one per `<td>`
+ */
+function parseRowCells(row) {
+    const cells = [];
+    let cursor = 0;
+    while (cursor < row.length) {
+        const tdIdx = row.indexOf('<td>', cursor);
+        if (tdIdx === -1)
+            break;
+        const tdEnd = row.indexOf('</td>', tdIdx);
+        if (tdEnd === -1)
+            break;
+        cells.push(row.slice(tdIdx + '<td>'.length, tdEnd));
+        cursor = tdEnd + '</td>'.length;
+    }
+    return cells;
+}
+/**
+ * Parse a single `<a href="…">text</a>` token out of a cell. Returns
+ * `null` when the cell does not contain an anchor (e.g. a plain string).
+ *
+ * @param cell - Inner-HTML of the `<td>` cell
+ * @returns Parsed anchor or `null`
+ */
+function parseAnchor(cell) {
+    const aIdx = cell.indexOf('<a ');
+    if (aIdx === -1)
+        return null;
+    const hrefIdx = cell.indexOf('href="', aIdx);
+    if (hrefIdx === -1)
+        return null;
+    const urlStart = hrefIdx + 'href="'.length;
+    const urlEnd = cell.indexOf('"', urlStart);
+    if (urlEnd === -1)
+        return null;
+    const closeOpenTag = cell.indexOf('>', urlEnd);
+    if (closeOpenTag === -1)
+        return null;
+    const closeIdx = cell.indexOf('</a>', closeOpenTag);
+    if (closeIdx === -1)
+        return null;
+    return {
+        href: cell.slice(urlStart, urlEnd),
+        text: cell.slice(closeOpenTag + 1, closeIdx),
+    };
+}
+/**
+ * Strip the `<code>…</code>` wrapper added by the Markdown renderer
+ * around the run-relative path cell.
+ *
+ * @param cell - Cell inner-HTML (possibly `<code>foo.md</code>`)
+ * @returns Plain text without code formatting
+ */
+function stripCodeWrapper(cell) {
+    const start = cell.indexOf('<code>');
+    if (start === -1)
+        return cell.trim();
+    const end = cell.indexOf('</code>', start);
+    if (end === -1)
+        return cell.trim();
+    return cell.slice(start + '<code>'.length, end).trim();
+}
+/**
+ * Render one Analysis Index card. Reuses the `pi-card` class hooks so
+ * the card-grid sits naturally next to the methodology / template
+ * cards in the same article.
+ *
+ * @param row - Parsed Analysis Index row
+ * @param lang - Target language code
+ * @returns HTML fragment for one `<li class="pi-card">…</li>`
+ */
+function renderAnalysisIndexCard(row, lang) {
+    const info = getArtifactInfo(row.runRelPath, lang);
+    const stem = row.runRelPath.split('/').pop()?.replace(/\.md$/i, '') ?? row.runRelPath;
+    const icon = getStemIcon(stem);
+    // Reuse the section-title localisation already used by the TOC so the
+    // "Section: …" badge reads naturally in every language.
+    const sectionLabel = getLocalizedTocTitle(row.sectionId, row.sectionId, lang);
+    // Drop the redundant `<code>analysis/.../foo.md</code>` filename row —
+    // the curated title + curated description plus the section badge
+    // already convey what the artifact is and where it sits in the
+    // article. The kind-aware "View artifact" CTA tells the reader the
+    // link opens the underlying committed artifact on GitHub.
+    return [
+        `          <li class="pi-card">`,
+        `            <a class="pi-card__link" href="${escapeHTML(row.href)}" rel="noopener external" target="_blank">`,
+        `              <span class="pi-card__icon" aria-hidden="true">${icon}</span>`,
+        `              <span class="pi-card__body">`,
+        `                <span class="pi-card__title">${escapeHTML(info.title)}</span>`,
+        `                <span class="pi-card__desc">${escapeHTML(info.description)}</span>`,
+        `                <span class="pi-card__meta"><span class="pi-card__section-badge">${escapeHTML(sectionLabel)}</span></span>`,
+        `                <span class="pi-card__cta">${escapeHTML(getViewArtifactLabel(lang))} <span aria-hidden="true">↗</span></span>`,
+        `              </span>`,
+        `            </a>`,
+        `          </li>`,
+    ].join('\n');
+}
 /**
  * Render the full article HTML document with the shared chrome.
  *

package/scripts/aggregator/reader-intelligence-guide.d.ts

@@ -22,17 +22,38 @@ export declare const READER_GUIDE_COL_NEED_LABELS: LanguageMap;
 export declare const READER_GUIDE_COL_VALUE_LABELS: LanguageMap;
 /** Table header: "Source artifact" */
 export declare const READER_GUIDE_COL_SOURCE_LABELS: LanguageMap;
+/**
+ * Look up the visual icon for a known article section.
+ *
+ * Exposed so the article-level Table-of-Contents (`buildArticleToc`)
+ * can render the same emoji that the Reader Intelligence Guide uses
+ * for each section, keeping the two navigation surfaces visually
+ * consistent. Unknown section IDs (e.g. ad-hoc `supplementary-…` or
+ * appendix anchors) fall back to a generic 📎 paperclip.
+ *
+ * @param sectionId - Anchor id of the section (e.g. `section-risk`)
+ * @returns Single emoji glyph used as a `guide-icon`
+ */
+export declare function getReaderGuideSectionIcon(sectionId: string): string;
 /**
  * Build a translated Reader Intelligence Guide as an HTML section.
  * Emits exactly one component with `data-component="reader-intelligence-guide"`
  * for de-duplication detection by E2E tests.
  *
+ * The guide renders one row per emitted article section that has a
+ * curated reader-need translation (see {@link READER_GUIDE_ROWS}). The
+ * `included` list is no longer surfaced — the previous "source artifact"
+ * column duplicated the per-section navigation that the Analysis Index
+ * appendix already presents, and clutters the headline reader lens. The
+ * parameter is kept on the signature for backward compatibility with
+ * callers that may pre-compute the run manifest.
+ *
  * @param lang - Target language code
  * @param sections - Emitted section TOC entries, in document order
- * @param included - Included artifacts, used to name each section's source
+ * @param _included - (Unused) Included artifacts; kept for API stability
  * @returns HTML fragment for the guide, or empty string if no rows match
  */
-export declare function buildReaderIntelligenceGuideHtml(lang: LanguageCode, sections: readonly TocSection[], included: readonly IncludedArtifact[]): string;
+export declare function buildReaderIntelligenceGuideHtml(lang: LanguageCode, sections: readonly TocSection[], _included?: readonly IncludedArtifact[]): string;
 /**
  * Strip an AI-authored Reader Intelligence Guide section from rendered HTML.
  * Looks for H2 headings with id="reader-intelligence-guide" and removes

package/scripts/aggregator/reader-intelligence-guide.js

@@ -363,6 +363,312 @@ const READER_GUIDE_ROWS = {
             zh: '政策、机构、联盟、沟通和执行风险登记册',
         },
     },
+    'section-actors-forces': {
+        need: {
+            en: 'Actors & forces',
+            sv: 'Aktörer & krafter',
+            da: 'Aktører & kræfter',
+            no: 'Aktører & krefter',
+            fi: 'Toimijat & voimat',
+            de: 'Akteure & Kräfte',
+            fr: 'Acteurs & forces',
+            es: 'Actores & fuerzas',
+            nl: 'Actoren & krachten',
+            ar: 'الفاعلون والقوى',
+            he: 'שחקנים וכוחות',
+            ja: 'アクターと力学',
+            ko: '행위자 & 세력',
+            zh: '行动者与力量',
+        },
+        value: {
+            en: 'who is driving the story, what political forces line up behind them, and which institutional levers they can pull',
+            sv: 'vem som driver händelsen, vilka politiska krafter står bakom och vilka institutionella spakar de kan dra',
+            da: 'hvem der driver historien, hvilke politiske kræfter står bag, og hvilke institutionelle håndtag de kan trække',
+            no: 'hvem som driver saken, hvilke politiske krefter står bak, og hvilke institusjonelle spaker de kan trekke',
+            fi: 'kuka ohjaa tarinaa, mitkä poliittiset voimat ovat takana ja mitä institutionaalisia vipuja he voivat käyttää',
+            de: 'wer die Geschichte vorantreibt, welche politischen Kräfte dahinterstehen und welche institutionellen Hebel sie ziehen können',
+            fr: "qui pilote l'histoire, quelles forces politiques sont alignées derrière, et quels leviers institutionnels ils peuvent actionner",
+            es: 'quién impulsa la historia, qué fuerzas políticas están detrás y qué palancas institucionales pueden accionar',
+            nl: 'wie het verhaal aandrijft, welke politieke krachten erachter staan en welke institutionele hefbomen ze kunnen overhalen',
+            ar: 'من يقود القصة، وما القوى السياسية المصطفة خلفه، وأي روافع مؤسسية يمكنهم تحريكها',
+            he: 'מי מניע את הסיפור, אילו כוחות פוליטיים מאחוריו, ואילו מנופים מוסדיים הם יכולים להפעיל',
+            ja: 'ストーリーを動かしているのは誰か、その背後にある政治的勢力、そして彼らが引ける制度的レバー',
+            ko: '누가 이야기를 주도하는지, 그 뒤에 어떤 정치적 세력이 있는지, 그리고 어떤 제도적 지렛대를 당길 수 있는지',
+            zh: '谁在推动故事、哪些政治力量在其背后、以及他们可以拉动哪些制度杠杆',
+        },
+    },
+    'section-threat': {
+        need: {
+            en: 'Threat landscape',
+            sv: 'Hotlandskap',
+            da: 'Trussellandskab',
+            no: 'Trussellandskap',
+            fi: 'Uhkamaisema',
+            de: 'Bedrohungslandschaft',
+            fr: 'Paysage des menaces',
+            es: 'Panorama de amenazas',
+            nl: 'Dreigingslandschap',
+            ar: 'مشهد التهديدات',
+            he: 'נוף האיומים',
+            ja: '脅威ランドスケープ',
+            ko: '위협 환경',
+            zh: '威胁态势',
+        },
+        value: {
+            en: 'hostile actors, attack vectors, consequence trees, and the legislative-disruption pathways the article tracks',
+            sv: 'fientliga aktörer, attackvektorer, konsekvensträd och de lagstiftningsstörningsvägar artikeln spårar',
+            da: 'fjendtlige aktører, angrebsvektorer, konsekvenstræer og de lovgivningsforstyrrelsesveje artiklen følger',
+            no: 'fiendtlige aktører, angrepsvektorer, konsekvenstrær og lovgivningsforstyrrelsesveiene artikkelen sporer',
+            fi: 'vihamieliset toimijat, hyökkäysvektorit, seurauspuut ja lainsäädännön häiriöpolut, joita artikkeli seuraa',
+            de: 'feindliche Akteure, Angriffsvektoren, Konsequenzbäume und die Gesetzgebungsstörungspfade, die der Artikel verfolgt',
+            fr: "acteurs hostiles, vecteurs d'attaque, arbres de conséquences et voies de perturbation législative que l'article suit",
+            es: 'actores hostiles, vectores de ataque, árboles de consecuencias y las vías de disrupción legislativa que sigue el artículo',
+            nl: 'vijandige actoren, aanvalsvectoren, gevolgenbomen en de wetgevingsverstoringspaden die het artikel volgt',
+            ar: 'الجهات المعادية وناقلات الهجوم وأشجار العواقب ومسارات التعطيل التشريعي التي يتتبعها المقال',
+            he: 'שחקנים עוינים, ווקטורי תקיפה, עצי השלכה ונתיבי שיבוש החקיקה שהמאמר עוקב אחריהם',
+            ja: '敵対的アクター、攻撃ベクトル、結果ツリー、および記事が追跡する立法阻害経路',
+            ko: '적대적 행위자, 공격 벡터, 결과 트리, 그리고 기사가 추적하는 입법 교란 경로',
+            zh: '敌对行为者、攻击向量、后果树以及文章追踪的立法干扰路径',
+        },
+    },
+    'section-forward-projection': {
+        need: {
+            en: 'What to watch',
+            sv: 'Vad att bevaka',
+            da: 'Hvad man skal følge',
+            no: 'Hva å følge med på',
+            fi: 'Mitä seurata',
+            de: 'Was zu beobachten ist',
+            fr: 'À surveiller',
+            es: 'Qué vigilar',
+            nl: 'Wat te volgen',
+            ar: 'ما يجب مراقبته',
+            he: 'מה לעקוב אחריו',
+            ja: '注目ポイント',
+            ko: '주목할 사항',
+            zh: '关注要点',
+        },
+        value: {
+            en: 'dated trigger events, parliamentary-calendar dependencies, and the legislative-pipeline forecast',
+            sv: 'daterade triggers, beroenden i parlamentskalendern och prognosen för lagstiftningspipelinen',
+            da: 'daterede triggers, parlamentskalender-afhængigheder og prognosen for lovgivningspipelinen',
+            no: 'daterte triggers, parlamentskalender-avhengigheter og prognosen for lovgivningspipelinen',
+            fi: 'päivätyt laukaisimet, parlamentin kalenterin riippuvuudet ja lainsäädäntöputken ennuste',
+            de: 'datierte Auslöseereignisse, Abhängigkeiten vom Parlamentskalender und die Prognose der Gesetzgebungspipeline',
+            fr: 'événements déclencheurs datés, dépendances du calendrier parlementaire et prévision du pipeline législatif',
+            es: 'eventos desencadenantes fechados, dependencias del calendario parlamentario y previsión del pipeline legislativo',
+            nl: 'gedateerde triggergebeurtenissen, afhankelijkheden van de parlementaire agenda en de voorspelling van de wetgevingspijplijn',
+            ar: 'أحداث محفزة مؤرخة، تبعيات الجدول البرلماني، وتوقعات خط الأنابيب التشريعي',
+            he: 'אירועי טריגר מתוארכים, תלויות לוח הפרלמנט ותחזית צינור החקיקה',
+            ja: '日付付きのトリガーイベント、議会カレンダーの依存関係、立法パイプラインの予測',
+            ko: '날짜가 지정된 트리거 이벤트, 의회 일정 의존성, 입법 파이프라인 예측',
+            zh: '标注日期的触发事件、议会日历依赖关系以及立法流程预测',
+        },
+    },
+    'section-electoral-arc': {
+        need: {
+            en: 'Electoral arc & mandate',
+            sv: 'Valbåge & mandat',
+            da: 'Valgbue & mandat',
+            no: 'Valgbue & mandat',
+            fi: 'Vaalikaari & mandaatti',
+            de: 'Wahlbogen & Mandat',
+            fr: 'Arc électoral & mandat',
+            es: 'Arco electoral & mandato',
+            nl: 'Verkiezingsboog & mandaat',
+            ar: 'القوس الانتخابي والتفويض',
+            he: 'קשת בחירות ומנדט',
+            ja: '選挙アークとマンデート',
+            ko: '선거 아크 & 위임',
+            zh: '选举弧线与任期',
+        },
+        value: {
+            en: 'where in the term the story sits, mandate-fulfilment scoring, seat projection, and the presidency-trio context',
+            sv: 'var i mandatperioden händelsen befinner sig, mandatuppfyllelsescoring, mandatprojektion och ordförandetrio-kontexten',
+            da: 'hvor i valgperioden historien ligger, mandatopfyldelsesscoring, mandatprojektion og formandstrio-konteksten',
+            no: 'hvor i valgperioden saken ligger, mandatoppfyllelsesscoring, mandatprojeksjon og formannskapstrio-konteksten',
+            fi: 'mihin kohtaan kautta tarina sijoittuu, mandaatin täyttymisen pisteytys, paikkaennuste ja puheenjohtajatrion konteksti',
+            de: 'wo im Mandat die Geschichte liegt, Mandatserfüllungs-Scoring, Sitzprojektion und Präsidentschaftstrio-Kontext',
+            fr: "où en est l'histoire dans le mandat, notation de l'exécution du mandat, projection des sièges et contexte du trio présidentiel",
+            es: 'dónde se sitúa la historia en el mandato, puntuación de cumplimiento del mandato, proyección de escaños y contexto del trío presidencial',
+            nl: 'waar het verhaal zich in het mandaat bevindt, scoring mandaatuitvoering, zetelprojectie en context van de voorzittersdrieluik',
+            ar: 'موقع القصة في الولاية، تقييم تنفيذ التفويض، توقعات المقاعد، وسياق الترويكا الرئاسية',
+            he: 'איפה בכהונה הסיפור ממוקם, ניקוד מילוי המנדט, תחזית מושבים, והקשר של שלישיית הנשיאות',
+            ja: '物語が任期のどこに位置するか、マンデート遂行スコア、議席予測、議長トリオの文脈',
+            ko: '이야기가 임기의 어디에 위치하는지, 위임 이행 점수, 의석 예측, 의장 트리오 맥락',
+            zh: '故事在任期中所处的位置、任期履行评分、席位预测以及主席三人组的背景',
+        },
+    },
+    'section-pestle-context': {
+        need: {
+            en: 'PESTLE & structural context',
+            sv: 'PESTLE & strukturell kontext',
+            da: 'PESTLE & strukturel kontekst',
+            no: 'PESTLE & strukturell kontekst',
+            fi: 'PESTLE & rakenteellinen konteksti',
+            de: 'PESTLE & struktureller Kontext',
+            fr: 'PESTLE & contexte structurel',
+            es: 'PESTLE & contexto estructural',
+            nl: 'PESTLE & structurele context',
+            ar: 'PESTLE والسياق الهيكلي',
+            he: 'PESTLE והקשר מבני',
+            ja: 'PESTLEと構造的コンテキスト',
+            ko: 'PESTLE & 구조적 맥락',
+            zh: 'PESTLE与结构性背景',
+        },
+        value: {
+            en: 'political, economic, social, technological, legal, and environmental forces plus the historical baseline',
+            sv: 'politiska, ekonomiska, sociala, tekniska, juridiska och miljömässiga krafter samt historisk baslinje',
+            da: 'politiske, økonomiske, sociale, teknologiske, juridiske og miljømæssige kræfter samt historisk baseline',
+            no: 'politiske, økonomiske, sosiale, teknologiske, juridiske og miljømessige krefter pluss historisk grunnlinje',
+            fi: 'poliittiset, taloudelliset, sosiaaliset, teknologiset, juridiset ja ympäristötekijät sekä historiallinen lähtötaso',
+            de: 'politische, wirtschaftliche, soziale, technologische, rechtliche und Umweltkräfte plus historische Baseline',
+            fr: 'forces politiques, économiques, sociales, technologiques, juridiques et environnementales plus la base historique',
+            es: 'fuerzas políticas, económicas, sociales, tecnológicas, legales y ambientales más la línea base histórica',
+            nl: 'politieke, economische, sociale, technologische, juridische en milieukrachten plus de historische basislijn',
+            ar: 'القوى السياسية والاقتصادية والاجتماعية والتكنولوجية والقانونية والبيئية بالإضافة إلى الأساس التاريخي',
+            he: 'כוחות פוליטיים, כלכליים, חברתיים, טכנולוגיים, משפטיים וסביבתיים בתוספת קו הבסיס ההיסטורי',
+            ja: '政治・経済・社会・技術・法律・環境の各要因と歴史的ベースライン',
+            ko: '정치, 경제, 사회, 기술, 법률, 환경 요인과 역사적 기준선',
+            zh: '政治、经济、社会、技术、法律和环境力量加上历史基准',
+        },
+    },
+    'section-continuity': {
+        need: {
+            en: 'Cross-run continuity',
+            sv: 'Kontinuitet mellan körningar',
+            da: 'Kryds-kørsels-kontinuitet',
+            no: 'Kontinuitet mellom kjøringer',
+            fi: 'Ajojen välinen jatkuvuus',
+            de: 'Laufübergreifende Kontinuität',
+            fr: 'Continuité inter-exécutions',
+            es: 'Continuidad entre ejecuciones',
+            nl: 'Continuïteit tussen runs',
+            ar: 'استمرارية عبر التشغيلات',
+            he: 'רציפות בין הרצות',
+            ja: 'クロスラン継続性',
+            ko: '교차 실행 연속성',
+            zh: '跨运行连续性',
+        },
+        value: {
+            en: 'how this run links to prior sessions, what changed, and how confidence shifted between runs',
+            sv: 'hur denna körning kopplar till tidigare sessioner, vad som förändrats och hur förtroendet skiftat mellan körningar',
+            da: 'hvordan denne kørsel forbinder til tidligere sessioner, hvad der er ændret, og hvordan tilliden har skiftet mellem kørsler',
+            no: 'hvordan denne kjøringen kobler til tidligere økter, hva som er endret, og hvordan tilliten har skiftet mellom kjøringer',
+            fi: 'miten tämä ajo kytkeytyy aiempiin istuntoihin, mikä on muuttunut ja miten luottamus on siirtynyt ajojen välillä',
+            de: 'wie dieser Lauf mit früheren Sitzungen verknüpft ist, was sich geändert hat und wie sich das Vertrauen zwischen Läufen verschoben hat',
+            fr: "comment cette exécution se relie aux sessions précédentes, ce qui a changé, et comment la confiance s'est déplacée entre les exécutions",
+            es: 'cómo se vincula esta ejecución con sesiones anteriores, qué cambió y cómo se desplazó la confianza entre ejecuciones',
+            nl: 'hoe deze run aansluit op eerdere sessies, wat er is veranderd en hoe het vertrouwen tussen runs is verschoven',
+            ar: 'كيفية ارتباط هذا التشغيل بالجلسات السابقة، وما الذي تغير، وكيف تحولت الثقة بين عمليات التشغيل',
+            he: 'כיצד הרצה זו מתקשרת להפעלות קודמות, מה השתנה, וכיצד הביטחון השתנה בין הרצות',
+            ja: 'この実行が以前のセッションとどう繋がるか、何が変わったか、実行間で信頼性がどう変動したか',
+            ko: '이 실행이 이전 세션과 어떻게 연결되는지, 무엇이 변경되었는지, 실행 간에 신뢰도가 어떻게 변화했는지',
+            zh: '本次运行如何与先前会话关联、变化了什么以及置信度在运行之间如何变化',
+        },
+    },
+    'section-extended-intel': {
+        need: {
+            en: 'Extended intelligence',
+            sv: 'Utökad underrättelse',
+            da: 'Udvidet efterretning',
+            no: 'Utvidet etterretning',
+            fi: 'Laajennettu tiedustelu',
+            de: 'Erweiterte Aufklärung',
+            fr: 'Renseignement étendu',
+            es: 'Inteligencia ampliada',
+            nl: 'Uitgebreide inlichtingen',
+            ar: 'استخبارات موسعة',
+            he: 'מודיעין מורחב',
+            ja: '拡張インテリジェンス',
+            ko: '확장 인텔리전스',
+            zh: '扩展情报',
+        },
+        value: {
+            en: "devil's-advocate critique, comparative international parallels, historical precedents, and media-framing analysis",
+            sv: 'djävulens-advokat-kritik, jämförande internationella paralleller, historiska prejudikat och mediaframing-analys',
+            da: 'djævlens-advokat-kritik, sammenlignende internationale paralleller, historiske præcedenser og medieframing-analyse',
+            no: 'djevelens advokat-kritikk, sammenlignende internasjonale paralleller, historiske presedenser og mediaframing-analyse',
+            fi: 'paholaisen asianajaja -kritiikki, kansainväliset vertailut, historialliset ennakkotapaukset ja media-analyysi',
+            de: 'Devil-Advocate-Kritik, vergleichende internationale Parallelen, historische Präzedenzfälle und Medien-Framing-Analyse',
+            fr: "critique de l'avocat du diable, parallèles internationaux comparatifs, précédents historiques et analyse du cadrage médiatique",
+            es: 'crítica de abogado del diablo, paralelismos internacionales comparativos, precedentes históricos y análisis de encuadre mediático',
+            nl: 'devils-advocate-kritiek, vergelijkende internationale parallellen, historische precedenten en media-framinganalyse',
+            ar: 'نقد محامي الشيطان، توازيات دولية مقارنة، سوابق تاريخية، وتحليل التأطير الإعلامي',
+            he: 'ביקורת פרקליט השטן, מקבילות בינלאומיות השוואתיות, תקדימים היסטוריים וניתוח מסגור תקשורתי',
+            ja: '悪魔の代弁者批評、比較国際パラレル、歴史的先例、メディアフレーミング分析',
+            ko: '악마의 변호인 비판, 비교 국제 평행 사례, 역사적 선례, 미디어 프레이밍 분석',
+            zh: '魔鬼代言人批评、比较国际平行案例、历史先例和媒体框架分析',
+        },
+    },
+    'section-mcp-reliability': {
+        need: {
+            en: 'MCP data reliability',
+            sv: 'MCP-datatillförlitlighet',
+            da: 'MCP-datapålidelighed',
+            no: 'MCP-datapålitelighet',
+            fi: 'MCP-datan luotettavuus',
+            de: 'MCP-Datenzuverlässigkeit',
+            fr: 'Fiabilité des données MCP',
+            es: 'Fiabilidad de datos MCP',
+            nl: 'Betrouwbaarheid MCP-gegevens',
+            ar: 'موثوقية بيانات MCP',
+            he: 'אמינות נתוני MCP',
+            ja: 'MCPデータ信頼性',
+            ko: 'MCP 데이터 신뢰성',
+            zh: 'MCP数据可靠性',
+        },
+        value: {
+            en: 'which feeds were healthy, which were degraded, and how the data limitations bound the conclusions',
+            sv: 'vilka flöden var friska, vilka var degraderade och hur databegränsningar binder slutsatserna',
+            da: 'hvilke feeds var sunde, hvilke var forringede, og hvordan databegrænsningerne binder konklusionerne',
+            no: 'hvilke feeds var sunne, hvilke var degradert, og hvordan databegrensninger binder konklusjonene',
+            fi: 'mitkä syötteet olivat terveitä, mitkä huonontuneita ja miten datarajoitukset rajaavat johtopäätöksiä',
+            de: 'welche Feeds gesund waren, welche degradiert, und wie die Datengrenzen die Schlussfolgerungen binden',
+            fr: 'quels flux étaient sains, lesquels étaient dégradés et comment les limites de données contraignent les conclusions',
+            es: 'qué fuentes estaban sanas, cuáles degradadas y cómo las limitaciones de datos restringen las conclusiones',
+            nl: 'welke feeds gezond waren, welke gedegradeerd, en hoe databeperkingen de conclusies inperken',
+            ar: 'أي الموجزات كانت صحية، وأيها متدهورة، وكيف تقيد قيود البيانات الاستنتاجات',
+            he: 'אילו פידים היו תקינים, אילו היו פגומים, וכיצד מגבלות הנתונים תוחמות את המסקנות',
+            ja: 'どのフィードが健全だったか、どれが劣化していたか、そしてデータの制約が結論をどう制限するか',
+            ko: '어떤 피드가 건강했고, 어떤 피드가 저하되었으며, 데이터 제약이 결론을 어떻게 제한하는지',
+            zh: '哪些数据源健康、哪些已降级，以及数据限制如何约束结论',
+        },
+    },
+    'section-quality-reflection': {
+        need: {
+            en: 'Analytical quality & reflection',
+            sv: 'Analytisk kvalitet & reflektion',
+            da: 'Analytisk kvalitet & refleksion',
+            no: 'Analytisk kvalitet & refleksjon',
+            fi: 'Analyyttinen laatu & pohdinta',
+            de: 'Analytische Qualität & Reflexion',
+            fr: 'Qualité analytique & réflexion',
+            es: 'Calidad analítica & reflexión',
+            nl: 'Analytische kwaliteit & reflectie',
+            ar: 'الجودة التحليلية والتأمل',
+            he: 'איכות אנליטית ורפלקציה',
+            ja: '分析品質と内省',
+            ko: '분석 품질 & 성찰',
+            zh: '分析质量与反思',
+        },
+        value: {
+            en: 'self-assessment scores, methodology audit, structured-analytic-techniques used, and known limitations',
+            sv: 'självvärderingspoäng, metodologirevision, strukturerade analystekniker som använts och kända begränsningar',
+            da: 'selvevalueringsresultater, metoderevision, anvendte strukturerede analyseteknikker og kendte begrænsninger',
+            no: 'selvvurderingsskår, metoderevisjon, brukte strukturerte analyseteknikker og kjente begrensninger',
+            fi: 'itsearviointipisteet, metodologian auditointi, käytetyt strukturoidut analyysitekniikat ja tunnetut rajoitukset',
+            de: 'Selbsteinschätzungs-Scores, Methodologie-Audit, eingesetzte strukturierte Analysetechniken und bekannte Einschränkungen',
+            fr: "scores d'auto-évaluation, audit méthodologique, techniques analytiques structurées utilisées et limitations connues",
+            es: 'puntuaciones de autoevaluación, auditoría metodológica, técnicas analíticas estructuradas utilizadas y limitaciones conocidas',
+            nl: 'zelfevaluatiescores, methodologie-audit, gebruikte gestructureerde analytische technieken en bekende beperkingen',
+            ar: 'درجات التقييم الذاتي، تدقيق المنهجية، تقنيات التحليل المنظمة المستخدمة، والقيود المعروفة',
+            he: 'ציוני הערכה עצמית, ביקורת מתודולוגית, טכניקות אנליטיות מובנות שנעשה בהן שימוש ומגבלות ידועות',
+            ja: '自己評価スコア、方法論監査、使用された構造化分析技法、および既知の制約',
+            ko: '자가 평가 점수, 방법론 감사, 사용된 구조화된 분석 기법 및 알려진 한계',
+            zh: '自我评估分数、方法论审计、使用的结构化分析技术和已知限制',
+        },
+    },
 };
 /* ─── Section icons ─────────────────────────────────────────────── */
 /** Visual icons for each reader guide section to improve scannability. */
@@ -370,24 +676,56 @@ const SECTION_ICONS = {
     'section-executive-brief': '📋',
     'section-synthesis': '🔗',
     'section-significance': '⚖️',
+    'section-actors-forces': '🎭',
     'section-coalitions-voting': '🤝',
     'section-stakeholder-map': '👥',
     'section-economic-context': '💶',
-    'section-scenarios': '🔮',
     'section-risk': '⚠️',
+    'section-threat': '🛡️',
+    'section-scenarios': '🔮',
+    'section-forward-projection': '🔭',
+    'section-electoral-arc': '🗳️',
+    'section-pestle-context': '🌍',
+    'section-continuity': '🔁',
+    'section-extended-intel': '🧠',
+    'section-mcp-reliability': '📡',
+    'section-quality-reflection': '🪞',
 };
+/**
+ * Look up the visual icon for a known article section.
+ *
+ * Exposed so the article-level Table-of-Contents (`buildArticleToc`)
+ * can render the same emoji that the Reader Intelligence Guide uses
+ * for each section, keeping the two navigation surfaces visually
+ * consistent. Unknown section IDs (e.g. ad-hoc `supplementary-…` or
+ * appendix anchors) fall back to a generic 📎 paperclip.
+ *
+ * @param sectionId - Anchor id of the section (e.g. `section-risk`)
+ * @returns Single emoji glyph used as a `guide-icon`
+ */
+export function getReaderGuideSectionIcon(sectionId) {
+    return SECTION_ICONS[sectionId] ?? '📎';
+}
 /* ─── HTML builder ───────────────────────────────────────────────── */
 /**
  * Build a translated Reader Intelligence Guide as an HTML section.
  * Emits exactly one component with `data-component="reader-intelligence-guide"`
  * for de-duplication detection by E2E tests.
  *
+ * The guide renders one row per emitted article section that has a
+ * curated reader-need translation (see {@link READER_GUIDE_ROWS}). The
+ * `included` list is no longer surfaced — the previous "source artifact"
+ * column duplicated the per-section navigation that the Analysis Index
+ * appendix already presents, and clutters the headline reader lens. The
+ * parameter is kept on the signature for backward compatibility with
+ * callers that may pre-compute the run manifest.
+ *
  * @param lang - Target language code
  * @param sections - Emitted section TOC entries, in document order
- * @param included - Included artifacts, used to name each section's source
+ * @param _included - (Unused) Included artifacts; kept for API stability
  * @returns HTML fragment for the guide, or empty string if no rows match
  */
-export function buildReaderIntelligenceGuideHtml(lang, sections, included) {
+export function buildReaderIntelligenceGuideHtml(lang, sections, _included = []) {
     const dir = getTextDirection(lang);
     const rows = [];
     for (const section of sections) {
@@ -396,10 +734,8 @@ export function buildReaderIntelligenceGuideHtml(lang, sections, included) {
             continue;
         const need = getLocalizedString(rowData.need, lang);
         const value = getLocalizedString(rowData.value, lang);
-        const source = included.find((artifact) => artifact.sectionId === section.id)?.runRelPath;
-        const sourceLabel = source ? `<code>${escapeHTML(source)}</code>` : escapeHTML(section.title);
-        const sectionIcon = SECTION_ICONS[section.id] ?? '📎';
-        rows.push(`<tr><td><span class="guide-icon" aria-hidden="true">${sectionIcon}</span> <a href="#${escapeHTML(section.id)}">${escapeHTML(need)}</a></td><td>${escapeHTML(value)}</td><td>${sourceLabel}</td></tr>`);
+        const sectionIcon = getReaderGuideSectionIcon(section.id);
+        rows.push(`<tr><td><span class="guide-icon" aria-hidden="true">${sectionIcon}</span> <a href="#${escapeHTML(section.id)}">${escapeHTML(need)}</a></td><td>${escapeHTML(value)}</td></tr>`);
     }
     if (rows.length === 0)
         return '';
@@ -407,14 +743,13 @@ export function buildReaderIntelligenceGuideHtml(lang, sections, included) {
     const intro = getLocalizedString(READER_GUIDE_INTRO_LABELS, lang);
     const colNeed = getLocalizedString(READER_GUIDE_COL_NEED_LABELS, lang);
     const colValue = getLocalizedString(READER_GUIDE_COL_VALUE_LABELS, lang);
-    const colSource = getLocalizedString(READER_GUIDE_COL_SOURCE_LABELS, lang);
     return `<section id="${READER_GUIDE_SECTION_ID}" data-component="reader-intelligence-guide" aria-label="${escapeHTML(title)}"${dir === 'rtl' ? ' dir="rtl"' : ''}>
 <h2 id="${READER_GUIDE_SECTION_ID}-heading"><span class="guide-icon" aria-hidden="true">🧭</span> ${escapeHTML(title)}</h2>
 <p class="reader-guide-intro">${escapeHTML(intro)}</p>
 <div class="table-scroll" role="region" tabindex="0" aria-labelledby="${READER_GUIDE_SECTION_ID}-heading">
 <table class="reader-guide-table">
 <caption class="sr-only">${escapeHTML(title)}</caption>
-<thead><tr><th scope="col">${escapeHTML(colNeed)}</th><th scope="col">${escapeHTML(colValue)}</th><th scope="col">${escapeHTML(colSource)}</th></tr></thead>
+<thead><tr><th scope="col">${escapeHTML(colNeed)}</th><th scope="col">${escapeHTML(colValue)}</th></tr></thead>
 <tbody>
 ${rows.join('\n')}
 </tbody>