populate-entity

name	populate-entity
description	Scan an entity file to identify mentions of people, places, organizations, and other entities in the text. Creates missing entities using appropriate templates and adds wikilinks. Use when user wants to "populate", "fill out", "create linked entities", or "auto-generate connections" for an entity.
argument-hint	[entity or --world WorldName] [--dry-run] [--auto] [--limit N]

Populate Entity

Populate this entity: $ARGUMENTS

Overview

This skill analyzes an existing entity file to:

1. Identify plain text that should become wikilinks (names of people, places, organizations)
2. Find existing wikilinks that point to non-existent entities
3. Create all missing entities using appropriate templates
4. Update the source entity with proper wikilinks
5. Ensure bidirectional connections

Instructions

Step 1: Parse Arguments

Required:

• Entity path or name

Optional Flags:

Flag	Purpose	Default
--dry-run	Show what would be created without making changes	false
--auto	Skip confirmations, use best-guess entity types	false
--limit N	Maximum number of entities to create	20
--broken-only	Only fix broken wikilinks, skip plain text detection	false
--links-only	Only add wikilinks to existing entities, don't create new	false
--world [name]	BULK MODE: Process all entities in the specified world	-
--category [type]	With --world: only process entities in this category	all

Step 2: Locate Entity & Determine World

1. If path provided (contains / or .md):

   • Read the file directly
   • Extract world name from path: Worlds/[World Name]/...

2. If name provided:

   • Search Worlds/ directories for matching entity
   • Try exact filename match first
   • Then fuzzy match on filename and YAML name: field
   • If multiple matches, list them and ask user to clarify

3. If not found:

   • List similar entities and ask for clarification

The world name is required for knowing where to save new entities.

Step 3: Build Entity Index

Before analysis, create a complete index of existing entities in the world:

1. Scan all files in Worlds/[World Name]/ recursively
2. For each entity file, extract:
   • Filename (without .md extension)
   • YAML name: field
   • YAML aliases: array
   • File path
3. Build lookup dictionary (case-insensitive):

   {
     "entity name": "path/to/entity.md",
     "alias1": "path/to/entity.md",
     ...
   }
   

This index is used to:

• Avoid creating duplicate entities
• Detect existing entities mentioned as plain text
• Verify wikilinks point to real files

Step 4: Analyze Source Entity

Read the source entity file and perform three analyses:

4A: Extract Existing Wikilinks

Use regex pattern: \[\[([^\]|]+)(?:\|[^\]]+)?\]\]

For each wikilink found:

1. Extract the entity name (handling [[Name|Display]] format)
2. Check if it exists in the entity index
3. If not found, mark as broken link
4. Track line numbers for reporting

4B: Identify Potential Entity References

Scan the entity content (excluding YAML frontmatter, code blocks, and Image Prompts section) for proper noun patterns:

High-Confidence Patterns:

Pattern	Entity Type	Example
Lord/Lady [Name]	Character	"Lord Varic", "Lady Serana"
King/Queen [Name]	Character	"King Aldric", "Queen Elara"
Prince/Princess [Name]	Character	"Prince Edric"
Sir/Dame [Name]	Character	"Sir Galahad"
Captain/Commander [Name]	Character	"Captain Alonzo"
High Priest/Confessor [Name]	Character	"High Confessor Maren"
Elder/Master [Name]	Character	"Elder Thorne"
House [Name]	Organization	"House Valdren"
Clan [Name]	Organization	"Clan Ironforge"
Guild/Order [Name]	Organization	"Guild of Merchants"
The [Name] + (River/Sea/Forest/Mountain)	Geography	"The Trader's Sea"
[Name] River/Stream	Geography (River)	"Valdris River"
[Name] Mountain(s)/Range/Peak(s)	Geography (Mountain)	"Sundered Peaks"
[Name] Forest/Wood(s)/Grove	Geography (Forest)	"Whisperwood Forest"
[Name] Sea/Ocean	Geography (Ocean)	"The Eastern Sea"
[Name] Lake/Pond	Geography (Lake)	"Lake Shimmer"
[Name] Fields/Plains	Geography (Plains)	"The Ashen Fields"
[Name] Pass/Gap	Geography (Pass)	"Ironhold Pass"
[Name] Palace/Ruins/Dungeon	Geography (Dungeon)	"The Sunken Palace"
[Name] City/Metropolis	Settlement (City)	"Porto Valdris"
[Name] Town	Settlement (Town)	"Oakhaven Town"
[Name] Port/Harbor	Settlement	"Porto Valdris"
[Name] Fortress/Castle/Keep	Settlement (Stronghold)	"Thornwall Keep"
[Name] Village/Hamlet	Settlement (Village)	"Millbrook Village"

Medium-Confidence Patterns:

Pattern	Entity Type	Context Needed
The [Capitalized Name] (standalone)	Geography/Organization	Check surrounding text
[Two-Three Capitalized Words] in People section	Character	"Marco Fortunato"
[Capitalized Name] near "guild/order/temple"	Organization	Check context
[Capitalized Name] near "river/mountain/forest"	Geography	Check context

Detection Algorithm:

1. Split content into lines
2. Skip YAML frontmatter (between --- markers)
3. Skip Image Prompts section and below
4. Skip content inside code blocks (``` markers)
5. Skip existing wikilinks

6. For each line:
   a. Find capitalized multi-word phrases (2-4 words)
   b. Check against high-confidence patterns first
   c. If no pattern match, check context clues
   d. Skip common phrases that aren't entities:
      - "The [Direction]" (The North, The East)
      - Generic descriptors (The Great, The Ancient)
      - Section headers

7. For each detected phrase:
   a. Check if already in entity index -> mark as "needs wikilink"
   b. Check if not in index -> mark as "potential new entity"
   c. Record line numbers for all occurrences
   d. Extract surrounding context (10 words before/after)

4C: Classify Detected References

Sort all detected references into categories:

Category	Description	Action
Existing (Unlinked)	Name matches an existing entity but isn't a wikilink	Convert to [[wikilink]]
Broken Link	[[wikilink]] exists but no entity file found	Create entity
Inferred New	Proper noun with confident type guess	Create entity (confirm type)
Ambiguous New	Proper noun but type unclear	Ask user for type

Step 5: Present Analysis Report

Display findings before taking action:

=== ENTITY ANALYSIS: [Source Entity Name] ===

World: [World Name]
Source Path: [path/to/source.md]

---

## EXISTING ENTITIES (Should Become Links)

Found X names matching existing entities but not wikilinked:

| # | Name | Line(s) | Matches Entity |
|---|------|---------|----------------|
| 1 | "Lady Serana Valdren" | 150 | [[Lady Serana Valdren]] |
| 2 | "Captain Alonzo" | 178, 192 | [[Captain Alonzo the Bold]] |

---

## BROKEN WIKILINKS (Need New Entities)

Found X wikilinks pointing to non-existent entities:

| # | Wikilink | Line(s) | Suggested Type | Template |
|---|----------|---------|----------------|----------|
| 1 | [[The Merchant Guilds]] | 286 | Organization | Guild.md |
| 2 | [[Marevento]] | 69, 278 | Settlement | Town.md |
| 3 | [[Serenzia]] | 72, 278 | Settlement | Town.md |

---

## DETECTED REFERENCES (Potential New Entities)

Found X capitalized names that may be entities:

| # | Name | Line(s) | Suggested Type | Context |
|---|------|---------|----------------|---------|
| 1 | "Marco Fortunato" | 171, 283 | Character | "wealthiest merchant", "key retainer" |
| 2 | "Adriano Valdren" | 165 | Character | "Varic's brother", "overseas trade" |
| 3 | "The Sunken Palace" | 166, 252 | Geography (Dungeon) | "underwater ruins", "pre-Faith secrets" |

---

## AMBIGUOUS REFERENCES (Need Confirmation)

| # | Name | Line(s) | Could Be | Please Specify |
|---|------|---------|----------|----------------|
| 1 | "The Reckoning" | 184, 253 | Event OR Tradition | history/concept? |

---

## SUMMARY

| Category | Count |
|----------|-------|
| Existing to link | X |
| Broken links to create | X |
| New entities detected | X |
| Ambiguous (need input) | X |
| **Total potential creations** | **X** |

---

**Options:**
1. Create all suggested entities (uses best-guess types)
2. Review each entity individually
3. Only fix broken wikilinks
4. Only add links to existing entities
5. Show dry-run (no changes)

If --auto flag is set, skip this step and proceed with best-guess types. If --dry-run flag is set, show report and stop.

Step 6: Determine Entity Types

For each entity to create, use pattern matching to determine the template:

Template Mapping (from create-entity):

Characters:

Pattern	Template
Lord/Lady/King/Queen/Prince/Princess + name	Support Character.md (or Antagonist.md if negative context)
Sir/Dame/Captain/Commander + name	Support Character.md
High Priest/Confessor/Elder + name	Support Character.md
Personal name in "Members" or "Allies" context	Support Character.md
Personal name with villain/enemy context	Antagonist.md

Settlements:

Pattern	Template
[Name] + City/Metropolis	City.md
[Name] + Port/Harbor (large)	City.md
[Name] + Town	Town.md
[Name] + Port/Harbor (small)	Town.md
[Name] + Village/Hamlet	Village.md
[Name] + Fortress/Castle/Keep/Stronghold	Stronghold.md
Context mentions "capital", "great city"	City.md

Organizations:

Pattern	Template
House + [Name] (noble context)	Government.md
Guild/Guilds + [Name]	Guild.md
Order + [Name] (religious context)	Religious Order.md
Order + [Name] (martial context)	Military.md
Clan/Tribe + [Name]	Organization (General).md
Army/Legion/Navy + [Name]	Military.md
Cult + [Name]	Cult.md
Company + [Name] (trade context)	Business.md
Default organization	Organization (General).md

Geography:

Pattern	Template
[Name] + River/Stream	River.md
[Name] + Mountain(s)/Range/Peak(s)	Mountain Range.md
[Name] + Forest/Wood(s)/Grove/Jungle	Forest.md
[Name] + Sea/Ocean	Ocean.md
[Name] + Lake/Pond	Lake.md
[Name] + Fields/Plains/Grassland	Plains.md
[Name] + Pass/Gap	Pass.md
[Name] + Desert/Wasteland	Desert.md
[Name] + Coast/Shore	Coast.md
[Name] + Island/Isle	Island.md
[Name] + Palace/Ruins/Dungeon/Tomb	Dungeon.md
[Name] + Cave/Cavern	Cave.md
The [Name] (generic geography)	Region.md

History:

Pattern	Template
The [Name] + War/Conflict	War.md
The [Name] + Battle/Siege	Battle.md
The [Name] (event context: "years ago", "when")	Event.md
[Name] + Age/Era/Epoch	Age.md
[Name] + Treaty/Accord	Treaty.md

Category Folder Mappings:

Template Category	Save to Folder
Characters	Characters/
Settlements	Settlements/
Organizations	Organizations/
Geography	Geography/
History	History/
Concepts	Concepts/
Items	Items/
Creatures	Creatures/

Step 7: Confirm Creation Plan

Before creating entities, present the plan:

=== CREATION PLAN ===

Will create X new entities:

CHARACTERS (X):
| Entity | Template | Context from Source |
|--------|----------|---------------------|
| Marco Fortunato | Support Character.md | "wealthiest merchant" |
| Adriano Valdren | Support Character.md | "Varic's brother" |

SETTLEMENTS (X):
| Entity | Template | Context from Source |
|--------|----------|---------------------|
| Marevento | Town.md | "secondary port", "shipbuilding" |
| Serenzia | Town.md | "agricultural center" |

ORGANIZATIONS (X):
| Entity | Template | Context from Source |
|--------|----------|---------------------|
| The Merchant Guilds | Guild.md | "allied with House Valdren" |

GEOGRAPHY (X):
| Entity | Template | Context from Source |
|--------|----------|---------------------|
| The Sunken Palace | Dungeon.md | "underwater ruins", "pre-Faith" |

---

Proceed with creation? (yes/no/modify)

If --auto flag is set, skip confirmation and proceed.

Step 8: Create Entities

For each confirmed entity:

8A: Read Template

Read the appropriate template from Templates/[Category]/[Template].md

8B: Generate Content

Generate content based on:

1. Context from source entity - What does the source say about this entity?
2. World Overview - Read for tone, themes, naming conventions
3. Template requirements - Fill required sections

Content Generation Guidelines:

Since these are auto-generated entities, create minimal but coherent content:

1. YAML Frontmatter:

   • Set name: to the entity name
   • Set status: draft (marked for user review)
   • Fill category-specific fields with reasonable defaults
   • Leave image: empty

2. Overview Section:

   • 2-3 sentences based on context from source entity
   • Reference the source entity using [[wikilink]]

3. Core Identity Sections:

   • Fill minimally based on available context
   • Mark sections needing expansion with <!-- TODO: Expand -->

4. Connections Section:

   • Add [[Source Entity]] as primary connection
   • Use appropriate relationship category based on entity types

5. Image Prompts:

   • Leave as template placeholders or fill with basic descriptions

Naming Conventions:

Consult naming reference files when generating names:

• Templates/Reference/D&D Species Naming Conventions.md
• Templates/Reference/Tolkien Naming Conventions.md

Match naming style to the world's established conventions.

8C: Save Entity

Save to: Worlds/[World Name]/[Category]/[Entity Name].md

Use Title Case with spaces for filenames.

8D: Add Reciprocal Link

After saving the new entity, add a connection back to the source entity:

Reciprocal Link Patterns:

New Entity Type	Source Entity Type	New Entity Links To Source As
Character	Settlement	Home/Location
Character	Organization	Member Of
Character	Character	Associate/Ally
Settlement	Region	Part Of
Settlement	Organization	Headquarters
Organization	Settlement	Based Here
Organization	Character	Leadership/Members
Geography	Geography	Part Of/Contains

Step 9: Update Source Entity

After creating all new entities:

9A: Convert Plain Text to Wikilinks

For each detected reference that now has an entity:

1. Find occurrences in source entity
2. Replace Entity Name with [[Entity Name]]
3. Handle partial name matches (e.g., "Lady Serana" → [[Lady Serana Valdren|Lady Serana]])

Use Edit tool for precise replacements.

9B: Ensure Connections Section is Updated

For each new entity created:

1. Determine appropriate connection category based on entity type
2. Check if source entity's Connections section has this category
3. Add wikilink to appropriate subsection

Connection Section Formats:

## Connections

### People
- **Family:** [[Family Member]]
- **Allies:** [[Ally 1]], [[Ally 2]]
- **Associates:** [[Associate 1]]

### Organizations
- **Member Of:** [[Organization]]
- **Allied With:** [[Allied Org]]

### Locations
- **Headquarters:** [[Settlement]]
- **Territory:** [[Region]]

### Geography
- **Contains:** [[Location 1]], [[Location 2]]
- **Borders:** [[Neighboring Region]]

9C: Validate All Links

After updates, verify:

1. All new wikilinks resolve to existing entity files
2. No duplicate links in Connections section
3. Source entity frontmatter is intact

Step 10: Summary Report

=== POPULATE COMPLETE: [Source Entity Name] ===

Created X new entities:

CHARACTERS:
- [[Marco Fortunato]] - Wealthy merchant, Valdren ally (draft)
- [[Adriano Valdren]] - Varic's brother, trade manager (draft)

SETTLEMENTS:
- [[Marevento]] - Secondary port, shipbuilding center (draft)
- [[Serenzia]] - Agricultural town (draft)

ORGANIZATIONS:
- [[The Merchant Guilds]] - Allied trading organizations (draft)

GEOGRAPHY:
- [[The Sunken Palace]] - Underwater ruins with ancient secrets (draft)

---

Source Entity Updated:
- Added X wikilinks (previously plain text)
- Added X items to Connections section

Reciprocal Links Added:
- Marco Fortunato → [[Source Entity]] (employer)
- Marevento → [[The Western Shore]] (region)
- etc.

---

All new entities marked as 'draft' for review.

Suggested Next Steps:
1. Review and expand created entities with /expand-entity
2. Run /audit-world [World Name] to verify all connections
3. Generate images with /generate-image [Entity]

Bulk Processing Mode

When --world flag is provided, the skill processes multiple entities:

Bulk Mode Workflow

1. Scan world directory:

   • List all .md files in Worlds/[World Name]/
   • If --category specified, only scan that folder
   • Build a master entity index for the entire world

2. Analyze all entities:

   • Run detection on each entity file
   • Compile a master list of potential new entities
   • De-duplicate across files (same reference in multiple files = one entity)

3. Present consolidated plan:

   === BULK POPULATE: [World Name] ===
   
   Files Analyzed: X
   Files with Detections: Y
   
   ENTITIES TO CREATE (de-duplicated):
   
   | Entity | Type | Referenced In | Times |
   |--------|------|---------------|-------|
   | Marco Fortunato | Character | 3 files | 7 mentions |
   | The Iron Guild | Organization | 2 files | 4 mentions |
   ...
   
   Total: N new entities across M source files
   
   Options:
   1. Create all (uses best-guess types)
   2. Review by category
   3. Review each individually
   4. Dry run complete
   

4. Process with de-duplication:

   • Create each entity once
   • Update ALL source files that reference it
   • Add reciprocal links from new entity to all referencing entities

5. Bulk summary report:

   === BULK POPULATE COMPLETE ===
   
   Entities Created: N
   Source Files Updated: M
   Total Wikilinks Added: X
   Reciprocal Links Created: Y
   
   By Category:
   - Characters: N created
   - Settlements: N created
   ...
   

Bulk Mode Options

# Process entire world (with confirmations)
/populate-entity --world Eldermyr

# Fully automated (no confirmations)
/populate-entity --world Eldermyr --auto

# Only fix broken links across world
/populate-entity --world Eldermyr --broken-only

# Limit total entities created in bulk
/populate-entity --world Eldermyr --limit 50

# Preview bulk changes
/populate-entity --world Eldermyr --dry-run

Performance Notes

• Bulk mode builds entity index once (more efficient)
• De-duplication prevents creating duplicate entities
• For very large operations, use --limit to process in batches
• Consider running /audit-world --check links afterward to verify

Examples

# Populate a specific entity by name
/populate-entity "House Valdren"

# Populate by file path
/populate-entity Worlds/Eldermyr/Organizations/House Valdren.md

# Preview what would be created (no changes)
/populate-entity "Porto Valdris" --dry-run

# Auto-populate without prompts (for batch processing)
/populate-entity "Lord Varic Valdren" --auto

# Only fix broken wikilinks, skip text detection
/populate-entity "World Overview" --broken-only

# Only add wikilinks to existing entities, don't create new
/populate-entity "The Great War" --links-only

# Limit number of entities to create
/populate-entity "The Great War" --limit 5

# Combine flags
/populate-entity "House Valdren" --auto --limit 10

Integration with Other Skills

After /create-entity

Run /populate-entity on newly created entities to automatically flesh out referenced names.

Before /audit-world

Run /populate-entity on key entities to reduce broken link count before audit.

With /expand-entity

• /expand-entity adds depth to a single entity
• /populate-entity creates the network of related entities
• Use together: populate first, then expand key entities

With /link-entities

• /populate-entity creates entities from detected references
• /link-entities can refine the relationships afterward

Quality Guidelines

1. Conservative Creation: Only create entities with high-confidence type detection
2. Minimal Content: New entities get basic content marked as draft
3. Preserve Context: Use context from source to inform new entity content
4. Bidirectional: Always add reciprocal links
5. No Duplicates: Check entity index before creating
6. User Control: Confirmation prompts unless --auto flag