Document event types on dedicated pages

- Break the events guide into an index and per-event pages
- Give each page a field table and a strategy handler example
- Correct position event field matrix and pending-order transitions
- Repoint sibling concept links to the new events directory

Author: cjdsellers

docs/concepts/events/account_state.md

@@ -0,0 +1,42 @@
+# AccountState
+
+`AccountState` carries a snapshot of an account's balances and margins. It fires when the
+venue reports an account update (via the execution client), or when the `Portfolio`
+recalculates account state after a position update (for margin accounts with
+`calculate_account_state` enabled). The `Portfolio` subscribes to these events internally
+to maintain exposure and balance tracking.
+
+The `is_reported` flag distinguishes venue-reported snapshots from system-calculated ones.
+
+## Fields
+
+| Field           | Python type            | Required/default | Description                                                               |
+|-----------------|------------------------|------------------|---------------------------------------------------------------------------|
+| `account_id`    | `AccountId`            | Required         | The account ID (with the venue).                                          |
+| `account_type`  | `AccountType`          | Required         | The account type (`CASH`, `MARGIN`, or `BETTING`).                        |
+| `base_currency` | `Currency` or `None`   | Required         | The account base currency (`None` for multi‑currency accounts).           |
+| `is_reported`   | `bool`                 | Required         | If the state is reported from the exchange (otherwise system‑calculated). |
+| `balances`      | `list[AccountBalance]` | Required         | The account balances (may be empty).                                      |
+| `margins`       | `list[MarginBalance]`  | Required         | The margin balances (may be empty).                                       |
+| `info`          | `dict[str, object]`    | Required         | Additional implementation‑specific account information.                   |
+| `event_id`      | `UUID4`                | Required         | The event ID.                                                             |
+| `ts_event`      | `int`                  | Required         | UNIX timestamp (nanoseconds) when the event occurred.                     |
+| `ts_init`       | `int`                  | Required         | UNIX timestamp (nanoseconds) when the object was initialized.             |
+
+## Example
+
+Account state is normally consumed through the `Portfolio` rather than a dedicated handler:
+
+```python
+from nautilus_trader.model import Venue
+
+# Account state is tracked by the portfolio; query it by venue
+account = self.portfolio.account(Venue("BINANCE"))
+self.log.info(f"Account state: {account}")
+```
+
+## Related guides
+
+- [Events](index.md) - Event categories and dispatch.
+- [Accounting](../accounting.md) - Account types, balances, and margin models.
+- [Portfolio](../portfolio.md) - How account state feeds exposure and balance tracking.

docs/concepts/events.md docs/concepts/events/index.mddocs/concepts/events.md renamed to docs/concepts/events/index.md

@@ -41,30 +41,30 @@ omit the callback, the event is delivered to `on_event` instead.
 ## Order events
 
 Each order event corresponds to a state transition in the
-[order state machine](orders/index.md#order-state-flow). The `ExecutionEngine`
+[order state machine](../orders/index.md#order-state-flow). The `ExecutionEngine`
 applies the event to the order, updates the `Cache`, and publishes it on the
 `MessageBus`. The table below shows the primary transitions; partially filled
 and triggered orders support additional transitions documented in the full
-[order state flow](orders/index.md#order-state-flow).
-
-| Event                  | Primary transition                  | Handler                    |
-|------------------------|-------------------------------------|----------------------------|
-| `OrderInitialized`     | (created locally)                   | `on_order_initialized`     |
-| `OrderDenied`          | Initialized -> Denied               | `on_order_denied`          |
-| `OrderEmulated`        | Initialized -> Emulated             | `on_order_emulated`        |
-| `OrderReleased`        | Emulated -> Released                | `on_order_released`        |
-| `OrderSubmitted`       | Initialized/Released -> Submitted   | `on_order_submitted`       |
-| `OrderAccepted`        | Submitted -> Accepted               | `on_order_accepted`        |
-| `OrderRejected`        | Submitted -> Rejected               | `on_order_rejected`        |
-| `OrderTriggered`       | Accepted -> Triggered               | `on_order_triggered`       |
-| `OrderPendingUpdate`   | Accepted -> PendingUpdate           | `on_order_pending_update`  |
-| `OrderPendingCancel`   | Accepted -> PendingCancel           | `on_order_pending_cancel`  |
-| `OrderUpdated`         | PendingUpdate -> Accepted           | `on_order_updated`         |
-| `OrderModifyRejected`  | PendingUpdate -> Accepted           | `on_order_modify_rejected` |
-| `OrderCancelRejected`  | PendingCancel -> Accepted           | `on_order_cancel_rejected` |
-| `OrderCanceled`        | PendingCancel/Accepted -> Canceled  | `on_order_canceled`        |
-| `OrderExpired`         | Accepted -> Expired                 | `on_order_expired`         |
-| `OrderFilled`          | Accepted -> Filled/PartiallyFilled  | `on_order_filled`          |
+[order state flow](../orders/index.md#order-state-flow).
+
+| Event                                             | Primary transition                 | Handler                    |
+|---------------------------------------------------|------------------------------------|----------------------------|
+| [`OrderInitialized`](order_initialized.md)        | (created locally)                  | `on_order_initialized`     |
+| [`OrderDenied`](order_denied.md)                  | Initialized -> Denied              | `on_order_denied`          |
+| [`OrderEmulated`](order_emulated.md)              | Initialized -> Emulated            | `on_order_emulated`        |
+| [`OrderReleased`](order_released.md)              | Emulated -> Released               | `on_order_released`        |
+| [`OrderSubmitted`](order_submitted.md)            | Initialized/Released -> Submitted  | `on_order_submitted`       |
+| [`OrderAccepted`](order_accepted.md)              | Submitted -> Accepted              | `on_order_accepted`        |
+| [`OrderRejected`](order_rejected.md)              | Submitted -> Rejected              | `on_order_rejected`        |
+| [`OrderTriggered`](order_triggered.md)            | Accepted -> Triggered              | `on_order_triggered`       |
+| [`OrderPendingUpdate`](order_pending_update.md)   | Accepted -> PendingUpdate          | `on_order_pending_update`  |
+| [`OrderPendingCancel`](order_pending_cancel.md)   | Accepted -> PendingCancel          | `on_order_pending_cancel`  |
+| [`OrderUpdated`](order_updated.md)                | PendingUpdate -> previous status   | `on_order_updated`         |
+| [`OrderModifyRejected`](order_modify_rejected.md) | PendingUpdate -> previous status   | `on_order_modify_rejected` |
+| [`OrderCancelRejected`](order_cancel_rejected.md) | PendingCancel -> previous status   | `on_order_cancel_rejected` |
+| [`OrderCanceled`](order_canceled.md)              | PendingCancel/Accepted -> Canceled | `on_order_canceled`        |
+| [`OrderExpired`](order_expired.md)                | Accepted -> Expired                | `on_order_expired`         |
+| [`OrderFilled`](order_filled.md)                  | Accepted -> Filled/PartiallyFilled | `on_order_filled`          |
 
 ### Common order event fields
 
@@ -83,13 +83,14 @@ All order events share these fields:
 | `ts_event`         | Timestamp when the event occurred.       |
 | `ts_init`          | Timestamp when the event was created.    |
 
-Individual events add type-specific fields (e.g. `OrderFilled` adds
-`last_qty`, `last_px`, `trade_id`, `commission`). See the API reference
-for the full field list per event type.
+Each order event's page lists the type-specific fields it adds beyond this
+common set, plus which optional common fields are populated. For example,
+[`OrderFilled`](order_filled.md) adds `last_qty`, `last_px`, `trade_id`, and
+`commission`.
 
 :::tip
 Override `on_order_event` to handle all order events in one place. The specific
-handlers fire first, so you can mix both approaches.
+handlers fire first, so you can combine both approaches.
 :::
 
 ## Position events
@@ -98,11 +99,11 @@ Position events are a direct consequence of fill events. The `ExecutionEngine`
 processes each `OrderFilled`, updates or creates a position, and emits the
 corresponding position event.
 
-| Event               | When it fires                             | Handler               |
-|---------------------|-------------------------------------------|-----------------------|
-| `PositionOpened`    | First fill creates a new position.        | `on_position_opened`  |
-| `PositionChanged`   | Subsequent fill changes quantity or side. | `on_position_changed` |
-| `PositionClosed`    | Fill reduces quantity to zero.            | `on_position_closed`  |
+| Event                                    | When it fires                             | Handler               |
+|------------------------------------------|-------------------------------------------|-----------------------|
+| [`PositionOpened`](position_opened.md)   | First fill creates a new position.        | `on_position_opened`  |
+| [`PositionChanged`](position_changed.md) | Subsequent fill changes quantity or side. | `on_position_changed` |
+| [`PositionClosed`](position_closed.md)   | Fill reduces quantity to zero.            | `on_position_closed`  |
 
 ### From fill to position: the causal chain
 
@@ -157,6 +158,11 @@ sequenceDiagram
 
 ### Position event fields
 
+Every position event exposes all of these fields (they are defined on the `PositionEvent`
+base). A check mark means the field carries a meaningful value for that event; a dash means
+it is left at its zero or default (for example `avg_px_close` and `duration_ns` before a
+position closes).
+
 | Field                | Opened | Changed | Closed | Description                       |
 |----------------------|--------|---------|--------|-----------------------------------|
 | `trader_id`          | ✓      | ✓       | ✓      | Trader instance identifier.       |
@@ -170,17 +176,17 @@ sequenceDiagram
 | `side`               | ✓      | ✓       | ✓      | Current position side.            |
 | `signed_qty`         | ✓      | ✓       | ✓      | Signed quantity (negative=short). |
 | `quantity`           | ✓      | ✓       | ✓      | Unsigned position quantity.       |
-| `peak_qty`           | -      | ✓       | ✓      | Largest quantity held.            |
+| `peak_qty`           | ✓      | ✓       | ✓      | Largest quantity held.            |
 | `last_qty`           | ✓      | ✓       | ✓      | Quantity of the last fill.        |
 | `last_px`            | ✓      | ✓       | ✓      | Price of the last fill.           |
 | `currency`           | ✓      | ✓       | ✓      | Settlement currency.              |
 | `avg_px_open`        | ✓      | ✓       | ✓      | Average entry price.              |
 | `avg_px_close`       | -      | ✓       | ✓      | Average exit price.               |
 | `realized_return`    | -      | ✓       | ✓      | Realized return as a ratio.       |
-| `realized_pnl`       | -      | ✓       | ✓      | Realized profit and loss.         |
+| `realized_pnl`       | ✓      | ✓       | ✓      | Realized profit and loss.         |
 | `unrealized_pnl`     | -      | ✓       | ✓      | Unrealized profit and loss.       |
 | `duration_ns`        | -      | -       | ✓      | Time held in nanoseconds.         |
-| `ts_opened`          | -      | ✓       | ✓      | Timestamp when position opened.   |
+| `ts_opened`          | ✓      | ✓       | ✓      | Timestamp when position opened.   |
 | `ts_closed`          | -      | -       | ✓      | Timestamp when position closed.   |
 | `event_id`           | ✓      | ✓       | ✓      | Unique event identifier.          |
 | `ts_event`           | ✓      | ✓       | ✓      | Timestamp of the triggering fill. |
@@ -211,7 +217,8 @@ opening_order_id = position.opening_order_id
 
 Account state contains balances, margins, account type, and base currency.
 The `Portfolio` subscribes to these events internally to maintain exposure
-and balance tracking.
+and balance tracking. See [`AccountState`](account_state.md) for the full
+field list.
 
 ## Event subscriptions
 
@@ -230,12 +237,12 @@ These are useful for monitoring actors that track execution quality or fill
 rates across strategies without participating in order management.
 
 For details and examples, see
-[Order event subscriptions](actors.md#order-event-subscriptions).
+[Order event subscriptions](../actors.md#order-event-subscriptions).
 
 ## Related guides
 
-- [Orders](orders/) - Order types and state machine.
-- [Positions](positions.md) - Position lifecycle and PnL.
-- [Execution](execution.md) - Execution flow and risk checks.
-- [Strategies](strategies.md) - Handler implementations in strategies.
-- [Architecture](architecture.md) - Data and execution flow patterns.
+- [Orders](../orders/) - Order types and state machine.
+- [Positions](../positions.md) - Position lifecycle and PnL.
+- [Execution](../execution.md) - Execution flow and risk checks.
+- [Strategies](../strategies.md) - Handler implementations in strategies.
+- [Architecture](../architecture.md) - Data and execution flow patterns.

docs/concepts/events/order_accepted.md

@@ -0,0 +1,29 @@
+# OrderAccepted
+
+`OrderAccepted` represents an order having been accepted by the trading venue. The
+`ExecutionEngine` applies it to the order, updates the `Cache`, and publishes it on the
+`MessageBus`. It fires when the venue acknowledges the order as received and valid (often
+a FIX `NEW` OrdStatus).
+
+Transition: `SUBMITTED` -> `ACCEPTED`. Handler: `on_order_accepted`.
+
+## Fields
+
+`OrderAccepted` carries only the [common order event fields](index.md#common-order-event-fields). On this event, `venue_order_id` and `account_id` are
+populated, and `reconciliation` carries a real value (default `False`).
+
+## Example
+
+Reading the event in a strategy handler:
+
+```python
+def on_order_accepted(self, event: OrderAccepted) -> None:
+    self.log.info(
+        f"Order {event.client_order_id} accepted as {event.venue_order_id}",
+    )
+```
+
+## Related guides
+
+- [Events](index.md) - Event categories, dispatch, and the common order event fields.
+- [Orders](../orders/) - Order types and the state machine.

docs/concepts/events/order_cancel_rejected.md

@@ -0,0 +1,35 @@
+# OrderCancelRejected
+
+`OrderCancelRejected` represents a `CancelOrder` command having been rejected by the
+trading venue. The `ExecutionEngine` applies it to the order, updates the `Cache`, and
+publishes it on the `MessageBus`. It fires when the venue rejects a cancel request.
+
+Transition: `PENDING_CANCEL` -> previous status (for example `ACCEPTED`). Handler:
+`on_order_cancel_rejected`.
+
+## Fields
+
+Beyond the [common order event fields](index.md#common-order-event-fields), `OrderCancelRejected` carries:
+
+| Field    | Python type | Required/default | Description                       |
+|----------|-------------|------------------|-----------------------------------|
+| `reason` | `str`       | Required         | The order cancel rejected reason. |
+
+On this event, `venue_order_id` and `account_id` are usually populated but may be `None`,
+and `reconciliation` carries a real value.
+
+## Example
+
+Reading the event in a strategy handler:
+
+```python
+def on_order_cancel_rejected(self, event: OrderCancelRejected) -> None:
+    self.log.warning(
+        f"Cancel rejected for {event.client_order_id}: {event.reason}",
+    )
+```
+
+## Related guides
+
+- [Events](index.md) - Event categories, dispatch, and the common order event fields.
+- [Orders](../orders/) - Order types and the state machine.

docs/concepts/events/order_canceled.md

@@ -0,0 +1,26 @@
+# OrderCanceled
+
+`OrderCanceled` represents an order having been canceled at the trading venue. The
+`ExecutionEngine` applies it to the order, updates the `Cache`, and publishes it on the
+`MessageBus`. It fires when the venue confirms cancellation of the order.
+
+Transition: `PENDING_CANCEL` / `ACCEPTED` -> `CANCELED`. Handler: `on_order_canceled`.
+
+## Fields
+
+`OrderCanceled` carries only the [common order event fields](index.md#common-order-event-fields). On this event, `venue_order_id` and `account_id` are
+usually populated but may be `None`, and `reconciliation` carries a real value.
+
+## Example
+
+Reading the event in a strategy handler:
+
+```python
+def on_order_canceled(self, event: OrderCanceled) -> None:
+    self.log.info(f"Order {event.client_order_id} canceled")
+```
+
+## Related guides
+
+- [Events](index.md) - Event categories, dispatch, and the common order event fields.
+- [Orders](../orders/) - Order types and the state machine.

docs/concepts/events/order_denied.md

@@ -0,0 +1,34 @@
+# OrderDenied
+
+`OrderDenied` represents an order having been denied by the Nautilus system. The
+`ExecutionEngine` applies it to the order, updates the `Cache`, and publishes it on the
+`MessageBus`. It fires when an otherwise valid order cannot be submitted, for example due
+to a risk limit or an unsupported feature.
+
+Transition: `INITIALIZED` -> `DENIED`. Handler: `on_order_denied`.
+
+## Fields
+
+Beyond the [common order event fields](index.md#common-order-event-fields), `OrderDenied` carries:
+
+| Field    | Python type | Required/default | Description              |
+|----------|-------------|------------------|--------------------------|
+| `reason` | `str`       | Required         | The order denied reason. |
+
+On this event, `venue_order_id` and `account_id` are both `None`, `reconciliation` is
+always `False`, and `ts_event` equals `ts_init`.
+
+## Example
+
+Reading the event in a strategy handler:
+
+```python
+def on_order_denied(self, event: OrderDenied) -> None:
+    self.log.warning(f"Order {event.client_order_id} denied: {event.reason}")
+```
+
+## Related guides
+
+- [Events](index.md) - Event categories, dispatch, and the common order event fields.
+- [Execution](../execution.md) - Risk checks and order denied reasons.
+- [Orders](../orders/) - Order types and the state machine.

docs/concepts/events/order_emulated.md

@@ -0,0 +1,26 @@
+# OrderEmulated
+
+`OrderEmulated` represents an order having become emulated by the Nautilus system. The
+`ExecutionEngine` applies it to the order, updates the `Cache`, and publishes it on the
+`MessageBus`. It fires when the `OrderEmulator` takes an order under local emulation.
+
+Transition: `INITIALIZED` -> `EMULATED`. Handler: `on_order_emulated`.
+
+## Fields
+
+`OrderEmulated` carries only the [common order event fields](index.md#common-order-event-fields). On this event, `venue_order_id` and `account_id` are
+both `None`, `reconciliation` is always `False`, and `ts_event` equals `ts_init`.
+
+## Example
+
+Reading the event in a strategy handler:
+
+```python
+def on_order_emulated(self, event: OrderEmulated) -> None:
+    self.log.info(f"Order {event.client_order_id} is now emulated locally")
+```
+
+## Related guides
+
+- [Events](index.md) - Event categories, dispatch, and the common order event fields.
+- [Emulated orders](../orders/emulated.md) - The local emulation lifecycle.

docs/concepts/events/order_expired.md

@@ -0,0 +1,27 @@
+# OrderExpired
+
+`OrderExpired` represents an order having expired at the trading venue. The
+`ExecutionEngine` applies it to the order, updates the `Cache`, and publishes it on the
+`MessageBus`. It fires when the order reaches its expiry (for example a GTD order) at the
+venue.
+
+Transition: `ACCEPTED` -> `EXPIRED`. Handler: `on_order_expired`.
+
+## Fields
+
+`OrderExpired` carries only the [common order event fields](index.md#common-order-event-fields). On this event, `venue_order_id` and `account_id` are
+usually populated but may be `None`, and `reconciliation` carries a real value.
+
+## Example
+
+Reading the event in a strategy handler:
+
+```python
+def on_order_expired(self, event: OrderExpired) -> None:
+    self.log.info(f"Order {event.client_order_id} expired")
+```
+
+## Related guides
+
+- [Events](index.md) - Event categories, dispatch, and the common order event fields.
+- [Orders](../orders/) - Order types and the state machine.