User-First Documentation Overhaul

content/en/_index.md

@@ -4,21 +4,21 @@ title: "FlexiRule: The Visual Logic Platform"
 
 # Welcome to FlexiRule
 
-FlexiRule is a high-performance, visual automation engine for the Frappe Framework. It allows you to design, execute, and manage complex business logic without writing boilerplate code.
+FlexiRule is a visual automation platform that helps you build business logic without writing code. It transforms complex workflows into clear, manageable diagrams that anyone can understand.
 
 ![FlexiRule Logo](/landing-page/flexiRule.png)
 
-## Design Your Logic Visually
+## Build Your Logic Visually
 
-With our intuitive drag-and-drop interface, you can build sophisticated workflows that are easy to understand and maintain.
+With our simple drag-and-drop builder, you can create powerful automations that are easy to read and maintain.
 
 ![Rule Builder Canvas](/landing-page/rule_builder.png)
 
-## Key Features
+## Why you'll love it
 
-- **Visual Rule Builder**: Create logic flows using a node-based interface.
-- **No-Code Experience**: Empower business users to participate in logic design.
-- **Native Frappe Integration**: Deeply integrated with DocTypes, Hooks, and the Frappe security model.
-- **Enterprise-Grade**: Built for performance, auditability, and scale.
+- **Drag-and-Drop**: Build processes visually using simple blocks.
+- **No Coding Required**: Empower your entire team to design and manage logic.
+- **Built-In Security**: Your data stays safe within your existing system.
+- **Fast and Reliable**: Designed to handle even the most complex enterprise workflows.
 
 [Get Started with our Guide]({{< relref "getting-started" >}})

content/en/advanced-reference/architecture/actions/_index.md

@@ -11,7 +11,7 @@ Welcome to the Actions section. This section contains detailed information about
 ## Sub-pages
 
 - **[Condition](condition.md)**
-- **[Document Action](document-action.md)**
+- **[Update Record](update-record.md)**
 - **[Entry](entry.md)**
 - **[Loop](loop.md)**
 - **[Notify](notify.md)**

content/en/advanced-reference/architecture/actions/assignment.md

@@ -0,0 +1,14 @@
+---
+title: 'Assignment Action: Architecture'
+description: Technical implementation of the value mutation engine.
+weight: 50
+---
+
+# Assignment Action Architecture
+
+The **Assignment** action is implemented via the `AssignmentActionHandler`. It handles the sequential execution of mutations on the execution context.
+
+## Core Implementation
+- **Class**: `AssignmentActionHandler` in `flexirule/ruleflow/core/action_handlers/assignment.py`.
+- **Logic**: Iterates through the `assignments` list and applies `frappe.set_value` or variable updates using the `ValueResolver`.
+- **Normalization**: If a pipeline is defined, it passes the value through `NormalizationValueResolver` before assignment.

content/en/advanced-reference/architecture/actions/process.md

@@ -0,0 +1,13 @@
+---
+title: 'Process Action: Architecture'
+description: Technical implementation of external process execution.
+weight: 110
+---
+
+# Process Action Architecture
+
+The **Process** action integrates with the `ProcessRegistry` to execute arbitrary Python or JavaScript logic.
+
+## Core Implementation
+- **Class**: `ProcessActionHandler` in `flexirule/ruleflow/core/action_handlers/process.py`.
+- **Logic**: Looks up the process definition by name. It then prepares the input arguments and executes the process either synchronously or via `frappe.enqueue`.

content/en/advanced-reference/architecture/actions/sub-rule.md

@@ -0,0 +1,13 @@
+---
+title: 'Sub-rule Action: Architecture'
+description: Technical implementation of nested engine execution.
+weight: 90
+---
+
+# Sub-rule Action Architecture
+
+The **Sub-rule** action allows for recursive engine calls by spawning a child `RuleEngine` instance.
+
+## Core Implementation
+- **Class**: `SubRuleActionHandler` in `flexirule/ruleflow/core/action_handlers/sub_rule.py`.
+- **Context Handling**: Clones the current `ExecutionContext`, applies any input mappings for the child rule, and waits for the child execution to complete (unless configured as async).

content/en/advanced-reference/architecture/actions/switch.md

@@ -0,0 +1,13 @@
+---
+title: 'Switch Action: Architecture'
+description: Technical implementation of multi-path branching.
+weight: 70
+---
+
+# Switch Action Architecture
+
+The **Switch** action uses the `SwitchActionHandler` to evaluate a single expression and match it against a map of target next steps.
+
+## Core Implementation
+- **Class**: `SwitchActionHandler` in `flexirule/ruleflow/core/action_handlers/switch.py`.
+- **Logic**: Evaluates the `switch_on` expression. It then looks up the result in the `cases` dictionary. If no match is found, it falls back to the `default_next_step`.

content/en/advanced-reference/architecture/actions/wait.md

@@ -0,0 +1,13 @@
+---
+title: 'Wait Action: Architecture'
+description: Technical implementation of execution suspension.
+weight: 80
+---
+
+# Wait Action Architecture
+
+The **Wait** action leverages Frappe's background job system and the `Scheduler` to suspend and resume rule execution.
+
+## Core Implementation
+- **Class**: `WaitActionHandler` in `flexirule/ruleflow/core/action_handlers/simple_actions.py`.
+- **Mechanism**: Calculates the resume timestamp. It then creates a `RuleSuspension` record and schedules a background job to re-trigger the engine at the appropriate time.

content/en/advanced-reference/reference/execution/_index.md

@@ -11,7 +11,7 @@ Welcome to the Execution section. This section contains detailed information abo
 ## Sub-pages
 
 - **[Condition](condition.md)**
-- **[Document Action](document-action.md)**
+- **[Update Record](update-record.md)**
 - **[Entry](entry.md)**
 - **[Loop](loop.md)**
 - **[Notify](notify.md)**

content/en/core-actions/assignment.md

@@ -6,23 +6,23 @@ aliases:
   - /docs/actions/assignment/
 ---
 
-# Assignment Action
+# Assignment
 
-The **Assignment** action is used to change values in your rule. This can include updating fields on the document currently being processed or setting temporary variables for use in later steps.
+Use the **Assignment** block to set or change values while your rule is running. It's like taking a note or updating a field on your record.
 
-## Types of Assignments
+## Common Uses
 
-### 1. Document Field Assignment
-Directly change a field on the current document (the one that triggered the rule).
-- **Example**: Set `status` to "Pending Review".
+### 1. Update the Current Record
+Change a field on the record that started the rule.
+- **Example**: Automatically set the `Status` of a new ticket to "In Progress".
 
-### 2. Context Variable Assignment {#context-variables-vars}
-Create or update a "Variable" that exists only while the rule is running. This is useful for temporary calculations.
-- **Example**: Calculate a total `tax_amount = doc.amount * 0.15`.
+### 2. Save a Temporary Note (Variables) {#context-variables-vars}
+Create a "Variable" to store a piece of information for later. This information isn't saved to your database; it's only used while the rule is running.
+- **Example**: Calculate the tax for an order and save it as `Tax Amount` so you can use it in an email later.
 
-## Batch Assignments
-You can define multiple assignments within a single node. They are executed sequentially from top to bottom.
+## Do Multiple at Once
+You can list as many assignments as you want in a single block. FlexiRule will process them one by one from top to bottom.
 
-## Normalization and Cleaning
-Assignments support "Pipelines" to clean or transform data as it's being set.
-- **Example**: Trimming whitespace from a string or converting a name to uppercase.
+## Clean Your Data
+You can also use assignments to "clean" information before it's saved.
+- **Example**: Automatically capitalize a customer's name or remove extra spaces from an email address.

content/en/core-actions/condition.md

@@ -6,25 +6,25 @@ aliases:
   - /docs/actions/condition/
 ---
 
-# Condition Action
+# Condition
 
-The **Condition** action allows you to create branching logic in your rules. It evaluates a set of rules and directs the execution flow down either a **True** or **False** path.
+Use the **Condition** block to make decisions in your rule. It acts like a fork in the road: if your rule is met, it follows the **True** (Green) path; if not, it follows the **False** (Red) path.
 
-## How to Configure
+## How to Set It Up
 
-### 1. The Rule Builder
-Use the integrated condition builder to define your logic.
-- **Field**: Select a field from the document or a variable.
-- **Operator**: Choose how to compare (e.g., "is", "is not", "contains", "is greater than").
-- **Value**: The value to compare against.
+### 1. Build Your Check
+Use the simple builder to define your logic:
+- **Field**: Pick the item you want to check (e.g., "Total Amount").
+- **Check**: Choose how to compare it (e.g., "is more than", "starts with", "is exactly").
+- **Value**: Type in the value you are looking for (e.g., "5000").
 
-### 2. Grouping Logic (And/Or)
-- **AND**: All conditions in the group must be true.
-- **OR**: At least one condition in the group must be true.
+### 2. Combining Checks (And/Or)
+- **AND**: Use this when *every* check must be true.
+- **OR**: Use this when *at least one* check must be true.
 
 ## Simple Example
-**Scenario**: Only notify a manager if an order is over $5,000.
-1. Add a **Condition** node.
-2. Set rule: `grand_total` is greater than `5000`.
-3. Connect the **True** path to a **Notify** action.
-4. Leave the **False** path empty or connect it to a different step.
+**Goal**: Only send an alert if a Sales Order is over $5,000.
+1. Add a **Condition** block.
+2. Set it to check if `Total Amount` is more than `5000`.
+3. Connect the **True** path to a **Notify** block.
+4. Leave the **False** path alone, or connect it to something else if you want a different action for smaller orders.

content/en/core-actions/entry-action.md

@@ -8,12 +8,12 @@ aliases:
 
 # Entry Action
 
-Every business rule starts with an **Entry Action**. This node represents the document and data that triggered the rule.
+Every business rule starts with an **Entry Action**. This block represents the starting point and the record that triggered the rule.
 
-## What is the Entry Action?
-Think of the Entry Action as the "input" for your logic. It contains the `doc` (the record that triggered the rule) and makes it available to all following steps.
+## What is it?
+Think of the Entry Action as the "start" button. It holds all the information from the record that kicked off the rule (like a Sales Order or a Support Ticket) and makes that information available to every other block in your flow.
 
-## Rule Entry Conditions
-You can configure "Entry Conditions" directly on the Rule header. These act as a gatekeeper: if the condition isn't met, the rule won't even start.
+## Setting Early Limits
+You can set "Entry Conditions" on your rule. These act like a gatekeeper: if the record doesn't meet these requirements, the rule won't even start. This is great for keeping your system efficient.
 
-**Note**: For branching logic *after* the rule has already started, use the [Condition Action]({{< relref "condition" >}}).
+**Note**: If you want to make decisions *after* a rule has already started running, use a [Condition]({{< relref "condition" >}}) block instead.

content/en/core-actions/loop.md

@@ -6,22 +6,22 @@ aliases:
   - /docs/actions/loop/
 ---
 
-# Loop Action
+# Loop
 
-The **Loop** action allows you to repeat a series of steps for multiple items. This is essential when you have a list of records (like those from a **Query Records** action) and need to perform the same task for each one.
+Use the **Loop** block when you need to perform the same action on a group of items. It's like going through a checklist and doing a task for every item on that list.
 
 ## How it Works
 
-1. **Input List**: Select the list of items you want to process.
-2. **Loop Flow**: Any actions connected to the loop's output will be executed once for every item in the list.
-3. **Current Item**: Inside the loop, you can access the specific item currently being processed.
+1. **The List**: Choose the group of items you want to process (usually from a **Query Records** block).
+2. **The Action**: Connect any action you want to repeat to the Loop's output.
+3. **The Result**: FlexiRule will run those actions once for every single item in your list.
 
-## Example
-**Scenario**: Send a notification for every overdue invoice found.
-1. **Query Records**: Find all "Invoices" where `status` is "Overdue".
-2. **Loop**: Connect the results to a Loop node.
-3. **Notify**: Inside the loop, use the **Notify** action. It will run for each individual invoice.
+## Simple Example
+**Goal**: Send a reminder email for every overdue invoice.
+1. **Find Records**: Use a **Query Records** block to find all "Overdue Invoices".
+2. **Loop**: Connect that list to a **Loop** block.
+3. **Notify**: Connect a **Notify** block to the Loop. It will send a separate email for every invoice found.
 
-## Best Practices
-- **Efficiency**: Only loop over the items you need. Use filters in your query to keep the list small.
-- **Complexity**: If your loop logic gets too complex, consider using a **Sub-rule**.
+## Pro Tips
+- **Be Selective**: Only loop through the items you really need to process. Use filters in your search to keep the list as short as possible.
+- **Keep it Simple**: If your loop starts looking like a giant spiderweb, consider using a **Sub-rule** to keep things tidy.

content/en/core-actions/notify-action.md

@@ -6,27 +6,27 @@ aliases:
   - /docs/actions/notify/
 ---
 
-# Notify Action
+# Notify
 
-The **Notify** action is used to communicate information to users or external systems.
+Use the **Notify** block to send messages to your team or customers.
 
-## Notification Types
+## Ways to Notify
 
 ### 1. Email
-Send a formatted email to one or more recipients.
-- **Recipients**: Use static email addresses or dynamic ones (e.g., `doc.owner`).
-- **Templates**: Select from existing Frappe Email Templates or write custom content.
-- **Attachments**: Attach the current document as a PDF.
+Send a professional email.
+- **Who**: Send to fixed addresses or pick someone related to the record (like the "Owner").
+- **What**: Write your own message or use a pre-made template.
+- **Attach**: You can automatically include the current record as a PDF.
 
-### 2. System Notification
-Create a notification within the Frappe Desk for a specific user or role. These appear in the notification bell icon.
+### 2. Desktop Notification
+Alert a user or a specific role within the system. These show up in the notification bell.
 
-### 3. UI Toast
-Display a temporary popup message (Toast) to the user who triggered the rule.
-- **Types**: Success, Info, Warning, or Error.
-- **Note**: This only works for rules triggered by manual UI actions (e.g., clicking Save).
+### 3. Quick Alert (Toast)
+Show a temporary pop-up message to the person currently using the system.
+- **Options**: Success, Info, Warning, or Error.
+- **Best for**: Giving instant feedback after someone saves or clicks a button.
 
-## Configuration Steps
-1. **Select Type**: Choose how you want to notify.
-2. **Define Content**: Write your message. You can use `{{ doc.name }}` to include data from the document.
-3. **Set Recipients**: Choose who should receive the notification.
+## How to Set Up
+1. **Pick Method**: Choose how you want to send the message.
+2. **Write Message**: Type your content. You can include details from the record by using curly brackets, like `{name}`.
+3. **Choose Recipients**: Select who needs to see the message.

content/en/core-actions/process.md

@@ -6,16 +6,16 @@ aliases:
   - /docs/actions/process/
 ---
 
-# Process Action
+# Process
 
-The **Process** action is used for advanced logic that goes beyond standard record updates or notifications.
+The **Process** block is for advanced tasks that need a little extra power. Use it when you need to run custom logic or connect to other systems.
 
 ## When to Use
-- **Custom Scripts**: Run a predefined Python or JavaScript process.
-- **Heavy Calculations**: Offload complex math to a dedicated process to keep the UI responsive.
-- **External Integrations**: Call third-party APIs or services.
+- **Custom Logic**: Run a specific piece of custom code built by your team.
+- **Big Calculations**: Handle complex math without slowing down your system.
+- **Connect to Others**: Send or receive information from external tools and websites.
 
-## Configuration
-1. Select the **Process** you want to run.
-2. Provide any required **Input Parameters**.
-3. Use the **Return Value** in subsequent nodes of your rule.
+## How to Set It Up
+1. Choose the **Process** you want to run from the list.
+2. Fill in any **Information** the process needs to start.
+3. If the process sends back an answer, you can use that answer in the next steps of your rule.

content/en/core-actions/query-records.md

@@ -8,49 +8,36 @@ aliases:
 
 # Query Records
 
-The **Query Records** action allows your rule flows to fetch information from the database. It is the primary way to make decisions based on data that isn't already present in your current document.
+Use the **Query Records** block to find information from elsewhere in your system. It's the best way to get data you need to make decisions or update other records.
 
-## When to Use
-- **Data Enrichment**: Fetching related fields (e.g., getting a Customer's "Territory").
-- **Validation**: Checking for duplicates or conflicting records.
-- **Aggregations**: Calculating totals across multiple documents (e.g., "Sum of all unpaid invoices").
+## Common Uses
+- **Find Details**: Get a customer's address or a product's price.
+- **Check Records**: See if a similar record already exists before creating a new one.
+- **Calculate Totals**: Add up all unpaid invoices for a specific client.
 
-## Query Modes
+## Ways to Search
 
-| Mode | Returns | Best For |
+| Search Type | What it finds | Best For |
 | :--- | :--- | :--- |
-| **Query List** | List of Records | Finding multiple records to loop over. |
-| **Query Doc** | Single Record | Fetching detailed info from a specific record. |
-| **Exist Record** | Yes/No | Simple validation and existence checks. |
-| **Aggregations** | Number | Totals, counts, and averages (Sum, Min, Max). |
-| **Group By** | List of Totals | Summary data grouped by a category (e.g., Sales by Territory). |
+| **Find List** | A group of records | Getting many items to process one by one. |
+| **Find One** | A single record | Getting specific details from one item. |
+| **Check Existence** | A "Yes" or "No" | Simple checks (e.g., "Does this customer exist?"). |
+| **Totals & Math** | A single number | Counting items or adding up values (Sum, Average). |
 
-## Advanced Querying
+## How to Set Up
 
-### Aggregations
-Use this mode when you only need a single number.
-- **Count**: How many records match the filter.
-- **Sum**: The total of a specific numeric field.
-- **Average/Min/Max**: Standard statistical calculations.
+### 1. Choose What to Find
+Pick the type of record you are looking for (e.g., "Sales Invoice").
 
-### Group By
-Use this to summarize data into "buckets".
-- **Example**: Get the total sales amount for each individual salesperson in the last month.
+### 2. Set Your Filters
+Filters tell FlexiRule exactly which records to look for.
+- **Simple**: Find records where `Status` is "Draft".
+- **Smart**: Find records that match your current document (e.g., "Find invoices for *this* customer").
+- **Time-Based**: Find records from "Last 7 Days" using the built-in date builder.
 
-## How to Configure
+### 3. Test and Refresh
+Click **Refresh Schema**. This runs a quick test to make sure your search works and lets FlexiRule know which fields will be available for you to use in the next steps.
 
-### 1. Select the DocType
-Choose the type of record you want to find (e.g., "Sales Invoice").
-
-### 2. Define Filters
-Filters tell FlexiRule exactly which records to find.
-- **Static Filters**: `status = "Draft"`
-- **Dynamic Filters**: `customer = doc.customer` (matches the customer from the current document).
-- **Date Formulas**: Use the formula builder for rolling windows like "Last 7 Days".
-
-### 3. Refresh Schema (Important)
-After setting your query, click the **Refresh Schema** button. This performs a live test and makes the resulting fields available to use in later steps of your rule.
-
-## Common Tips
-- **Always Filter**: Avoid searching the entire database without filters to keep your rules fast.
-- **Check the Result**: Remember that **Query List** always returns a list of items, even if it only finds one. Use **Query Doc** if you only need one specific record.
+## Pro Tips
+- **Be Specific**: Use filters to narrow down your search. Searching everything can slow down your rule.
+- **Pick the Right Type**: If you only need one specific record, use **Find One**. If you need to process a whole list, use **Find List**.