Overhaul Rule Builder Documentation with User-First Terminology

content/en/advanced-concepts/architecture/engine/execution-engine.md

@@ -105,6 +105,6 @@ Rule conditions and templates are evaluated using `SafeFrappeAPI`, preventing un
 
 ## Related Topics
 
-- [Rule Building]({{< relref "rule-builder/canvas-navigation.md" >}})
+- [Rule Building]({{< relref "rule-builder/canvas.md" >}})
 - [Glossary]({{< relref "advanced-concepts/reference/glossary.md" >}})
 - [API Reference]({{< relref "api-reference/public-apis.md" >}})

content/en/advanced-concepts/decision-trees.md

@@ -84,5 +84,5 @@ Need to process a collection?
 ## Related Topics
 
 - [Glossary]({{< relref "advanced-concepts/reference/glossary.md" >}})
-- [Rule Builder]({{< relref "rule-builder/canvas-navigation.md" >}})
+- [Rule Builder]({{< relref "rule-builder/canvas.md" >}})
 - [Action Zone]({{< relref "action-types/" >}})

content/en/advanced-concepts/reference/doctypes.md

@@ -54,7 +54,7 @@ The primary container for an automation flow. It defines **when** logic starts a
 Represents a single executable node (Step) within a Rule's graph.
 
 ### When to Use
-- Rule Actions are managed via the [Rule Builder]({{< relref "rule-builder/canvas-navigation.md" >}}), which handles the creation of these child records automatically.
+- Rule Actions are managed via the [Rule Builder]({{< relref "rule-builder/canvas.md" >}}), which handles the creation of these child records automatically.
 
 | Field | Type | Description |
 | :--- | :--- | :--- |
@@ -94,5 +94,5 @@ Audit trail for every rule execution.
 ## Related Topics
 
 - [Execution Engine]({{< relref "advanced-concepts/architecture/engine/execution-engine.md" >}})
-- [Rule Builder]({{< relref "rule-builder/canvas-navigation.md" >}})
+- [Rule Builder]({{< relref "rule-builder/canvas.md" >}})
 - [API Reference]({{< relref "api-reference/public-apis.md" >}})

content/en/advanced-concepts/reference/glossary.md

@@ -48,4 +48,4 @@ Common terminology and core concepts used throughout the FlexiRule documentation
 
 - [System Architecture]({{< relref "advanced-concepts/architecture/" >}})
 - [Execution Engine]({{< relref "advanced-concepts/architecture/engine/execution-engine.md" >}})
-- [Rule Building]({{< relref "rule-builder/canvas-navigation.md" >}})
+- [Rule Building]({{< relref "rule-builder/canvas.md" >}})

content/en/rule-builder/_index.md

@@ -1,5 +1,31 @@
 ---
 title: Rule Builder Guide
 weight: 40
-description: Deep dive into the Visual Rule Builder UI and configuration.
+description: Learn how to use the visual interface to build and manage your business rules.
 ---
+
+# Rule Builder Guide
+
+The Rule Builder is the heart of FlexiRule. it provides a powerful, visual "drag-and-drop" interface that allows you to orchestrate complex business logic without writing code.
+
+## In this Section
+
+- **[Canvas Navigation]({{< relref "canvas.md" >}})**: Learn how to move around the workspace and arrange your logic blocks.
+- **[Adding Actions]({{< relref "add-action.md" >}})**: Discover how to use the Action Zone to insert new logic into your flow.
+- **[Rule Configuration]({{< relref "rule-configuration.md" >}})**: Set up the triggers and global settings that define when your rule runs.
+- **[Smart Value System]({{< relref "smart-value-system.md" >}})**: Master the unified system for providing inputs using static values, variables (@), and resolvers (/).
+- **[Condition Builder]({{< relref "condition-builder.md" >}})**: Build complex logical branches using a simple visual interface.
+- **[Action Settings]({{< relref "action-settings.md" >}})**: Configure the details of individual blocks.
+- **[Rule Lifecycle]({{< relref "rule-lifecycle.md" >}})**: Understand the stages of a rule from draft to active production.
+- **[Debugging & Logs]({{< relref "debugging.md" >}})**: Test your rules safely and troubleshoot live executions.
+
+## Key Concepts
+
+### Visual Flow
+FlexiRule represents logic as a flowchart. You can see exactly how data moves from a trigger event to the final outcome.
+
+### Unified Input (Smart Values)
+Instead of writing scripts, you use the **Smart Value System** to pick fields, apply formulas, and set values. This unified approach works the same way across the entire builder.
+
+### Safety First
+With built-in **Debugging** and a version-controlled **Lifecycle**, you can build and update automations with confidence, knowing that your live operations are protected.

content/en/rule-builder/action-settings.md

@@ -0,0 +1,53 @@
+---
+title: Action Settings
+description: Learn how to configure individual blocks in your rule.
+weight: 60
+---
+
+# Action Settings
+
+When you select a block on the canvas, the **Action Settings** panel slides out from the right side of the screen. This is where you define the specific behavior for that step in your rule.
+
+## Common Interface Elements
+
+While every action has different options, they all share a consistent design:
+
+-   **Block Title**: At the top, you can see and edit the name of the block.
+-   **Description**: A brief explanation of what the action does.
+-   **Configuration Fields**: The main area where you input data, select options, and define logic.
+
+## Smart Value Fields
+
+Most settings in FlexiRule use "Smart" fields. These fields allow you to provide data in three different ways: static text, variables, or dynamic functions.
+
+To learn more about the logic behind these fields, see the [Smart Value System]({{< relref "smart-value-system.md" >}}).
+
+### Quick Access
+In any Smart Value field, you can use these shortcuts:
+
+1.  **Static Input**: Just type a value directly into the field.
+2.  **Variable Picker (@)**: Type `@` or click the variable icon to see a list of available data, such as `@doc.customer_name` or `@rule.total_count`.
+3.  **Advanced Resolvers (/)**: Type `/` or click the magic wand icon to access tools like math, text formatting, and date calculations.
+
+## Field Types
+
+In the settings panel, you will encounter different types of input controls:
+
+-   **Dropdowns**: Choose from a fixed list of options.
+-   **Checkboxes**: Toggle settings on or off.
+-   **Data Grids**: Used for actions like "Set Value," where you need to map multiple fields at once. Each row in the grid uses a Smart Value field for the value column.
+-   **Multi-Select**: Pick one or more tags or items from a list.
+
+## Context Awareness
+
+The settings panel is "Smart." It knows where the block is located in your flow.
+-   **Available Variables**: In the `@` menu, you will only see variables that have actually been defined *before* the current block.
+-   **Validation**: Required fields are marked, and the panel will alert you if your configuration is incomplete or contains errors.
+
+## Saving Changes
+
+Changes in the Action Settings panel are usually drafted immediately. However, you must **Save** the entire rule using the button at the top of the canvas to commit your changes to the system.
+
+{{< tip >}}
+**Keep it Readable**: Use the title field at the top of the settings panel to give each block a business-friendly name. Instead of "Set Value 1," use "Calculate Discounted Total."
+{{< /tip >}}

content/en/rule-builder/add-action.md

@@ -0,0 +1,50 @@
+---
+title: Adding Actions
+description: Learn how to add new logic blocks to your rule.
+weight: 20
+---
+
+# Adding Actions
+
+Building a rule involves adding "Actions" (Blocks) to the canvas and connecting them to form a logical flow. FlexiRule makes this process intuitive with the **Action Zone**.
+
+## The Action Zone
+
+The Action Zone is the primary way to insert new logic into your rule. It appears dynamically as you work on the canvas.
+
+{{< video src="/images/add-action-from-action-zone.webm" autoplay="true" loop="true" muted="true" >}}
+
+### How to Add an Action
+1.  **Trigger the Menu**: Hover your mouse over any connection line (the arrows between blocks) or click the `+` icon that appears in empty spaces on the canvas.
+2.  **Browse or Search**: An action menu will pop up. You can:
+    -   **Search**: Type keywords like "Email," "Update," or "Check" to find specific actions quickly.
+    -   **Categories**: Browse through categorized lists like *Data Operations*, *Communications*, or *Flow Control*.
+3.  **Select**: Click the action you want to add.
+4.  **Auto-Insertion**: The new block will be automatically placed on the canvas. If you clicked a connection line, the new block will be inserted *between* the two existing blocks, and the connections will be automatically updated.
+
+## Types of Actions
+
+When adding an action, you will see several types of blocks categorized by their purpose:
+
+-   **Set Value**: Used for calculations and updating variables within the rule.
+-   **Check (Condition)**: Creates a fork in the road based on logic (True/False).
+-   **Update Record**: Saves changes directly to a record in your system.
+-   **Notify**: Sends alerts via Email, SMS, or System Notifications.
+-   **Repeat (Loop)**: Runs a series of actions for every item in a list.
+-   **Process**: Triggers advanced system operations or external integrations.
+
+## Organizing Blocks
+
+Once an action is added, you can click and drag it to any position on the canvas.
+
+### Inserting Between Blocks
+The easiest way to add logic to an existing flow is to hover over the arrow connecting two blocks. When the `+` icon appears, clicking it and selecting an action will "splice" the new action into the flow, saving you from manually deleting and re-drawing connection lines.
+
+{{< video src="/images/remove-a-node-will-dynamically-reconnet-nodes.webm" >}}
+
+### Quick Configuration
+As soon as you add an action, it is selected by default, and its **Action Settings** panel opens on the right. This allows you to immediately configure the details of the new block without extra clicks.
+
+## Managing Actions
+-   **Renaming**: You can customize the name of any block by clicking its title in the settings panel. This helps make your flow more readable (e.g., instead of "Notify," name it "Send Approval Email").
+-   **Deleting**: To remove a block, select it and press `Delete` on your keyboard, or click the trash icon in its settings panel. The builder will attempt to reconnect the preceding and following blocks automatically.

content/en/rule-builder/canvas.md

@@ -0,0 +1,52 @@
+---
+title: Canvas Navigation
+description: Learn how to navigate and use the visual Rule Builder canvas.
+weight: 10
+---
+
+# Canvas Navigation
+
+The Rule Builder provides a visual workspace where you can design your business logic by dragging, dropping, and connecting different "Blocks." This visual approach allows you to see exactly how data flows through your system.
+
+![Rule Builder Overview](/images/flexirule-canvas-view.png)
+
+## The Visual Workspace
+
+The canvas is an infinite workspace that represents your rule's logic as a flowchart.
+
+### How Logic is Represented
+- **Blocks**: Each step in your rule is represented by a Block (node). Blocks have a clear icon, a title, and often a sub-label describing their specific configuration.
+- **Connections**: Arrows between blocks show the direction of execution. The flow typically moves from the **Start** block at the top towards various outcomes or a **Stop** block.
+- **Entry & Exit Points**: Most blocks have a circular handle at the top (input) and one or more handles at the bottom (output).
+
+## Core Interactions
+
+### Moving Around
+- **Pan**: Click and hold any empty area of the canvas, then drag to move your view.
+- **Zoom**: Use your mouse wheel or the zoom controls in the bottom-right corner to get a bird's-eye view or focus on a specific section.
+
+### Arranging Your Logic
+- **Moving Blocks**: Click and drag any block to reposition it. The connected arrows will automatically adjust to follow the block.
+- **Selecting**: Click a block to select it. This highlights the block and opens its **Action Settings** panel on the right side of the screen.
+- **Multi-Select**: Hold `Shift` and drag a box around multiple blocks to move them as a group.
+
+{{< video src="/images/shift-click-nodes-to-copy.webm" >}}
+
+### Connecting Blocks
+To create a connection, click and drag from the bottom handle of one block to the top handle of another.
+- **Valid Paths**: The builder will highlight valid connection points as you drag.
+- **Auto-Healing**: If you delete a block that sits between two others, the builder will often attempt to "heal" the connection by linking the preceding block directly to the following one.
+
+## Visual Indicators
+
+The canvas uses visual cues to help you understand your rule at a glance:
+- **Active State**: Selected blocks are highlighted with a distinct border.
+- **Validation**: If a block is missing required configuration, a warning icon or red outline may appear to alert you before you save.
+- **Logical Branching**: For decision blocks (like "Check"), paths are clearly labeled (e.g., "True" and "False") so you can follow the logic easily.
+
+## Tips for a Clean Canvas
+- **Alignment**: Keep your blocks organized vertically to make the logic easier for others to read.
+- **Labels**: Use descriptive labels for your blocks so the purpose of each step is clear without opening the settings.
+- **Sub-rules**: For very complex logic, consider using a **Sub-rule** block to keep your main canvas simple and readable.
+
+![Ruleflow with Sub-rule](/images/flexirule-canvas-with-sub-rule.png)

content/en/rule-builder/condition-builder.md

@@ -0,0 +1,61 @@
+---
+title: Condition Builder
+description: Learn how to create logical branches in your rules.
+weight: 50
+---
+
+# Condition Builder
+
+The **Condition Builder** is a visual interface used to define "Yes/No" logic. It is most commonly found inside the **Check** block, but it is also used for filters and trigger conditions.
+
+## How it Looks
+
+Instead of writing complex code, you build conditions using a structured, row-based interface. Each row represents a single logical check.
+
+![Condition Builder Example](/images/demo-condition-and-query.webm)
+
+## Building a Condition
+
+A single condition row consists of three main parts:
+
+1.  **Field/Value**: What you are checking (e.g., `Status` or `Grand Total`).
+2.  **Operator**: How you are checking it (e.g., `is`, `is not`, `is greater than`, `contains`).
+3.  **Comparison Value**: What you are checking against (e.g., `Open` or `1000`).
+
+### Powered by the Smart Value System
+For both the first and third parts of a condition, you use the [Smart Value System]({{< relref "smart-value-system.md" >}}). This allows you to:
+-   Pick fields directly from the document using `@doc`.
+-   Use variables calculated earlier in the rule using `@rule`.
+-   Enter static text or numbers.
+-   Use resolver functions with `/` for complex comparisons.
+
+## Grouping Logic (AND / OR)
+
+Rules often require checking more than one thing at a time. The Condition Builder uses **Groups** to handle this.
+
+-   **AND Groups**: All conditions in the group must be true for the whole group to be true. (e.g., "Status is Open" **AND** "Total > 1000").
+-   **OR Groups**: Only one condition in the group needs to be true for the whole group to be true. (e.g., "Customer is VIP" **OR** "Order is Urgent").
+
+### Nested Groups
+You can add groups inside of other groups to create complex logic. The UI represents this with indented boxes, making it easy to see which conditions belong together.
+
+## Visual Structure
+
+-   **Add Condition**: Click the `+ Condition` button to add a new row to the current group.
+-   **Add Group**: Click the `+ Group` button to create a new nested AND/OR block.
+-   **Toggle Logic**: Click the **AND/OR** label at the top of a group to switch the logic for all rows within that group.
+-   **Delete**: Use the trash icon next to any row or group to remove it.
+
+## Example: Complex Approval Logic
+Imagine you want a rule to run if:
+*(The Order is from a VIP Customer)* **AND** *(The Total is over $5,000 **OR** the Order is marked as "Urgent")*
+
+In the Condition Builder, this would look like:
+- **Group (AND)**
+  - Row: `Customer Type` is `VIP`
+  - **Group (OR)**
+    - Row: `Grand Total` > `5000`
+    - Row: `Priority` is `Urgent`
+
+## Validation
+As you build, FlexiRule checks your logic. If you leave a value empty or use an operator that doesn't make sense for the field type (like using "Greater Than" on a text field), the builder will highlight the error so you can fix it before saving.