Aura/docs/project-layout.md

How aura is used — engine, projects, and a day in the life

This document describes the outside of aura: how you sit in front of it and what a research session looks like. The inside (the engine's contracts) is the design ledger (docs/design/INDEX.md).

Engine vs. project (the game-engine split)

aura is a game engine for traders, and like any game engine it is separate from the things built with it:

• This repo (aura) is the engine: aura-core (the shared contract), aura-std (universal standard nodes), aura-engine (the deterministic sim runtime), aura-cli (the aura binary), and later the egui playground. It ships at most examples/ fixture nodes for its own tests — never your real signals.
• A research project is its own external repo (e.g. ~/dev/ger40-lab/), with its own git history and its own Gitea repo (its own forward-queue), anchored by a static Aura.toml. Its default tier is data-only — blueprints, process, and campaign documents over the std vocabulary, no crate, no build step; the aura host loads and runs it during research as is. The moment the project needs native node logic (role-2 work), it attaches a node crate (a cdylib, scaffolded by aura nodes new) via Aura.toml [nodes]; the aura host then hot-reloads that crate too, and freezing a chosen strategy + broker still yields one standalone binary spanning both halves for deploy. This is where you and Claude author signals and experiments, and where the runs live. (Contracts C16, C20, #241.)

The aura CLI is a tool you run inside a project directory — it finds the project root by walking up to an Aura.toml, the way cargo finds Cargo.toml. A project is a directory anchored by Aura.toml; native node logic never lives in the project directory itself, only in an attached node crate (the two tiers below).

A project repo (two tiers)

The default project is data-only — no crate, no build step. aura new scaffolds exactly this:

ger40-lab/                 # your research project — a plain directory, no crate
├── Aura.toml              # STATIC context only: `[paths] runs` (the runs dir)
│                          # and `[paths] data` (the archive root; defaults to
│                          # the built-in Pepperstone path when unset); no
│                          # logic — instrument geometry is the recorded
│                          # sidecar (C15), never authored here. A `[nodes]`
│                          # section, absent here, is what tier-selects a
│                          # node crate in (see below).
├── CLAUDE.md              # the project's own skills wiring (authoring discipline)
├── blueprints/            # op-scripts / campaign / process documents (data, no build)
└── runs/                  # the run registry: manifest + metrics per run

Runs, sweeps, and campaigns over the std vocabulary work immediately — nothing to compile. The moment a project needs a native node type (role-2 work), aura nodes new <name> scaffolds a sibling node crate and attaches it via an Aura.toml [nodes] pointer:

ger40-lab/                 # unchanged: still Aura.toml + blueprints/ + runs/
├── Aura.toml              # now carries `[nodes] crates = ["../ger40-lab-nodes"]`
└── …

ger40-lab-nodes/            # a SIBLING directory — its own cdylib crate
├── Cargo.toml              # cdylib; depends on aura-core (+ shared node crates);
│                           # carries an empty [workspace] table (see note below)
├── CLAUDE.md               # the node crate's own skills wiring
└── src/
    └── lib.rs              # the project's native node types, `<namespace>::`-prefixed

The aura host loads the pointed-at node crate during research (hot-reload); freezing a chosen strategy + broker still yields one standalone binary for deploy, spanning both halves.

The empty [workspace] table (node-crate tier only). A node crate is its own cargo workspace, never a member of the engine's. This matters the moment a node crate lives under the engine repo (common while authoring, before it moves to its own repo): cargo otherwise walks up, finds the engine's root manifest, and refuses to build —

error: current package believes it's in a workspace when it's not:
... to keep it out of the workspace, add an empty [workspace] table ...

The fix is cargo's own hint: an empty [workspace] table in the node crate's Cargo.toml. It pins the crate as a standalone workspace root and costs nothing when the node crate later sits in its own repo. The aura nodes new scaffolder emits this line; a hand-rolled node crate adds it itself.

Where reusable nodes live (three tiers)

Everything that plugs into the engine is fractally a Node. Reuse is plain cargo, layered by maturity (contract C16):

1. aura-std — universal blocks shipped with the engine (SMA/ATR/RSI, resamplers, the SessionNode, standard combinators, broker profiles).
2. Shared node crates — cross-project-reusable blocks in their own repos (e.g. Brummel/aura-nodes-fx), pulled in as cargo git dependencies.
3. The project's own node crate — experimental, project-specific blocks, attached via Aura.toml [nodes] (scaffolded by aura nodes new; see the two tiers above).

Promotion is the ordinary Rust gradient: a node proves itself project-local → gets extracted into a shared crate → if it turns universal, into aura-std. Shared nodes are rlib dependencies; the hot-reload unit stays the project-side cdylib that composes them, so editing a shared node still rebuilds and reloads the dependent.

Every tier follows the same three-part pattern — a Node impl, a PrimitiveBuilder recipe, and rostering the type id into a vocabulary lookup — worked through end to end, with the scaffold's own starter node as the example, in docs/authoring-guide.md, §0.

Authoring happens in Claude Code (contract C17)

aura has no built-in coding-LLM. You author by talking to Claude Code, which writes the Rust — nodes, strategies, and experiments — builds it, runs it, and reports back. Declarative config (Aura.toml) holds only static context, never logic. IONOS LLMs appear only as a runtime data source (e.g. a news-agent node emitting a bias), recorded before it enters a backtest, and only with your per-session consent.

Wiring already-built node types into a graph, and naming experiment intent over such a graph, is a separate, closed-vocabulary data surface, not Rust: an op-script (aura graph build) assembles a strategy blueprint from node types already in the vocabulary, a process document (aura process) names a validation/eval methodology, and a campaign document (aura campaign) names instruments × windows × strategy × param axes × process. All three are headless-authorable and introspectable without a build. See docs/authoring-guide.md for the worked grammar and command sequences.

A day in the life

1. You (in Claude Code, inside ger40-lab/): "I suspect the 3rd 15m candle after GER40 open is long-biased when the first two close bullish — build it as a signal."
2. Claude (via the skills pipeline) attaches the project's node crate — once, aura nodes new ger40-lab-nodes — and implements the ThirdCandleLong node's schema + eval in it, against aura-core.
3. Backtest: an op-script wiring ger40_lab_nodes::ThirdCandleLong (§1, docs/authoring-guide.md) is built into blueprints/third-candle-long.json (aura graph build); aura run blueprints/third-candle-long.json --real GER40 --from 1704067200000 --to 1735689600000 (the window bounds are Unix milliseconds — here 2024) → the strategy produces a broker-independent, unsized bias stream (one signed, bounded f64 ∈ [-1,+1] per cycle — sign = direction, magnitude = optional conviction). A downstream risk-based executor (stop-rule → position-management, in R, the protective stop defining 1R) turns the bias into tracked trades, and the R-evaluator integrates the per-trade R-outcomes into an R-expectancy / R-curve — the signal's quality, measured account- and instrument-agnostically in R (E[R], SQN), not currency. Optionally compose a cost model — a C9 graph of cost nodes, in R (net R = gross R − cost-in-R) — to draw the net-R curve beside the gross one. The run yields an R-metrics table + a run record (manifest + metrics) under runs/. (Contract C10.) Money, a real broker, and a currency curve are a later live/deploy-edge concern (the only reliable ground truth, measured forward — never an authored historical "realistic broker"); the legacy SimBroker pip yardstick survives only as an optional dual readout, not the model.
4. Sweep / Monte-Carlo / matrix — a campaign document. Anything beyond a single backtest is experiment intent named in a campaign document (data, not Rust, §3 docs/authoring-guide.md): a parameter sweep, Monte-Carlo over seeds, or a structural matrix like "these 10 strategies × these 3 instruments × {fixed-stop, vol-stop} risk-executors" — instruments × windows × strategy × param axes × process, headless-authorable and registered under blueprints/. aura campaign run <content-id> bootstraps the matrix, fans the disjoint sims over all cores (C1), and writes the comparable runs to runs/.
5. Compose: "combine it with momentum-filter as a weighted sum" → Claude writes a composite node (fractal, C9).
6. Walk-forward: another experiment kind (rolling in-sample optimize + out-of-sample test) → an out-of-sample verdict.
7. Freeze: aura freeze blueprints/strategy-y.json --out bots/strategy-y → a standalone, statically-linked bot (C13); the live broker connection (e.g. cTrader Open API) is bound at this deploy edge — the only place account money appears, measured forward against a real venue, never an authored historical broker.
8. Explore — aura play. The playground plays any harness and shows what your sinks recorded (C22): live equity/signal streams while a run executes, and recorded traces + meta-views afterwards — stitched walk-forward equity, sweep surfaces, multi-strategy comparison. It is a trace explorer, not a scene editor (the World is a program; only sink-recorded data is visible — no sink, nothing to see). Topology you grow in Rust (hot-reload); runtime params you tune with sliders (C12).

The real value is not step 3 (one backtest — every quant system does that) but the World: steps 4/6 dynamically construct and orchestrate families of harnesses, and the playground explores those families. The single-harness engine is the substrate; the World is the product (C20–C22).

CLI command names and Aura.toml are illustrative; the concrete surface is designed with the relevant milestone (see the open threads in the design ledger). The forward-queue — what to try next — lives in the project's Gitea tracker, not in code (contract C18).