Add Civilization - Interactive Research Session

Research and add a new civilization (polity at a point in time) to the FUTR database.

Input

The user provides a civilization specification - a hint at universe, polity, and time frame. Examples: "Andorians from Star Trek at Federation founding", "Galactic Empire at fall of Coruscant"

Workflow

Step 1: Identifying

•Research the specification online to verify it's unambiguous
•Identify: Universe, Polity, Civilization name, Date
•Check if the universe/polity already exists in data/universes/
•Ask clarifying questions if the specification is ambiguous
•Confirm the identified civilization with the user

Step 2: General Research

•Search for descriptive and metric data about the civilization
•Find material on: population, territory, technology, government, military, culture
•Check existing metrics in data/metrics/ that could apply
•Propose new metrics if needed (ask user)
•Present findings and ask which metrics to include

Step 3: Metrics Research

•Research specific values for each selected metric
•Determine confidence levels: canon > calculated > informedGuess > calculatedGuess > wildGuess
•Find min/max ranges where uncertain
•Cross-check values against existing data (e.g., compare Kardashev to Earth 2023 = 0.73) — these comparisons are for validation only, do not include them in readme fields
•In-universe comparisons: When sources compare to places that share real-world names (e.g., "Sol System", "Earth", "Mars"), assume they refer to the in-universe version at the same time period—not real-world data. Research the in-universe reference to properly contextualize the comparison.
•Gather reference URLs for all values

Step 4: Review

•
Present all proposed data in tables:
- •New metrics (if any)
- •Polity info
- •Civilization info
- •Datapoints with values, ranges, confidence, sources AND comparable figures from other civilizations (for validation only—do not include comparisons in final readme fields)
•Ask user to approve or adjust values
•Iterate until user is satisfied

Step 5: Image Research & Attribution (REQUIRED)

•Find images (from Wikimedia Commons, Wikipedia, official sources)
•
For EVERY image, you MUST research and document all attribution fields:
- •src: Direct image URL (or /proxy/... path for downloaded images)
- •link: Source page URL for attribution (e.g., Wikimedia Commons file page, publisher page)
- •author: Creator/artist name (search for the artist - e.g., book cover artists, map creators)
- •license: Short identifier (e.g., "CC BY-SA 4.0", "Public Domain", "© Publisher" for copyrighted works)
- •legal: Full license text or URL (e.g., "https://creativecommons.org/licenses/by-sa/4.0/" or "Copyrighted by [Publisher]. Used for commentary under Fair Use.")
•
Research strategy for attribution:
- •Wikimedia Commons: Fetch the file page to find author and license info
- •Book covers: Search for "[book title] cover artist" - publishers like Baen often use known artists
- •Fan wiki images: Check the file page for upload info and licensing
- •Official art: Note the copyright holder (studio, publisher) and use Fair Use rationale
•If attribution is incomplete, ask the user whether to: (a) add the image anyway with "Unknown" for missing fields, (b) skip the image, or (c) search for a different image
•Write descriptions for polity and civilization readme fields
•Gather links to official/wiki pages
•Proxy images from Wikimedia/Wikipedia if they block external embedding (see Image Proxy section below)

Step 6: Implementation

•
Create directories and info.yaml files:
- •data/universes/{Universe}/info.yaml (if new universe — include tags: [index, new])
- •data/metrics/{NewMetric}/info.yaml (if new metrics)
- •data/universes/{Universe}/_polities/{Polity}/info.yaml (if new polity)
- •data/universes/{Universe}/{Civilization}/info.yaml (include tags: [index, new])
- •data/universes/{Universe}/{Civilization}/{Metric}/info.yaml (datapoints)
•Verify all files created
•Check if .claude/settings.local.json was modified (new permissions added during research)
•Commit all changes together (data files + settings if modified) with message: "add {Civilization} civilization"

YAML Schemas Reference

See .claude/rules/content.md for full schemas. Key fields:

Timestamps

All info.yaml files MUST have created and changed date fields (format: YYYY-MM-DD):

•New files: Set both created and changed to today's date
•Modified files: Update only changed to today's date (never change created)

Datapoint:

yaml

created: 2026-02-04
changed: 2026-02-04
value: 8e9
min: 5e9
max: 11e9
confidence: informedGuess  # canon|calculated|informedGuess|calculatedGuess|wildGuess
references:
  - link: https://...
    text: "Source name"
readme: |
  Explanation of how value was derived.

Universe (if new):

yaml

title: Universe Name
created: 2026-02-04
changed: 2026-02-04
tags: [index, new]  # always add 'new' tag for new universes
images:
  - src: https://...           # Direct image URL
    text: "Caption"
    link: https://source-page  # Source page for attribution
    author: "Artist Name"      # REQUIRED: Research the actual artist
    license: "CC BY-SA 4.0"    # REQUIRED: License identifier
    legal: "https://creativecommons.org/licenses/by-sa/4.0/"  # REQUIRED: License URL or Fair Use text
    tags: [main]               # "main" = primary/tile image
links:
  - src: https://...
    text: "Official/Wiki link"
readme: |
  Description of the universe.

Civilization:

yaml

title: Polity Year
created: 2026-02-04
changed: 2026-02-04
date: 2161
polity: Polity Name
tags: [index, new]  # always add 'new' tag for new civilizations
images:
  - src: https://...           # Direct image URL
    text: "Caption"
    link: https://source-page  # Source page for attribution
    author: "Artist Name"      # REQUIRED: Research the actual artist
    license: "CC BY-SA 4.0"    # REQUIRED: License identifier
    legal: "https://creativecommons.org/licenses/by-sa/4.0/"  # REQUIRED: License URL or Fair Use text
    tags: [main]               # "main" = primary/tile image
readme: |
  Description of this civilization snapshot.

Quality Checks

•All datapoints MUST have references
•Cross-check Kardashev against Earth 2023 (K=0.73) for sanity
•Use existing metrics when possible before creating new ones
•Images should be from canonical/official sources when available
•
All images MUST have complete attribution — src, link, author, license, legal are ALL required fields
- •author: Research the actual creator (artist name, photographer, etc.) — do not skip this step
- •license: Use standard identifiers like "CC BY-SA 4.0", "Public Domain", "© [Publisher]"
- •legal: Provide license URL or Fair Use rationale for copyrighted works
•New universes and civilizations MUST have tags: [index, new] — the "new" tag marks recently added content
•All info.yaml files MUST have created and changed dates — use today's date for new files

Image Proxy

Wikimedia/Wikipedia images often block external embedding. Download these to a local proxy folder:

Pattern:

•Original URL: https://upload.wikimedia.org/wikipedia/commons/d/d5/Example_Image.PNG
•Local path: data/proxy/upload.wikimedia.org/wikipedia/commons/d/d5/Example_Image.PNG
•Reference in YAML: /proxy/upload.wikimedia.org/wikipedia/commons/d/d5/Example_Image.PNG

The local path mirrors the original URL structure (preserving slashes).

Steps:

•Create directory: mkdir -p "data/proxy/{host}/{path}"
•Download the image: curl -L -o "data/proxy/{host}/{path}/{filename}" "{url}"
•Reference with /proxy/... URL in the src field (served by ProxyController)
•Keep the original Wikimedia Commons page in the link field for attribution

Example:

yaml

images:
  - src: /proxy/upload.wikimedia.org/wikipedia/commons/d/d5/The_Honor_Harrington_Universe.PNG
    text: Map of the Honorverse
    link: https://commons.wikimedia.org/wiki/File:The_Honor_Harrington_Universe.PNG
    author: "Michał Świerczek"  # Research the actual author from Wikimedia Commons page
    license: "CC BY-SA 3.0"
    legal: "https://creativecommons.org/licenses/by-sa/3.0/"