feat(aura-cli): surviving-surface prose — scaffold template, concepts help, sweep-vehicle tests

Slice 5 of the #319 retirement. The scaffolder's project CLAUDE.md and the
CLI concepts help now teach only the surviving surface (exec over both
document classes, --override, graph introspect --params for discovery;
traces via exec --tap / presentation.persist_taps). Sweep vehicles moved
onto campaign documents driven by exec (project_new's starter quickstarts,
cli_broken_pipe — whose bare-sweep EPIPE probe was latently vacuous and now
streams a real 4-member campaign, project_sweep_campaign's real-data leg,
graph_construct's gang-axis parity pair as paired one-cell campaigns);
pure discovery sites became graph introspect --params, and the line-identity
test kept its literal --params expectations minus the sweep half. Help pins
rewritten; the scaffold template's in-src pin follows the new bytes.

refs #319
This commit is contained in:
2026-07-25 19:34:07 +02:00
parent 5dc8e03249
commit 24782caaec
8 changed files with 573 additions and 221 deletions
+9 -9
View File
@@ -1153,20 +1153,20 @@ fn version_string() -> &'static str {
const CONCEPTS_HELP: &str = "\
Author, backtest, and validate trading strategies — research CLI.
Two layers, one vocabulary: the research verbs are the convenience surface —
over --real data, sweep, walkforward, mc, and generalize desugar to
registered process/campaign documents and execute them (run is their
single-backtest sibling; synthetic runs execute in-process). That document
data plane is directly authorable: `aura process` / `aura campaign`
(validate | introspect | register | run), growing a document from a bare {}
via `introspect --unwired`.
Two layers, one vocabulary: `aura exec` is the one executor over both document classes
— a registered campaign (file or content id) or a signal blueprint (single
run; synthetic runs execute in-process). That document data plane is
directly authorable: `aura process` / `aura campaign` (validate | introspect
| register), growing a document from a bare {} via `introspect --unwired`;
axis discovery is `aura graph introspect --params`.
Execution model: a strategy emits a bias in [-1,+1] per cycle, held as the
continuously-tracked target position; a protective stop defines the risk unit
R, and signal quality is measured in R.
Traces: `sweep --real --trace` / `walkforward --real --trace` record per-cycle
taps under runs/, consumed by `aura chart` and `aura measure`.";
Traces: `exec <blueprint.json> --tap NAME=FOLD` (or a campaign document's
`presentation.persist_taps`) record per-cycle taps under runs/, consumed by
`aura chart` and `aura measure`.";
#[derive(Parser)]
#[command(
+12 -11
View File
@@ -231,12 +231,13 @@ const CLAUDE_MD_PROJECT: &str = r#"# __NAME__ — an aura research project (data
This directory is an aura project: blueprints + research documents over the
std vocabulary, anchored by `Aura.toml`. There is no crate and no build step.
- Run: `aura run blueprints/signal.json` (the starter is closed — all
params bound; bound values are defaults — any `--axis` may override them
(#246))
- Sweep: `aura sweep blueprints/signal.json --axis fast.length=2,4,8`
(`aura sweep <bp> --list-axes` lists the open + bound-overridable axes, RAW
`<node>.<param>` names — #328)
- Run: `aura exec blueprints/signal.json` (single smoke run, synthetic stream
— the starter is closed; all params bound; bound values are defaults —
`--override NODE.PARAM=VALUE` may override one for this run (#246))
- Campaign: `aura exec <campaign.json>` executes a registered campaign
document (file or content id) — the multi-cell/axis surface
- Axes: `aura graph introspect --params blueprints/signal.json` lists the
open + bound-overridable axes, RAW `<node>.<param>` names (#328)
- Native nodes: when the project needs its first project-specific node,
`aura nodes new <name>` scaffolds a node crate beside this project and
attaches it via `[nodes]` in `Aura.toml` (build it with `cargo build`).
@@ -459,12 +460,12 @@ mod tests {
}
let claude = render_project(CLAUDE_MD_PROJECT, "demo-lab");
assert!(claude.contains("demo-lab"));
// The CLAUDE.md sweep quickstart targets the closed starter itself
// with the RAW axis name (#246: a bound param is a default an axis
// overrides; #328: the axis namespace is raw, no blueprint-name
// prefix).
// The CLAUDE.md quickstart targets the closed starter itself through
// the surviving surface (#319): exec for both document classes, the
// #246 override residue, and raw-namespace axis discovery (#328).
assert!(claude.contains("blueprints/signal.json"));
assert!(claude.contains("--axis fast.length"));
assert!(claude.contains("--override NODE.PARAM=VALUE"));
assert!(claude.contains("graph introspect --params"));
}
/// #315: the scaffolded project CLAUDE.md teaches the execution semantics