<!-- Generated by scripts/generate_language_docs.py. Do not edit directly. -->

# Quawd language quick-start

Author incrementally with typed JSON. Every variant selects its kind; indicators also select indicator.
Unknown fields are refused. The signatures in overview are reference notation, not executable text syntax.

## Mental model

- ValueRef produces a value: price, indicator, arithmetic, event, universe or position data.
- Condition expresses compare/cross/range/pattern logic, composition, a schedule or a protective policy.
- A definition stores reusable condition source. Saving it alone activates nothing.
- A rule uses a definition as entry, gate or exit. add_rule saves and attaches in one call.
- Configuration controls sizing, position policy, execution, risk and allocation.

## Collections

A basket applies one strategy to multiple instruments; a portfolio combines member strategies.
Both use allocation={construction:{kind:...}, rebalance:{kind:...}, capital_model:...}.
Use config:allocation for baskets and config:portfolio_allocation for portfolios; their admitted modes differ.
Portfolio declarations: portfolio:member, portfolio:shared_signal, portfolio:create, portfolio:update.
Specification.collection_examples contains validated mode examples and prerequisites.
Manual weights live only in construction.weights. update_portfolio takes portfolio_id and a typed patch.
Omitted patch fields preserve; allocation null clears; shared_signals [] clears. Invalid resulting configurations are refused.

## Choose the operation

Use create_strategy, then add_rule for recursive source, and builder_set_strategy_config for configuration.
Use builder_add_condition only to save reusable source; builder_attach_rule activates a saved definition.
builder_compose is useful for saved definitions; inline Boolean/sequence children need no separate calls.
Inspect with builder_get_strategy. Edit a definition with builder_update_condition and its expected_source_version.
Compile to check admission before running a backtest. A valid draft alone does not establish runnability.

## Semantics to check

compare tests a level on each evaluation; cross fires at a crossing edge. Use transition for categorical changes.
Entry grouping is all_of: separate same-side entries must fire on the same bar. Put alternatives in one any_of.
Simultaneous long/short entry conflict policy is skip.
Position policy controls repeated entries and reversal; inspect entry_behavior for the selected mode.
Protective exit policies belong directly in exit rules, not under Boolean combinators. fixed_targets with only time_stop_bars is a predicate and may be combined.
Clock schedules retain current role/nesting admission; there is no separate rule schedule slot.
Position-scoped operands need a position context; a signal scan does not provide one.
Basket instruments share one strategy definition; portfolios combine member strategies. Allocation uses construction.kind and rebalance.kind. Manual weights belong only in construction. Portfolio updates use a patch: omitted fields preserve, allocation null clears, shared_signals [] clears. Construction-managed rotation refuses member entry/gate/exit/protective logic. Member rotation retains member logic but may trim and top up holdings. Member rotations require partitioned capital; cash reserves are refused on rotations. Portfolio walk-forward has no parameter optimization. Published structure does not replace mode-specific allocation admission or compiled-member plan checks.
Execution price and allocation score positions have narrower schemas than ValueRef.
Units vary by operand: use published output_units and exact indicator output fields.

## Complete example: SPY RSI recovery

Replace <project_id>, <strategy_id> and <backtest_id> with returned IDs; pass them unchanged.
Check SPY data availability with list_assets. The 4h gate uses the higher-timeframe data available to the engine.
Calls below are tool names followed by JSON arguments, not a second programming language.

### 1. project_create

Create a project, or reuse an owned project from project_list. Use its returned id as project_id.

```json
{
  "name": "RSI recovery research"
}
```

### 2. create_strategy

Create a draft. Keep the returned strategy_id for subsequent calls.

```json
{
  "name": "SPY RSI recovery",
  "symbols": [
    "SPY"
  ],
  "timeframe": "1h",
  "project_id": "<project_id>"
}
```

### 3. builder_set_strategy_config

Set the position size explicitly.

```json
{
  "strategy_id": "<strategy_id>",
  "patch": {
    "sizing": {
      "mode": "fixed_usd",
      "fixed_usd": 5000
    }
  }
}
```

### 4. add_rule

Attach the complete sequence as one entry rule; no child saves or composition calls.

```json
{
  "strategy_id": "<strategy_id>",
  "name": "rsi_recovery",
  "role": "entry",
  "direction": "long",
  "condition": {
    "kind": "sequence",
    "steps": [
      {
        "condition": {
          "kind": "cross",
          "left": {
            "kind": "indicator",
            "indicator": "rsi",
            "period": 14
          },
          "right": 35,
          "direction": "below"
        }
      },
      {
        "condition": {
          "kind": "cross",
          "left": {
            "kind": "indicator",
            "indicator": "rsi",
            "period": 14
          },
          "right": 45,
          "direction": "above"
        },
        "within_bars": 6
      }
    ]
  }
}
```

### 5. add_rule

Permit entries only while the 4h trend predicate is true.

```json
{
  "strategy_id": "<strategy_id>",
  "name": "trend",
  "role": "gate",
  "condition": {
    "kind": "compare",
    "left": {
      "kind": "price",
      "field": "close",
      "resolution": "4h"
    },
    "op": ">",
    "right": {
      "kind": "indicator",
      "indicator": "ema",
      "period": 100,
      "resolution": "4h"
    }
  }
}
```

### 6. add_rule

Exit when RSI exceeds 65 or the open position reaches 12 bars.

```json
{
  "strategy_id": "<strategy_id>",
  "name": "timeout_or_rsi",
  "role": "exit",
  "direction": "long",
  "condition": {
    "kind": "any_of",
    "conditions": [
      {
        "kind": "compare",
        "left": {
          "kind": "indicator",
          "indicator": "rsi",
          "period": 14
        },
        "op": ">",
        "right": 65
      },
      {
        "kind": "compare",
        "left": {
          "kind": "live_position",
          "field": "bars_in_position"
        },
        "op": ">=",
        "right": 12
      }
    ]
  }
}
```

### 7. builder_get_strategy

Review source, active rules, unattached_definitions and entry_behavior.

```json
{
  "strategy_id": "<strategy_id>"
}
```

### 8. builder_compile

Check compilation/admission and inspect warnings before running research.

```json
{
  "strategy_id": "<strategy_id>"
}
```

### 9. run_backtest

Request two years; inspect actual coverage, admitted dates and warnings in the result.

```json
{
  "strategy_id": "<strategy_id>",
  "lookback": "2y"
}
```

### 10. get_backtest

If the run is queued, follow its returned instructions until terminal; inspect results and warnings.

```json
{
  "backtest_id": "<backtest_id>",
  "detail": "summary"
}
```

## Learn more and recover from errors

builder_discover(action='overview') gives the complete inventory; detail='full' adds defaults and bounds.
Use action='get', ref='condition:sequence' or 'indicator_shape:rsi' for exact primitive guidance.
Use action='specification' for the recursive JSON Schema graph and registered operation schemas.
Schema validates structure; parser/compiler admission also checks roles, references, data and execution context.
On refusal, correct the reported field or placement. Read current source/version before retrying a stale edit.
For sweeps and walk-forward, inspect get_strategy_patch_schemas first; editable source is not automatically sweepable.
Signal scans have no open-position context and refuse clock schedules; choose a supported predicate.