docs: update rule_order references, clarify dimension binding defaults, fix anchored rule syntax examples, and add use command documentation

Author: Alex Bikeyev

docs/reference/rule-engine-semantics.md

@@ -24,18 +24,18 @@ Rule semantics must preserve:
 
 ## Rule execution order
 
-Rules execute in the order specified by `workspace.formula_rule_order`. This list of rule IDs is the semantic contract. Do not rely on dictionary insertion order as a semantic execution contract — always use `formula_rule_order`.
+Rules execute in the order specified by `workspace.rule_order`. This list of rule IDs is the semantic contract. Do not rely on dictionary insertion order as a semantic execution contract — always use `rule_order`.
 
 ## Value precedence
 
 When a cell is evaluated, the engine resolves value precedence from highest to lowest:
 
-1. Hardcoded user override (`user_override_addrs`)
+1. Hardcoded user override (`cube.user_override_addrs`)
 2. Cell rule (single-cell rule)
 3. Slice rule (rule targeted at a pattern)
 4. Empty cell (`None`)
 
-A more specific rule always wins over a less specific rule. When two rules have the same specificity and match the same cell, the later rule in `workspace.formula_rule_order` wins.
+A more specific rule always wins over a less specific rule. When two rules have the same specificity and match the same cell, the later rule in `workspace.rule_order` wins.
 
 ## Rule invalidation
 
@@ -49,15 +49,15 @@ The system must not expose a durable state where deleted graph or item reference
 
 ## Rule deletion
 
-Deleting a rule must remove its rule ID from `workspace.formula_rule_order` in the same semantic mutation. The system must not persist dangling rule-order entries.
+Deleting a rule must remove its rule ID from `workspace.rule_order` in the same semantic mutation. The system must not persist dangling rule-order entries.
 
 ## Anti-patterns
 
 | Anti-pattern | Why we avoid | Correct approach |
 | --- | --- | --- |
 | Skipping dependency cleanup during recompute | Leaves stale state | Ensure recompute cleanup and indegree updates always run |
 | Rule references stored by label | Renames break rules | Resolve to stable IDs |
-| Relying on dict order for rule execution | Serialization drift | Use `workspace.formula_rule_order` |
+| Relying on dict order for rule execution | Serialization drift | Use `workspace.rule_order` |
 | Bidirectional recurrence | Ambiguous dependency direction | Use only `PREV` or only `NEXT` |
 | Writing to `PREV` / `NEXT` on LHS | Ambiguous mutation target | LHS may target only current cell or explicit slice |
 | Persisting error values | Reload corrupts state | Recalculate errors on load |

docs/reference/rule-syntax.md

@@ -96,15 +96,15 @@ This is **not** the same as `Year[2026]`. Bracket shorthand applies to a full cu
 
 ### Cube-relative shorthand on the RHS
 
-RHS references may use cube-relative shorthand. If a referenced cube shares a dimension with the current target cell, OM Core binds that dimension from the current evaluation context, provided the binding is unambiguous. Dimensions that do not exist in the referenced cube are ignored. A fully explicit address is always safer and required when the shorthand would be ambiguous.
+RHS references may use cube-relative shorthand. If a referenced cube shares a dimension with the current target cell, OM Core binds that dimension from the current evaluation context, provided the binding is unambiguous. Dimensions that do not exist in the referenced cube are not carried over; they default to the first item of that dimension in the target cube. A fully explicit address is always safer and required when the shorthand would be ambiguous.
 
 For example, if the target cell is `AnnualDep::Asset.Vehicle:Year.2026`, then this shorthand:
 
 ```text
 Inputs::[Metric.Cost]
 ```
 
-carries over the shared `Asset.Vehicle` context to resolve `Inputs::Asset.Vehicle:Metric.Cost`. The `Year` dimension is not carried over because `Inputs` does not have a `Year` dimension.
+carries over the shared `Asset.Vehicle` context to resolve `Inputs::Asset.Vehicle:Metric.Cost`. The `Year` dimension is not carried over because `Inputs` does not have a `Year` dimension; it would default to the first `Year` item of `Inputs` if that dimension existed there.
 
 Use the full semantic address whenever you need to read from a different context than the current target cell.
 
@@ -198,11 +198,11 @@ This behavior lets you define a general rule first and then add targeted overrid
 An **anchored rule** targets exactly one cell. The user opts in by prefixing the rule target with `$`.
 
 ```text
-rule $[Year.2024, Region.North] = 1100   # anchored: one cell
-rule  [Year.2024, Region.North] = 1100   # standard: slice (wildcarded)
+rule $Sales::@.value:Year.2024:Region.North = 1100   # anchored: one cell
+rule  Sales::@.value:Year.2024:Region.North = 1100   # standard: slice (wildcarded)
 ```
 
-The `$[...]` form is a **contextual shorthand** used when the active cube, channel, and view context are already known, such as in the grid or rule panel. In standalone scripts, prefer the full form:
+The `$` prefix is the only anchored shorthand available in standalone scripts. The bracket form `$[...]` is **not** accepted as a rule target; it is only valid in contextual input such as the grid or rule panel, where the active cube, channel, and view are already known. In scripts, prefer the full form:
 
 ```text
 rule Cube::@.value:Dim.Item:Dim.Item = expression
@@ -222,10 +222,10 @@ Example with a 3D cube `(Year, Region, Scenario)`:
 
 | Target | Anchored? | Scenario selector | Coverage |
 | --- | --- | --- | --- |
-| `$[Year.2024, Region.North, Scenario.Actual]` | Yes | `Actual` | One cell: `(2024, North, Actual)` |
-| `[Year.2024, Region.North]` | No | wildcard | Slice: `(2024, North, *)` |
+| `$Sales::@.value:Year.2024:Region.North:Scenario.Actual` | Yes | `Actual` | One cell: `(2024, North, Actual)` |
+| `Sales::@.value:Year.2024:Region.North` | No | wildcard | Slice: `(2024, North, *)` |
 
-Use `$` when entering a rule via the grid or rule panel to bind it to one specific cell. In scripts, use the full `Cube::@.channel:...` form and omit `$` when defining rules that should apply across dimensions.
+In scripts, use `$` only as a prefix on a full canonical address. In the grid or rule panel, the contextual `$[...]` form may be used to bind a rule to one specific cell.
 
 ## Error behavior
 
@@ -261,7 +261,7 @@ rule BS::@.value:BS.Cash:* = IF(POS(Year)=1, Drivers::@.value:Driver.OpeningCash
 ### Anchored rule
 
 ```text
-rule $[Year.2024, Region.North] = 1100
+rule $Sales::@.value:Year.2024:Region.North = 1100
 ```
 
 Prefer the full script form in standalone `.openm` files:
@@ -279,7 +279,7 @@ When generating rule syntax:
 - Use `[THIS]` for the current item, `[PREV]` / `[NEXT]` for recurrence on the RHS only.
 - Use `*` for slice wildcards on the LHS.
 - Use cube-relative shorthand (`Cube::[Dim.Item]`) only when the context binding is unambiguous.
-- Use `$` only for contextual input such as the grid or rule panel; in scripts, use the full `Cube::@.channel:...` form.
+- Use `$` only as a prefix on a full canonical address in scripts. Avoid the `$[...]` bracket form in standalone `.openm` files.
 - Avoid `PREV` / `NEXT` / `FIRST` / `LAST` on the LHS.
 - Avoid mixing `PREV` and `NEXT` in the same rule.
 - Reference cells by stable semantic address, not grid coordinates.

docs/reference/scripting.md

@@ -126,8 +126,8 @@ rule {{selected}} = 100000
 Use `exec {{cmd}}` to execute a command and capture its output.
 
 ```openm
-# Legacy $(selection) is deprecated. Use exec selection instead.
-cells=exec selection
+# Legacy $(timestamp) is deprecated. Use exec timestamp instead.
+ts=exec timestamp %Y%m%d_%H%M%S
 ```
 
 ### Legacy syntax
@@ -170,6 +170,15 @@ view PnL
 
 The first form defines a view. The second form activates it.
 
+#### `use` — set the active cube context
+
+```openm
+use Sales
+rule Revenue = Cost * 1.15
+```
+
+`use` sets the default cube for subsequent `rule` commands that omit a `Cube::` prefix. It is optional; explicit `Cube::@.value:...` addresses are preferred in scripts.
+
 ### Rule definition
 
 #### `rule` — define a calculation rule
@@ -211,7 +220,7 @@ References can also use bracket shorthand:
 rule AnnualDep::@.value:*.* = (Inputs::[Metric.Cost] - Inputs::[Metric.Salvage]) / Inputs::[Metric.Life]
 ```
 
-When a referenced cube shares a dimension with the current target cell, the shorthand binds that dimension from the context. Dimensions that do not exist in the referenced cube are ignored. For example, `AnnualDep` has dimensions `Asset` and `Year`, while `Inputs` has `Asset` and `Metric`. The shorthand `Inputs::[Metric.Cost]` binds the current `Asset` from the target cell but ignores the `Year` dimension because `Inputs` does not have one.
+When a referenced cube shares a dimension with the current target cell, the shorthand binds that dimension from the context. Dimensions that do not exist in the referenced cube are not carried over; they default to the first item of that dimension in the target cube. For example, `AnnualDep` has dimensions `Asset` and `Year`, while `Inputs` has `Asset` and `Metric`. The shorthand `Inputs::[Metric.Cost]` binds the current `Asset` from the target cell. The `Year` dimension is not carried over because `Inputs` does not have a `Year` dimension.
 
 ### Calculation
 
@@ -287,16 +296,18 @@ assert Inputs::@.value:Asset.Equipment:Metric.Life == 4 "Equipment life"
 
 ### Selection and navigation
 
-#### `selection` — return the current selection
+#### `selection` — show the current selection
 
 ```openm
-selected=exec selection
+selection
 ```
 
+Prints the current cursor position as `(row, col)`. It does not return a list of semantic addresses.
+
 #### `select`, `up`, `down`, `left`, `right` — navigate the grid
 
 ```openm
-select C::@.value:PL.Revenue:Year.2026
+select 5 2
 up 3
 right 2
 ```
@@ -372,6 +383,8 @@ When generating `.openm` scripts:
 - Place rules after dimensions and cubes.
 - Run `calc` after defining rules.
 - Use `assert` to verify expected values.
+- Use `use <cube>` to set an active cube context only when omitting the cube prefix in rules.
+- Use `$` as a prefix on a full canonical address for anchored rules; do not use the `$[...]` bracket form in scripts.
 
 ## See also