docs/STATE_FILES.md

Runtime State Files (Repo-Root JSONs)

Several JSON files live in the repository root because they are runtime-state artifacts opened via relative paths by 20+ modules across aureon/, scripts/, and tests/. They must remain in the repo root so that scripts executed from the project root resolve them correctly.

⚠️ Do not move these files without updating every open("<name>.json") reference across the codebase. Moving them would silently break learning persistence, seed data, and integration tests.

File	Role	Primary owners
adaptive_learning_history.json	Adaptive-learning event log (seeded + appended at runtime)	aureon/utils/learned_analytics_reset.py, scripts/python/learning_analytics_cli.py, aureon/utils/full_market_trainer.py
bot_army_catalog.json	Catalog of tracked bot fleets used by scanners and simulations	aureon/bots/sniper_training_simulation.py, aureon/scanners/ira_sniper_mode.py, aureon/simulation/nuclear_crypto_reality.py
brain_predictions_history.json	Historical prediction log for the miner brain / hive mind	aureon/utils/aureon_miner_brain.py, aureon/utils/aureon_queen_hive_mind.py, aureon/analytics/historical_pattern_hunter.py
miner_brain_knowledge.json	Persistent knowledge base for the miner brain	aureon/utils/aureon_miner_brain.py, aureon/wisdom/irish_patriot_scouts.py, aureon/command_centers/aureon_command_center_ui.py

Related Runtime State (written by scripts, not always committed)

These files are generated at runtime in the current working directory by specific modules. They may or may not be committed at any given point:

File	Generator
ghost_dance_state.json	aureon/wisdom/aureon_ghost_dance_protocol.py
comprehensive_entity_database.json	aureon/scanners/aureon_strategic_warfare_scanner.py
planetary_harmonic_network.json	aureon/harmonic/aureon_planetary_harmonic_sweep.py
strategic_warfare_intelligence.json	aureon/scanners/aureon_strategic_warfare_scanner.py
harmonic_counter_frequency_map.json	aureon/harmonic/aureon_harmonic_counter_frequency.py
bot_census_registry.json, bot_cultural_attribution.json, historical_manipulation_evidence.json, manipulation_patterns_across_time.json, planetary_intelligence_report.json	aureon/bridges/aureon_planetary_intelligence_hub.py
deep_money_flow_analysis.json, money_flow_timeline.json	aureon/analytics/aureon_historical_manipulation_hunter.py

Future Refactor

A future cleanup could centralize these under data/state/ with a STATE_DIR environment variable / module constant that every consumer reads, eliminating the CWD coupling. That refactor is deferred to avoid touching 20+ call sites in this reorganization pass.