Update v0.15.0

- Added dynamic risk group creation with auto-assignment based on attribute matching and generation from unique attribute values.
- Implemented risk group validation to detect undefined references and circular hierarchies at load time.

Author: networmix

.claude/skills/netgraph-dsl/SKILL.md

@@ -9,14 +9,30 @@ description: >
 license: MIT
 metadata:
   author: "netgraph"
-  version: "1.0"
+  version: "1.1"
   repo: "https://github.com/networmix/NetGraph"
 ---
 
 # NetGraph DSL
 
 Define network simulation scenarios in YAML format.
 
+> **Quick Start**: See [Minimal Example](#minimal-example) below.
+> **Complete Reference**: See [references/REFERENCE.md](references/REFERENCE.md) for full documentation.
+
+## Instructions
+
+When working with NetGraph scenarios:
+
+1. **Creating new scenarios**: Start with the [Minimal Example](#minimal-example), then add sections as needed
+2. **Editing existing scenarios**: Identify the relevant section (network, traffic_matrix_set, failure_policy_set, etc.)
+3. **Understanding selection**: Review [Selection Models](#selection-models) to understand path-based vs condition-based selection
+4. **Debugging issues**: Check [Common Pitfalls](#common-pitfalls) and [Validation Checklist](#validation-checklist)
+5. **Complex topologies**: Use [Blueprints](#blueprints) for reusable patterns
+6. **Failure simulation**: Define [Risk Groups](#risk-groups) before creating failure policies
+
+Refer to specific sections below for detailed syntax and examples.
+
 ## Quick Reference
 
 | Section | Purpose |
@@ -48,6 +64,28 @@ network:
 
 ## Core Patterns
 
+### Selection Models
+
+The DSL implements two distinct selection patterns:
+
+**1. Path-based Node Selection** (adjacency rules, traffic demands, workflow steps)
+
+- Uses regex patterns on hierarchical node names
+- Supports capture group-based grouping
+- Supports attribute-based grouping (`group_by`)
+- Supports attribute filtering (`match` conditions)
+- Supports `active_only` filtering
+
+**2. Condition-based Entity Selection** (failure rules, membership rules, risk group generation)
+
+- Works on nodes, links, or risk_groups (`entity_scope`)
+- Uses only attribute-based filtering (`conditions`)
+- No path/regex patterns (operates on all entities of specified type)
+
+These patterns share common primitives (condition evaluation, match specification) but serve different purposes and should not be confused.
+
+> **For comprehensive details** on entity creation flows, processing steps, and comparison tables, see the [Entity Creation Architecture](references/REFERENCE.md#entity-creation-architecture) section in the full reference.
+
 ### Nodes and Links
 
 ```yaml
@@ -134,7 +172,7 @@ adjacency:
   - source:
       path: "/datacenter"
       match:
-        logic: and         # "and" or "or" (default)
+        logic: and         # "and" or "or"; defaults vary by context (see below)
         conditions:
           - attr: role
             operator: "=="
@@ -145,6 +183,15 @@ adjacency:
 
 **Operators**: `==`, `!=`, `<`, `<=`, `>`, `>=`, `contains`, `not_contains`, `in`, `not_in`, `any_value`, `no_value`
 
+**Logic defaults by context**:
+
+| Context | Default `logic` | Rationale |
+|---------|-----------------|-----------|
+| Adjacency `match` | `"or"` | Inclusive: match any condition |
+| Demand `match` | `"or"` | Inclusive: match any condition |
+| Membership rules | `"and"` | Precise: must match all conditions |
+| Failure rules | `"or"` | Inclusive: match any condition |
+
 ### Capturing Groups for Grouping
 
 ```yaml
@@ -226,6 +273,47 @@ failure_policy_set:
 
 **Rule types**: `all` (select all matches), `choice` (sample `count`), `random` (each with `probability`)
 
+### Risk Groups
+
+Risk groups model failure correlation (shared infrastructure, geographic regions, vendor dependencies, or any custom domain). Three methods:
+
+**Direct definition:**
+
+```yaml
+risk_groups:
+  - name: "RG1"              # Full form
+  - "RG2"                    # String shorthand (equivalent to {name: "RG2"})
+```
+
+**Membership rules** (assign entities by attribute matching):
+
+```yaml
+risk_groups:
+  - name: HighCapacityLinks
+    membership:
+      entity_scope: link     # node, link, or risk_group
+      match:
+        logic: and           # "and" or "or" (default: "and" for membership)
+        conditions:
+          - attr: capacity
+            operator: ">="
+            value: 1000
+```
+
+**Generate blocks** (create groups from unique attribute values):
+
+```yaml
+risk_groups:
+  - generate:
+      entity_scope: node     # node or link only
+      group_by: region       # Any attribute to group by
+      name_template: "Region_${value}"
+```
+
+**Validation:** Risk group references are validated at load time (undefined references and circular hierarchies detected).
+
+See [REFERENCE.md](references/REFERENCE.md) for complete details.
+
 ### Workflow
 
 ```yaml

.claude/skills/netgraph-dsl/references/EXAMPLES.md

@@ -838,7 +838,118 @@ failure_policy_set:
 
 **Result**: Hierarchical risk groups with recursive child failure expansion
 
-## Example 17: Additional Selector Operators
+## Example 17: Risk Group Membership Rules
+
+Dynamically assign entities based on attributes.
+
+```yaml
+network:
+  nodes:
+    core1: {attrs: {role: core, tier: 3, datacenter: dc1}}
+    core2: {attrs: {role: core, tier: 3, datacenter: dc2}}
+    edge1: {attrs: {role: edge, tier: 1, datacenter: dc1}}
+    edge2: {attrs: {role: edge, tier: 1, datacenter: dc2}}
+  links:
+    - source: core1
+      target: core2
+      link_params:
+        capacity: 1000
+        attrs:
+          route_type: backbone
+          path_id: primary
+    - source: core1
+      target: edge1
+      link_params: {capacity: 400}
+
+risk_groups:
+  # Assign all core tier-3 nodes
+  - name: CoreTier3
+    membership:
+      entity_scope: node
+      match:
+        logic: and              # Must match ALL conditions
+        conditions:
+          - attr: role
+            operator: "=="
+            value: core
+          - attr: tier
+            operator: "=="
+            value: 3
+
+  # Assign links by route type
+  - name: BackboneLinks
+    membership:
+      entity_scope: link
+      match:
+        logic: and
+        conditions:
+          - attr: route_type      # Dot-notation for nested attrs
+            operator: "=="
+            value: backbone
+
+  # String shorthand for simple groups
+  - "ManualGroup1"
+```
+
+**Result**: Nodes and links automatically assigned to risk groups based on attributes
+
+## Example 18: Generated Risk Groups
+
+Create risk groups from unique attribute values.
+
+```yaml
+network:
+  nodes:
+    srv1: {attrs: {datacenter: dc1, rack: r1}}
+    srv2: {attrs: {datacenter: dc1, rack: r2}}
+    srv3: {attrs: {datacenter: dc2, rack: r1}}
+  links:
+    - source: srv1
+      target: srv2
+      link_params:
+        capacity: 100
+        attrs:
+          connection_type: intra_dc
+    - source: srv2
+      target: srv3
+      link_params:
+        capacity: 100
+        attrs:
+          connection_type: inter_dc
+
+risk_groups:
+  # Generate risk group per datacenter (from nodes)
+  - generate:
+      entity_scope: node
+      group_by: datacenter
+      name_template: "DC_${value}"
+      attrs:
+        generated: true
+        type: location
+
+  # Generate risk group per rack (from nodes)
+  - generate:
+      entity_scope: node
+      group_by: rack
+      name_template: "Rack_${value}"
+
+  # Generate risk group per connection type (from links)
+  - generate:
+      entity_scope: link
+      group_by: connection_type
+      name_template: "Links_${value}"
+```
+
+**Result**: Creates 6 risk groups:
+
+- `DC_dc1` (srv1, srv2)
+- `DC_dc2` (srv3)
+- `Rack_r1` (srv1, srv3)
+- `Rack_r2` (srv2)
+- `Links_intra_dc` (link srv1→srv2)
+- `Links_inter_dc` (link srv2→srv3)
+
+## Example 19: Additional Selector Operators
 
 Demonstrating all condition operators.