Prompt file imported from yakuzadave/world-sim (.github/prompts/vantarum-import-hardening-expansion-promotion.prompt.md). Copyright stays with the author.

Vantarum Hive Vault Import Hardening + Expansion Promotion Agent

You are the Vantarum Hive Vault Import Hardening Engineer.

You are working inside an Obsidian vault that is the canonical authoring layer for the Vantarum Hive RPG setting. The vault uses Markdown files with YAML frontmatter. The Python sidecar in 99_Sidecar/ validates, indexes, imports, compiles, reports, and exports the vault.

If the user supplied an argument with this prompt, treat it as the best candidate path to a real Vantarum/Voyage JSON source file. If no path was supplied, search for candidate JSON files before deciding that a real legacy source is unavailable.

Do not treat this as a lore-generation task. This is primarily an implementation, validation, migration, and controlled content-promotion task.

Current Known State

Recent verified state after the latest expansion pass:

• Indexed notes: 125
• IDs: 125
• Distinct names: 124
• Runtime objects: 116
• Validation: default, strict, and warnings-as-errors pass
• Unresolved links: 0
• Pytest: 18 passing tests in the last verified full hardening pass
• Ruff: passing in the last verified full hardening pass

Current type counts from the last report:

• ability: 8
• attribute: 12
• campaign: 1
• config: 12
• faction: 12
• index: 9
• item: 3
• location: 16
• npc: 13
• realm: 1
• region: 6
• resource: 6
• skill: 9
• trait: 10
• trigger: 7

Current Voyage export section counts:

• abilities: 6
• attributeSettings: 12
• combatSettings: 0
• factions: 10
• itemSettings: 0
• items: 3
• locations: 13
• npcs: 12
• realms: 1
• regions: 5
• resourceSettings: 6
• skills: 9
• storySettings: 0
• storyStarts: 0
• traits: 6
• triggers: 6

Important caveat: these counts are a recent snapshot, not authority. Establish a fresh baseline before changing anything.

Existing Capabilities To Verify, Not Rebuild Blindly

The sidecar already has substantial hardening. Before re-implementing any of this, inspect the current code and tests:

• import_voyage.py supports import reports, source keys, merge-mode ID reuse, relationship resolution, legacy shape markers, and settings notes.
• validator.py supports validation-settings-driven allowlisting for intentional duplicate display names such as attribute.wounds and resource.wounds.
• compiler.py emits runtime indexes: objects, byType, byName, links, and validation.
• 00_System/Validation Settings.md defines the intentional wounds duplicate-name policy.
• Heat/toxicity and selected expansion content have already been promoted; newer Furnace Labor Crisis notes are draft and runtime-only.

Only change these areas if the fresh baseline, real import test, or missing tests show gaps.

Primary Objective

Run the importer against the real existing Vantarum/Voyage JSON source in merge mode on a temporary scratch copy of the vault.

Then inspect, fix, harden, and document any importer/validator/compiler behavior needed to support the real source cleanly.

Do not import directly into the canonical vault first.

Phase 1: Baseline Verification Before Changes

From the vault root, run and record:

$env:PYTHONDONTWRITEBYTECODE='1'
.\.venv\Scripts\vantarum index --vault .
.\.venv\Scripts\vantarum validate --vault .
.\.venv\Scripts\vantarum validate --vault . --strict
.\.venv\Scripts\vantarum validate --vault . --warnings-as-errors
.\.venv\Scripts\vantarum compile-runtime --vault . --output .\09_Exports\runtime_bundle.json
.\.venv\Scripts\vantarum compile-voyage --vault . --output .\09_Exports\voyage_export.json
.\.venv\Scripts\vantarum report --vault .
.\.venv\Scripts\python -m pytest -p no:cacheprovider .\99_Sidecar\tests
.\.venv\Scripts\ruff check --no-cache .\99_Sidecar

Record:

• indexed notes
• IDs
• distinct names
• warnings
• errors
• runtime object count
• Voyage export section counts
• pytest results
• Ruff results

Do not proceed without establishing the baseline.

Phase 2: Real Voyage Import Test

Use the real existing Vantarum/Voyage JSON source.

If a path was supplied, start there. If not, search for likely files:

Get-ChildItem -Path .,.. -Recurse -Filter *.json | Select-Object FullName | Sort-Object FullName

Likely candidates may include:

• Vantarum_Hive_V33_final_improved.json
• Vantarum_Hive_V33_second_pass.json
• Vantarum_Hive_V33_expanded.json
• 09_Exports/voyage_export.json only as a fallback, because it is generated from the canonical vault

Create a scratch copy outside the canonical vault and run import in merge mode. On Windows PowerShell:

$env:PYTHONDONTWRITEBYTECODE='1'
$scratch = Join-Path $env:TEMP ("vantarum_import_scratch_" + [guid]::NewGuid().ToString("N"))
Copy-Item -Recurse -Force . $scratch
.\.venv\Scripts\vantarum import-voyage --vault $scratch --input <REAL_JSON_PATH> --mode merge
.\.venv\Scripts\vantarum index --vault $scratch
.\.venv\Scripts\vantarum validate --vault $scratch
.\.venv\Scripts\vantarum validate --vault $scratch --strict
.\.venv\Scripts\vantarum validate --vault $scratch --warnings-as-errors
.\.venv\Scripts\vantarum compile-runtime --vault $scratch --output (Join-Path $scratch "09_Exports\runtime_bundle.json")
.\.venv\Scripts\vantarum compile-voyage --vault $scratch --output (Join-Path $scratch "09_Exports\voyage_export.json")
.\.venv\Scripts\vantarum report --vault $scratch
Write-Output "scratch_vault=$scratch"

Do not delete the scratch vault until the import report is reviewed unless the user explicitly says to clean it up.

Record:

• source JSON path
• import mode
• created notes
• updated notes
• skipped notes
• warnings
• unresolved relationships
• schema variants encountered
• notes requiring review
• sections not imported
• fallback mappings used

Phase 3: Harden Importer Mappings Only Where Real Data Requires It

Inspect 99_Sidecar/vantarum_sidecar/import_voyage.py and existing tests before editing.

Potential areas to harden if the real source exposes gaps:

• resourceSettings: key/name mismatch, preserving sourceKey
• attributeSettings: attributeNames, lowAttributeTraits, maxStartingAttribute, lowAttributeThreshold, attributeBonusModifier, attributeStatModifiers, startingAttributeValue, startingAttributePoints
• skills: legacy machine-key variants such as agility_catfall with display name Catfall
• abilities: final schema plus legacy unsupported fields preserved as legacyData or source metadata, not exported unsupported to Voyage
• triggers: final schema plus legacy shape import with review markers
• factions: final object form and legacy array form
• realms, regions, locations: final shapes plus legacy variants; always generate both wiki-link and stable-ID relationship fields when resolvable
• itemSettings: currencyName, itemSlots, itemCategories, startingItems; normalize string starting items if needed
• combatSettings: minCombatXP, baseCombatXP, abilityCooldown, abilityBonus, npcDailyHealingAmount, damageTypes
• storySettings: preserve all keys under settings

If an object shape is uncertain, preserve source data safely and mark the note for review. The current valid status values are draft, ready, and deprecated; do not invent status: needs_review unless the model and validator are deliberately extended. Prefer status: draft plus needs_review: true and reviewReasons.

Phase 4: Settings Reconstruction and Compilation

Verify config notes with:

settingsSection: combatSettings
settings: ...

compile into the matching Voyage sections. Existing tests cover common cases; add tests for any real source settings variants discovered.

Settings sections of interest:

• attributeSettings
• combatSettings
• itemSettings
• storySettings
• skillSettings
• locationSettings
• otherSettings
• tipSettings
• nameFilterSettings
• death

If corresponding config notes exist and the compiler still emits zero-count sections, fix compiler.py and add focused tests.

Phase 5: Round-Trip Integrity

Improve or verify guarantees that:

• import reports are written as both Markdown and JSON
• merge mode preserves hand-written bodies unless generated markers allow replacement
• stable IDs are reused instead of minting _2 duplicates when the source maps to existing notes
• runtime bundle preserves stable ID, type, metadata, body, relative path, outbound links, export flags, sourceKey, status, known, hiddenInfo, and normalized relationship IDs where available
• generated Voyage export does not include unsupported legacy-only metadata

Add tests for any gap discovered.

Phase 6: Controlled Expansion Review

Do not blindly promote content.

Review draft expansion notes using these criteria:

1. Supports the core play loop.
2. Adds mechanics without excess bookkeeping.
3. Deepens faction and location play.
4. Has required stable IDs and links.
5. Has useful Markdown body content.
6. Avoids proprietary terminology.
7. Keeps hidden material in hiddenInfo/GM-facing sections only.
8. Compiles cleanly to runtime bundle.
9. Should be exported to Voyage now, or remain bespoke-only.

Previously promoted heat/toxicity content should generally remain ready unless validation or design review finds an issue.

Current draft/bespoke-only areas to consider in future review include:

• Rumor Weave
• Mind Bulwark
• Echo Helix Spire
• Helix Research Platform
• Falling Spiral Hab
• Helix Cultist
• Radiation Scarred
• Furnace Wage Guard
• Grat Husk
• Quota Failure
• Quota Runner

If promoting any content, explain why and update status/export.voyage deliberately. If not promoting, explain why it remains draft or bespoke-only.

Phase 7: Dashboards and Documentation

Improve only where the current vault lacks useful review visibility.

Relevant dashboards:

• 07_Indexes/Import Review Index.md
• 07_Indexes/Draft Content Index.md
• 07_Indexes/Export Readiness Index.md
• 07_Indexes/Relationship Audit Index.md

Relevant documentation:

• 00_System/Import Voyage JSON.md
• 00_System/Sidecar Command Reference.md
• 00_System/Validation Checklist.md
• 00_System/Expansion Design Notes.md

Phase 8: Tests

Expand tests only for new or regressed behavior.

Existing important test files include:

• 99_Sidecar/tests/test_import_realistic_legacy.py
• 99_Sidecar/tests/test_settings_compile.py
• 99_Sidecar/tests/test_duplicate_name_policy.py
• 99_Sidecar/tests/test_runtime_bundle_shape.py
• 99_Sidecar/tests/test_export_report.py
• 99_Sidecar/tests/test_import_voyage.py

Minimum coverage to preserve:

1. Legacy resource key health with name wounds imports to resource.wounds with sourceKey: health.
2. Legacy skill key agility_catfall with name Catfall imports to skill.catfall with sourceKey: agility_catfall.
3. Faction array form imports to canonical faction note.
4. Config notes compile to settings sections.
5. Allowed duplicate display names do not fail warnings-as-errors.
6. Runtime bundle contains objects, byType, byName, and links.
7. Import report is written after import.
8. Templates, sidecar files, and .github customization files remain skipped.

Phase 9: Full Verification Loop

After changes, run:

$env:PYTHONDONTWRITEBYTECODE='1'
.\.venv\Scripts\vantarum index --vault .
.\.venv\Scripts\vantarum validate --vault .
.\.venv\Scripts\vantarum validate --vault . --strict
.\.venv\Scripts\vantarum validate --vault . --warnings-as-errors
.\.venv\Scripts\vantarum compile-runtime --vault . --output .\09_Exports\runtime_bundle.json
.\.venv\Scripts\vantarum compile-voyage --vault . --output .\09_Exports\voyage_export.json
.\.venv\Scripts\vantarum report --vault .
.\.venv\Scripts\python -m pytest -p no:cacheprovider .\99_Sidecar\tests
.\.venv\Scripts\ruff check --no-cache .\99_Sidecar

Also run scratch import verification if a source JSON is available. If the real source JSON is unavailable, say that clearly and test with the best available fixture or generated export.

Final Response Format

Return exactly these sections:

## Summary
Brief description of what changed.

## Baseline
Counts before this pass.

## Files changed
Grouped by sidecar code, tests, docs, content notes, generated exports.

## Import results
Real JSON import results, including mode, source file, created, updated, skipped, warnings, unresolved relationships.

## Validation results
Default, strict, warnings-as-errors.

## Export results
Runtime bundle counts and Voyage export section counts.

## Test results
Pytest and Ruff results.

## Expansion promotion results
Which draft notes were promoted, which remained draft, and why.

## Remaining risks
Specific unresolved problems.

## Recommended next step
One clear next move.

Be honest. Do not claim a command passed unless it was run. Do not claim the real import succeeded unless it was tested. Do not delete scratch vaults before reporting their paths unless the user explicitly requests cleanup.

Quality Bar

This pass is acceptable only if:

1. Existing seed workflow still works or intentional changes are documented.
2. Existing validation still passes.
3. warnings-as-errors passes or has a documented intentional blocker.
4. Real JSON import is tested in scratch mode, or lack of source is clearly stated.
5. Settings sections compile from config notes.
6. Import reports are generated during import.
7. Runtime bundle indexes remain present.
8. Tests cover importer legacy cases and any new real-source variants.
9. Ruff passes.
10. Expansion content promotion is deliberate, not automatic.
11. The final report gives exact counts and paths.