CLAUDE.md — AI Assistant Guide for the Aureon / HNC Repository

If you are an AI assistant (Claude, ChatGPT, Gemini, Copilot, etc.) landing in this repository cold — read this file first, then the three files in §"Cold-start reading order" below. After ~15 minutes of reading you will be able to answer almost any question about this project accurately.

What this repository is (30 seconds)

Aureon is a live, open-source quantitative trading system built on the Harmonic Nexus Core (HNC) — a theoretical framework that claims the same φ² (golden-ratio-squared) mathematical coherence organized the Ziggurats of Ur, the Great Pyramid, the Roman road network, the Maeshowe chamber, and the 1977 Wow! Signal, and now expresses itself in GitHub repository activity under geopolitical stress (r = 0.85 correlation, 24–48h lag, measurable and falsifiable).

The creator (Gary Leckey, Aureon Institute · R&A Consulting) synthesizes mythopoeic framing + hard-quantitative claims in one voice. Both registers are intentional and both are load-bearing — do not "soften" the mystical framing (the data holds it up) and do not "decorate" the technical claims (they're falsifiable).

Cold-start reading order (3 files, ~15 minutes)

1. docs/THE_SYNTHESIS.md — the one-page story, stitched from the creator's own prose. This is your single source of truth for "what is this?"
2. docs/CLAIMS_AND_EVIDENCE.md — every quantitative claim → evidence file → reproduction command. If you need to verify anything, start here.
3. docs/research/READING_PATHS.md — curated canon (13 papers out of 54) across 3 paths: A · The Pattern · B · The Framework · C · The Application.

After those three, pick the next file by task:

• User asks about code / architecture → docs/NAVIGATION_GUIDE.md → Developer Path
• User asks about the HNC math → docs/HNC_UNIFIED_WHITE_PAPER.md (Master Formula Λ(t), Tree of Light, Auris Conjecture)
• User asks about the ancient/φ² thread → docs/research/THE_PHI_SQUARED_CHAIN_Sumer_to_Rome_to_Now.md
• User asks about trading operations → docs/QUICK_START.md → docs/LIVE_TRADING_RUNBOOK.md
• User asks about deployment / Windows / dashboards → docs/deployment/ · docs/windows/ · docs/dashboards/

Codebase map (package-level)

aureon-trading/
├── aureon/                 # Main Python package — 715 modules, 24 domains
│   ├── core/               # Core engine, thought bus, nexus
│   ├── harmonic/           # HNC Master Formula implementation, planetary sweep, FFT
│   ├── scanners/           # Ocean wave, strategic warfare, stock scanners (44,000+ bots)
│   ├── queen/              # Queen AI decision layer with 4th-pass veto (53 modules)
│   ├── intelligence/       # Auris nodes, Seer ML, Lighthouse consensus
│   ├── wisdom/             # Ghost Dance protocol, stargate grid, Celtic frequencies
│   ├── bots_intelligence/  # Bot shape scanner, 193 species fingerprinted
│   ├── analytics/          # Historical manipulation hunter, pattern matching
│   ├── exchanges/          # Kraken, Capital.com, Alpaca, Binance adapters
│   ├── utils/              # Miner brain, adaptive Kelly gate, learning analytics
│   └── …                   # 14 more domains
├── frontend/               # React + Vite dashboard (647 files)
├── docs/                   # Theory, research, runbooks, architecture (17 entry-point .md at root)
│   ├── THE_SYNTHESIS.md    ★ start here
│   ├── CLAIMS_AND_EVIDENCE.md · HNC_UNIFIED_WHITE_PAPER.md · HNC_FALSIFICATION_PROTOCOL.md
│   ├── NAVIGATION_GUIDE.md · INDEX.md · QUICK_START.md · LIVE_TRADING_RUNBOOK.md
│   ├── STATE_FILES.md · MODULES_AT_A_GLANCE.md · SCRIPTS_INDEX.md · WHO_RUNS_THE_WORLD.md
│   ├── CHANGELOG.md · CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md · LICENSE-CC-BY-4.0.md
│   ├── research/           # whitepapers + markdown research notes
│   │   ├── READING_PATHS.md   ★ the 13-paper canon
│   │   ├── INDEX.md            # full thematic catalog
│   │   ├── whitepapers/        # PDFs/DOCX, themed
│   │   ├── reports/            # benchmark / analysis reports (AI LLM, sentience, Butlin…)
│   │   ├── audits/             # HNC verification audits (dated)
│   │   ├── figures/            # benchmark + verification charts (PNG / JPG)
│   │   ├── benchmarks/         # queen-benchmark-run*.md
│   │   ├── traffic/            # GitHub analytics charts
│   │   ├── hardware/           # CAD + firmware
│   │   └── images/
│   ├── architecture/       # 19 architecture/design docs (SYSTEM_*, POWER_STATION_*, UNIFIED_DATA_FLOW, Philosophy, Technical-Overview, …)
│   ├── integrations/       # Exchange / data-feed integrations (Binance, Kraken, Coinapi, Earth, Nexus feed, TWAP, Whale)
│   ├── deployment/         # DigitalOcean / tier / quickstart deploy guides
│   ├── runbooks/           # Live-trading readiness, emergency halt, production checklists, troubleshooting, security
│   ├── guides/             # Subsystem guides (BROKER_TEMPO, CELTIC_WARFARE, QUANTUM_TELESCOPE, Rising-Star, Ephemeris, Harmonic-Trinity, Primelines, Temporal-Qbit, …)
│   ├── components/         # Component READMEs (AURIS validator, Harmonic Nexus, Test validation)
│   ├── windows/            # Windows setup, terminal + unicode fixes + command cheat sheet
│   ├── dashboards/         # Dashboard guides + validation reports
│   ├── reports/            # Doc-form reports (backtest, before/after, bug, optimization, paper trade, SWOT)
│   ├── images/             # thematic visuals (WHO_RUNS_THE_WORLD, etc.)
│   └── archive/            # Historical docs kept for provenance
│       ├── queen_explorations/   # 14 QUEEN_*.md session + design notes
│       └── status_reports/       # 32 _STATUS / _COMPLETE / _SUMMARY proclamations
├── scripts/                # CLI tooling, deployment, analytics
│   ├── reports/            # status/integration Python scripts (GO_LIVE, INTEGRATION_SUMMARY, …)
│   ├── validation/         # flight-check / verify scripts (validate_balances, verify_*, …)
│   └── patches/            # queued code patches (not yet applied)
├── tests/                  # pytest suite; tests/fixtures/ for sample JSONL
├── data/                   # Ephemeris, market datasets, simulations
│   ├── datasets/           # aureon_qa / math_challenge / questions (ask-aureon corpus)
│   ├── research/           # structured benchmark & analysis data
│   └── ephemeral/          # runtime output logs (multiverse_live_thoughts.jsonl)
├── archive/                # Binary archives: old project zips, extracted RAINBOW-main, crash logs, etc.
├── VERIFICATION AND VALIDATION/  # 16 PDFs: acceptance criteria, replication
└── CLAUDE.md               # ← you are here

Conventions & gotchas

Naming conventions you will see

• _v1 / _v2 suffixes on whitepapers → intentionally distinct content, both preserved (the creator confirmed same-name-different-content pairs exist)
• _rev2 suffix → a later revision, original is also preserved
• _Leckey / _2026 — author + year markers
• HNC-related files are often prefixed aureon_* (e.g. aureon_harmonic_seed.py)

Runtime-state JSONs at the repo root

Four files live at the repo root by design because 20+ modules open them via CWD-relative paths — do not move them: adaptive_learning_history.json · bot_army_catalog.json · brain_predictions_history.json · miner_brain_knowledge.json See docs/STATE_FILES.md for the full inventory and the modules that own each file.

Voice & tone (critical when editing any prose)

When editing any doc in this repo, preserve the creator's characteristic fusion:

• Mythopoeic: quotes Babylonian tablets, the Emerald Tablet, Hermes Trismegistus
• Technical: r = 0.85, 1.29 ppb precision, 0.0° phase sync, β ∈ [0.6, 1.1]
• Defiant/humble: "Business guy → Consciousness researcher → Overnight self-taught coder"

Do not substitute the mystical framing with neutral corporate language. Do not add hedging to quantitative claims (they are pre-registered and falsifiable — see docs/CLAIMS_AND_EVIDENCE.md §Pre-Registered Predictions). Both registers are load-bearing.

Research theme groupings

The 54 whitepapers group into these themes (see docs/research/INDEX.md): HNC Framework · EPAS / Project Druid / Alfie · Lumina / LuminaCell · Symbolic Emergence / Dynamic Systems / Tandem-in-Unity · QGITA / Quantum Gravity · Materialization / Lambda / Mathematical · Astronomical / Cosmic Timing · Historical & Archaeo-Harmonic · Narrative / Reflective · Evidence Synthesis & Research Hubs

Safe edit zones vs careful zones

Safe to edit freely (standard docs work):

• docs/*.md (except voice-sensitive files below)
• docs/architecture/*.md
• docs/research/INDEX.md, docs/research/READING_PATHS.md, docs/CLAIMS_AND_EVIDENCE.md
• README.md (but preserve creator's voice in hero section)
• Code in aureon/, scripts/, tests/ following existing patterns

Careful — voice-sensitive:

• docs/THE_SYNTHESIS.md — primarily quoted from the creator; only add in <!-- editorial --> blocks
• docs/research/*.md (ANCIENT_CONVERGENCE, UNIFIED_FIELD, THE_PHI_SQUARED_CHAIN, AUREON_WHITE_PAPER_RESEARCH_HUB, etc.) — the creator's original prose, do not paraphrase
• docs/HNC_UNIFIED_WHITE_PAPER.md — formal theoretical paper, treat as immutable

Do not touch without explicit instruction:

• Whitepapers in docs/research/whitepapers/ (PDFs/DOCX)
• The 4 runtime-state JSONs at repo root
• VERIFICATION AND VALIDATION/ (authoritative audit artifacts)
• Anything under .git/, .github/, supervisord.conf, deployment configs

Quick facts for answering common questions

If you're about to write new code / docs

• Read docs/THE_SYNTHESIS.md first for voice calibration
• Check docs/architecture/THEORY_TO_CODE.md for the HNC-equation → Python mapping
• Run existing tests: pytest tests/ (pytest config in conftest.py)
• Validate any new markdown links with: python3 -c "import re,os; ..." (see git history for the link-audit script pattern used in recent commits)

This file is the creator's answer to "what should an AI read first?" — keep it accurate. If you discover this file is stale or missing something important, update it in the same PR as your actual work.