When to use: After the investigation is written (brief.md, script.md, scene-plan.md complete). Before packaging for upload.
From the completed investigation, extract and structure:
1. Entities (8 categories)
Read ALL source files (brief.md, script.md, scene-plan.md, plot.md) and extract every named entity into the correct category:
people: Named individuals, historical figures
institutions: Organizations, corporations, governments, international bodies
places: Countries, cities, regions, specific locations
events: Named historical events, treaties, conferences, crises
mechanisms: Policy tools, economic instruments, control methods
systems: Named systems (Bretton Woods System, petrodollar system)
concepts: Abstract ideas, ideologies, theoretical frameworks
commodities: Physical goods (oil, gold, water, seeds)
Every entity MUST have ALL THREE fields:
name — the entity's namedescription — what it IS, universally (context-independent definition that works across all investigations). 1-2 sentences. "Lloyd's of London is a 337-year-old British insurance marketplace where syndicates pool capital to underwrite risk."role — what it did in THIS investigation (investigation-specific). "The marketplace whose war risk committee closed Hormuz coverage faster than Iran's mines — their risk calculation shut down one-fifth of global oil transit."
The difference matters:
description = stable identity. Same for Lloyd's no matter which investigation mentions it.role = investigation-specific contribution. Changes per investigation. THIS is the hero content in detail panels.
Quality check: If description sounds like role, you wrote the same thing twice. Description answers "what IS this?" Role answers "what did it DO here?"
2. Causal Links
For every cause-and-effect relationship in the investigation, create a link:
{"from": "IMF", "relation": "enforced", "to": "structural adjustment", "evidence_panel": 7}
Use ONLY these relation types:
caused, triggered, created, enabled, funded, legitimized, enforced, weakened, collapsed, resisted, warned_against, replaced
Quality check: If you're using "caused" for everything, you're not reading closely enough. "enabled" is different from "caused" is different from "triggered."
3. Causal Chains
Identify the multi-step causal sequences — these are the investigation's analytical backbone:
{
"name": "Dollar Dependency Chain",
"description": "How US gold reserves became global financial dependency through institutional design",
"steps": ["US gold supremacy", "dollar plan at Bretton Woods", "IMF/World Bank creation", "dollar as reserve currency", "global dependency"],
"panels": [3, 5, 7, 9, 12]
}
- Minimum 4 chains
- Each chain: 4+ steps
description is REQUIRED — what structural mechanism this chain revealspanels tracks where each step appears
4. Themes
Identify the structural patterns the investigation reveals:
{
"name": "asymmetric design",
"description": "The system was built to favor creditors over borrowers at every decision point",
"panels": [4, 8, 14, 19]
}
- Themes are OBJECTS with name, description, and panel references
- Minimum 5 themes
- Themes are patterns, not topics. "economics" is a topic. "asymmetric design" is a theme.
5. Act Structure (Narrative Structure)
Extract from plot.md — the investigation's structural skeleton:
{
"act_structure": [
{"act": "THE ROOM", "panels": [1, 6], "description": "44 nations gather at Mount Washington Hotel"},
{"act": "THE VISIONS", "panels": [7, 10], "description": "Keynes vs White — two competing blueprints"},
{"act": "THE MACHINE", "panels": [11, 16], "description": "How the institutions actually work"},
{"act": "THE CONVERGENCE", "panels": [17, 20], "description": "BRICS, AIIB, and the counter-architecture"},
{"act": "THE QUESTION", "panels": [21, 25], "description": "Can any replacement avoid the same dynamics?"}
]
}
panels is [start, end] — the range of panels in that actdescription is a one-sentence summary of what that act covers- Act names should be evocative, not generic ("THE MACHINE" not "Part 3")
- This drives the sidebar navigation in the platform detail page
6. Emotion Arc
Map the emotional journey through the investigation:
{
"emotions": ["tension", "revelation", "unease", "clarity", "urgency"],
"emotion_arc": [
{"panel": 1, "emotion": "tension", "note": "opening scene — ship adrift"},
{"panel": 2, "emotion": "authority", "note": "classification header establishes weight"},
{"panel": 12, "emotion": "revelation", "note": "the insurance withdrawal mechanism revealed"}
]
}
emotions: unique tones across the investigation (deduplicated list)emotion_arc: per-panel emotional beat (every panel gets one)
7. Systems
Named systems mapped in the investigation:
{
"systems": [
{
"name": "Marine Insurance Architecture",
"description": "The layered system of hull, cargo, P&I, and war risk insurance that determines which ships can sail",
"entities": ["Lloyd's of London", "P&I Clubs", "War Risk Premium", "JWC"]
}
]
}
8. Cross-Project Links
If you know about other GatorSquare investigations, identify connections:
{"project_id": "petrodollar-system", "connection": "Nixon Shock killed Bretton Woods gold standard, creating vacuum petrodollar filled", "type": "causal"}
9. Topic Categories
NOT a fixed list. Assign 2-4 broad umbrella categories that describe the investigation. Examples: Economics, Geopolitics, Energy, Security, Finance, Institutions, History, Technology, Society, Maritime, Nuclear — whatever fits. Be consistent across investigations (if "Economics" in one, not "Economic Systems" in another).
STEP 1: Read brief.md completely — extract entities with descriptions + roles, identify key systems
STEP 2: Read script.md — extract causal links from narration, map emotion per panel
STEP 3: Read scene-plan.md — extract visual entities, moods, environments
STEP 4: Read plot.md — extract act structure (act names + panel ranges + descriptions)
STEP 5: Deduplicate entities across all sources (keep the richer description/role)
STEP 6: Build causal chains from individual links, write chain descriptions
STEP 7: Identify themes from patterns — write as objects with panel refs
STEP 8: Build systems — group related entities into named systems with descriptions
STEP 9: Map emotion arc — one emotion per panel
STEP 10: Check cross-project connections
STEP 11: Assign topic categories
STEP 12: Write knowledge.json + update metadata.json
Output: knowledge.json (Canonical Schema)
{
"project_id": "investigation-slug",
"entities": [
{
"name": "Lloyd's of London",
"category": "institutions",
"description": "337-year-old British insurance marketplace where syndicates pool capital to underwrite risk globally",
"role": "The marketplace whose war risk committee closed Hormuz coverage faster than Iran's mines",
"panels": [2, 5, 8, 14, 22]
}
],
"causal_links": [
{"from": "Lloyd's JWC", "relation": "triggered", "to": "war risk premium spike", "evidence_panel": 5}
],
"causal_chains": [
{
"name": "Insurance Cascade",
"description": "How a committee decision in London shut down global oil transit",
"steps": ["JWC designates war zone", "war risk premium spikes to $14M", "shipowners cancel voyages", "Hormuz transit drops 90%", "spot oil hits $119"],
"panels": [5, 7, 9, 12, 15]
}
],
"systems": [
{
"name": "Marine Insurance Architecture",
"description": "Layered system of hull, cargo, P&I, and war risk that determines which ships can sail",
"entities": ["Lloyd's of London", "P&I Clubs", "JWC", "War Risk Premium"]
}
],
"themes": [
{
"name": "permission layer",
"description": "Insurance doesn't respond to risk — it grants or withdraws permission to operate",
"panels": [3, 8, 14, 20]
}
],
"act_structure": [
{"act": "THE PERMISSION LAYER", "panels": [1, 5], "description": "How insurance controls global trade"},
{"act": "FIVE CRISES", "panels": [6, 12], "description": "Historical precedents for insurance withdrawal"}
],
"emotions": ["tension", "revelation", "authority", "unease", "urgency"],
"emotion_arc": [
{"panel": 1, "emotion": "tension", "note": "VLCC adrift in the Gulf"},
{"panel": 2, "emotion": "authority", "note": "Lloyd's Room 1 establishes institutional weight"}
],
"cross_references": [
{"project_id": "hormuz-chokepoint", "connection": "Military side of the same closure", "type": "causal"}
]
}
{
"project_id": "investigation-slug",
"title": "Full Title",
"subtitle": "One-line hook (shown on gallery cards and detail page header)",
"summary": "2-3 sentence overview of the investigation and its core finding",
"description": "Full paragraph description for SEO and detail page",
"author": "Display Name",
"author_id": "user_id",
"author_role": "Professional role",
"author_location": "City",
"viewer_style": "dossier|magazine|first-person|quantitative|blog|comic-text|scenario-brief",
"investigation_date": "2026-03-XX",
"investigation_type": "systems|economic|geopolitical|comparative|quantitative",
"topic_domain": "primary domain (e.g., energy economics)",
"key_question": "The question this investigation answers",
"thesis_statement": "One-sentence core finding",
"research_summary": "Opening paragraph — the hook that draws readers in",
"confidence_level": "high|medium|moderate",
"data_sources": ["source1", "source2"],
"geographic_focus": ["country1", "country2"],
"historical_period": "date range (e.g., 1688-2026)",
"systems_mapped": ["System 1", "System 2"],
"key_figures": ["Person 1", "Institution 1"],
"cross_references": [
{"project_id": "related-id", "connection": "how they relate", "type": "causal"}
],
"tags": ["tag1", "tag2"],
"topic_categories": ["Economics", "Security"],
"panel_count": 25,
"estimated_word_count": 6000
}
Fields the frontend DEPENDS on (do NOT skip):
subtitle — gallery cards + detail page headersummary — detail panel when entity is a projectsystems_mapped — collapsible section + Systems view modekey_figures — collapsible section with green badgesresearch_summary — project cards teasercross_references — Connected Investigations sectiongeographic_focus — gray badgeshistorical_period — metadata linetags — brass badges, tag-level filteringtopic_categories — checkbox filters in Knowledge Panel
Validation Checklist