From 3e1048f317735d9f83c046a4fc074c904bf107f0 Mon Sep 17 00:00:00 2001
From: abdoruzaqi <245876665+abdoruzaqi@users.noreply.github.com>
Date: Thu, 2 Jul 2026 04:39:28 +0000
Subject: [PATCH] docs: comprehensive user-first documentation overhaul
- Reorganized directory structure into User-First hierarchy (Getting Started, Using the Builder, Core Actions, Advanced Reference).
- Rewrote core guides using business-centric terminology (Blocks, Check, Set Value, Repeat).
- Consolidated functional action guides and isolated technical architectural details.
- Updated all internal relref links to maintain site integrity.
- Verified successful Hugo build with --gc --minify.
---
content/en/action-types/assignment.md | 71 --------
content/en/action-types/condition.md | 68 -------
content/en/action-types/entry-action.md | 19 --
content/en/action-types/loop.md | 27 ---
content/en/action-types/notify/_index.md | 74 --------
content/en/action-types/notify/email.md | 32 ----
.../en/action-types/query-records/_index.md | 70 -------
.../action-types/query-records/query-doc.md | 25 ---
.../action-types/query-records/query-list.md | 22 ---
.../en/action-types/update-record/_index.md | 80 --------
.../action-types/update-record/create-new.md | 27 ---
.../update-record/update-existing.md | 24 ---
.../architecture/actions/condition.md | 74 --------
.../architecture/actions/document-action.md | 64 -------
content/en/advanced-reference/_index.md | 15 ++
.../advanced-concepts/_index.md | 0
.../advanced-concepts/ai-features.md | 6 +-
.../advanced-concepts}/architecture.md | 0
.../advanced-concepts/architecture/_index.md | 0
.../architecture/actions/_index.md | 4 +-
.../architecture/actions/check.md | 17 ++
.../architecture/actions/document-action.md | 17 ++
.../architecture/actions/entry.md | 2 +-
.../architecture/actions/notify.md | 4 +-
.../architecture/actions/query-records.md | 4 +-
.../architecture/actions/repeat.md} | 0
.../architecture/actions/set-value.md | 22 +++
.../architecture/actions/stop.md | 4 +-
.../architecture/contracts/_index.md | 0
.../architecture/engine/_index.md | 0
.../engine/action-implementation.md | 8 +-
.../architecture/engine/condition-system.md | 2 +-
.../architecture/engine/execution-engine.md | 6 +-
.../architecture/engine/orchestration.md | 0
.../architecture/internals/_index.md | 0
.../architecture/overview.md | 6 +-
.../architecture/resolver/_index.md | 0
.../resolver/resolver-patterns.md | 0
.../architecture/runtime/_index.md | 0
.../architecture/runtime/execution-context.md | 0
.../runtime/graph-orchestration.md | 0
.../architecture/runtime/overview.md | 0
.../architecture/ui/_index.md | 0
.../architecture/ui/action-config-panels.md | 0
.../architecture/ui/component-registry.md | 0
.../architecture/ui/controls.md | 0
.../architecture/ui/dynamic-forms.md | 0
.../architecture/ui/overview.md | 0
.../data-manipulation/_index.md | 0
.../normalization-value-resolver.md | 6 +-
.../advanced-concepts/decision-trees.md | 6 +-
.../advanced-concepts/reference/_index.md | 0
.../advanced-concepts/reference/ai/_index.md | 0
.../reference/ai/action-metadata-schema.md | 4 +-
.../advanced-concepts/reference/doctypes.md | 8 +-
.../reference/execution/_index.md | 4 +-
.../reference/execution/condition.md | 6 +-
.../reference/execution/document-action.md | 0
.../reference/execution/entry.md | 0
.../reference/execution/loop.md | 2 +-
.../reference/execution/notify.md | 4 +-
.../reference/execution/query-records.md | 4 +-
.../reference/execution/stop.md | 6 +-
.../advanced-concepts/reference/glossary.md | 8 +-
.../reference/localized/_index.md | 0
.../reference/localized/arabic-overview.md | 0
.../reference/query-filters/index.md | 2 +-
.../reference/terminology.md | 0
.../reference/timespan-keywords/index.md | 0
.../advanced-concepts/registry-contracts.md | 0
.../advanced-concepts/roadmap/_index.md | 2 +-
.../roadmap/documentation-standardization.md | 4 +-
.../roadmap/event-driven-architecture.md | 0
.../roadmap/platform-potential.md | 0
.../roadmap/runtime-optimization.md | 0
.../roadmap/set-value-action-improvements.md} | 6 +-
...ule-entry-condition-vs-condition-action.md | 6 +-
.../advanced-concepts/system-philosophy.md | 0
.../advanced-concepts/triggers/_index.md | 2 +-
.../triggers/callable-triggers.md | 0
.../triggers/context-reference.md | 0
.../triggers/engine-details.md | 0
.../triggers/event-triggers.md | 0
.../triggers/scheduler-triggers.md | 0
.../api-reference/_index.md | 0
.../api-reference/contracts.md | 0
.../api-reference/hooks.md | 0
.../api-reference/public-apis.md | 0
.../developer-guide/_index.md | 0
.../performance.md | 0
.../performance/_index.md | 0
.../performance/architecture.md | 0
.../performance/optimization.md | 2 +-
.../philosophy}/better-than-hard-coded.md | 0
.../philosophy}/do-i-need-flexirule.md | 0
.../philosophy}/erpnext-need.md | 0
.../philosophy}/why-flexirule.md | 0
.../{ => advanced-reference}/setup/_index.md | 0
.../setup/initial-configuration.md | 0
.../setup/installation.md | 0
.../setup/permissions.md | 0
.../setup/settings.md | 0
.../setup/troubleshooting.md | 0
.../troubleshooting/_index.md | 0
.../troubleshooting/faq.md | 0
.../troubleshooting/troubleshooting.md | 0
.../{action-types => core-actions}/_index.md | 0
content/en/core-actions/check.md | 43 +++++
content/en/core-actions/notify-action.md | 38 ++++
.../{action-types => core-actions}/process.md | 0
content/en/core-actions/query-records.md | 37 ++++
content/en/core-actions/repeat.md | 35 ++++
content/en/core-actions/set-value.md | 45 +++++
content/en/core-actions/start.md | 21 +++
.../stop-error.md | 0
.../sub-rule.md | 0
.../{action-types => core-actions}/switch.md | 0
content/en/core-actions/update-record.md | 28 +++
.../en/{action-types => core-actions}/wait.md | 0
content/en/getting-started/_index.md | 13 +-
.../introduction.md} | 17 +-
content/en/getting-started/quick-start.md | 38 ++--
content/en/introduction/_index.md | 21 ---
content/en/introduction/core-concepts.md | 172 ------------------
content/en/introduction/key-capabilities.md | 39 ----
.../rule-builder/adding-managing-actions.md | 38 ----
.../_index.md | 0
.../adding-managing-actions.md | 43 +++++
.../canvas-navigation.md | 21 ++-
.../lifecycle-execution.md | 0
.../tutorials/_index.md | 0
.../tutorials/automatic-assignment.md | 0
.../tutorials/manager-approval.md | 0
.../tutorials/send-email-sales-order.md | 0
134 files changed, 476 insertions(+), 1049 deletions(-)
delete mode 100644 content/en/action-types/assignment.md
delete mode 100644 content/en/action-types/condition.md
delete mode 100644 content/en/action-types/entry-action.md
delete mode 100644 content/en/action-types/loop.md
delete mode 100644 content/en/action-types/notify/_index.md
delete mode 100644 content/en/action-types/notify/email.md
delete mode 100644 content/en/action-types/query-records/_index.md
delete mode 100644 content/en/action-types/query-records/query-doc.md
delete mode 100644 content/en/action-types/query-records/query-list.md
delete mode 100644 content/en/action-types/update-record/_index.md
delete mode 100644 content/en/action-types/update-record/create-new.md
delete mode 100644 content/en/action-types/update-record/update-existing.md
delete mode 100644 content/en/advanced-concepts/architecture/actions/condition.md
delete mode 100644 content/en/advanced-concepts/architecture/actions/document-action.md
create mode 100644 content/en/advanced-reference/_index.md
rename content/en/{ => advanced-reference}/advanced-concepts/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/ai-features.md (91%)
rename content/en/{introduction => advanced-reference/advanced-concepts}/architecture.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/actions/_index.md (85%)
create mode 100644 content/en/advanced-reference/advanced-concepts/architecture/actions/check.md
create mode 100644 content/en/advanced-reference/advanced-concepts/architecture/actions/document-action.md
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/actions/entry.md (96%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/actions/notify.md (96%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/actions/query-records.md (96%)
rename content/en/{advanced-concepts/architecture/actions/loop.md => advanced-reference/advanced-concepts/architecture/actions/repeat.md} (100%)
create mode 100644 content/en/advanced-reference/advanced-concepts/architecture/actions/set-value.md
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/actions/stop.md (88%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/contracts/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/engine/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/engine/action-implementation.md (92%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/engine/condition-system.md (99%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/engine/execution-engine.md (92%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/engine/orchestration.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/internals/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/overview.md (89%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/resolver/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/resolver/resolver-patterns.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/runtime/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/runtime/execution-context.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/runtime/graph-orchestration.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/runtime/overview.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/ui/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/ui/action-config-panels.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/ui/component-registry.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/ui/controls.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/ui/dynamic-forms.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/architecture/ui/overview.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/data-manipulation/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/data-manipulation/normalization-value-resolver.md (96%)
rename content/en/{ => advanced-reference}/advanced-concepts/decision-trees.md (92%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/ai/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/ai/action-metadata-schema.md (98%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/doctypes.md (85%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/execution/_index.md (85%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/execution/condition.md (94%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/execution/document-action.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/execution/entry.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/execution/loop.md (96%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/execution/notify.md (95%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/execution/query-records.md (93%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/execution/stop.md (88%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/glossary.md (84%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/localized/_index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/localized/arabic-overview.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/query-filters/index.md (94%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/terminology.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/reference/timespan-keywords/index.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/registry-contracts.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/roadmap/_index.md (81%)
rename content/en/{ => advanced-reference}/advanced-concepts/roadmap/documentation-standardization.md (92%)
rename content/en/{ => advanced-reference}/advanced-concepts/roadmap/event-driven-architecture.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/roadmap/platform-potential.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/roadmap/runtime-optimization.md (100%)
rename content/en/{advanced-concepts/roadmap/assignment-action-improvements.md => advanced-reference/advanced-concepts/roadmap/set-value-action-improvements.md} (95%)
rename content/en/{ => advanced-reference}/advanced-concepts/rule-entry-condition-vs-condition-action.md (96%)
rename content/en/{ => advanced-reference}/advanced-concepts/system-philosophy.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/triggers/_index.md (92%)
rename content/en/{ => advanced-reference}/advanced-concepts/triggers/callable-triggers.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/triggers/context-reference.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/triggers/engine-details.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/triggers/event-triggers.md (100%)
rename content/en/{ => advanced-reference}/advanced-concepts/triggers/scheduler-triggers.md (100%)
rename content/en/{ => advanced-reference}/api-reference/_index.md (100%)
rename content/en/{ => advanced-reference}/api-reference/contracts.md (100%)
rename content/en/{ => advanced-reference}/api-reference/hooks.md (100%)
rename content/en/{ => advanced-reference}/api-reference/public-apis.md (100%)
rename content/en/{ => advanced-reference}/developer-guide/_index.md (100%)
rename content/en/{introduction => advanced-reference}/performance.md (100%)
rename content/en/{ => advanced-reference}/performance/_index.md (100%)
rename content/en/{ => advanced-reference}/performance/architecture.md (100%)
rename content/en/{ => advanced-reference}/performance/optimization.md (93%)
rename content/en/{introduction => advanced-reference/philosophy}/better-than-hard-coded.md (100%)
rename content/en/{introduction => advanced-reference/philosophy}/do-i-need-flexirule.md (100%)
rename content/en/{introduction => advanced-reference/philosophy}/erpnext-need.md (100%)
rename content/en/{introduction => advanced-reference/philosophy}/why-flexirule.md (100%)
rename content/en/{ => advanced-reference}/setup/_index.md (100%)
rename content/en/{ => advanced-reference}/setup/initial-configuration.md (100%)
rename content/en/{ => advanced-reference}/setup/installation.md (100%)
rename content/en/{ => advanced-reference}/setup/permissions.md (100%)
rename content/en/{ => advanced-reference}/setup/settings.md (100%)
rename content/en/{ => advanced-reference}/setup/troubleshooting.md (100%)
rename content/en/{ => advanced-reference}/troubleshooting/_index.md (100%)
rename content/en/{ => advanced-reference}/troubleshooting/faq.md (100%)
rename content/en/{ => advanced-reference}/troubleshooting/troubleshooting.md (100%)
rename content/en/{action-types => core-actions}/_index.md (100%)
create mode 100644 content/en/core-actions/check.md
create mode 100644 content/en/core-actions/notify-action.md
rename content/en/{action-types => core-actions}/process.md (100%)
create mode 100644 content/en/core-actions/query-records.md
create mode 100644 content/en/core-actions/repeat.md
create mode 100644 content/en/core-actions/set-value.md
create mode 100644 content/en/core-actions/start.md
rename content/en/{action-types => core-actions}/stop-error.md (100%)
rename content/en/{action-types => core-actions}/sub-rule.md (100%)
rename content/en/{action-types => core-actions}/switch.md (100%)
create mode 100644 content/en/core-actions/update-record.md
rename content/en/{action-types => core-actions}/wait.md (100%)
rename content/en/{introduction/what-is-flexirule.md => getting-started/introduction.md} (55%)
delete mode 100644 content/en/introduction/_index.md
delete mode 100644 content/en/introduction/core-concepts.md
delete mode 100644 content/en/introduction/key-capabilities.md
delete mode 100644 content/en/rule-builder/adding-managing-actions.md
rename content/en/{rule-builder => using-the-builder}/_index.md (100%)
create mode 100644 content/en/using-the-builder/adding-managing-actions.md
rename content/en/{rule-builder => using-the-builder}/canvas-navigation.md (53%)
rename content/en/{rule-builder => using-the-builder}/lifecycle-execution.md (100%)
rename content/en/{ => using-the-builder}/tutorials/_index.md (100%)
rename content/en/{ => using-the-builder}/tutorials/automatic-assignment.md (100%)
rename content/en/{ => using-the-builder}/tutorials/manager-approval.md (100%)
rename content/en/{ => using-the-builder}/tutorials/send-email-sales-order.md (100%)
diff --git a/content/en/action-types/assignment.md b/content/en/action-types/assignment.md
deleted file mode 100644
index 8ee46a9..0000000
--- a/content/en/action-types/assignment.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: Assignment
-description: Perform sequential batch state mutations on document fields and context variables.
-weight: 50
-entity_kind: action_operation
-category: data-operations
-mutation: true
-targets: ["Frappe DocType", "Context Variable"]
----
-
-# Assignment Action
-
-The **Assignment** action (formerly *Set Value*) is the primary mechanism for state mutation in FlexiRule. It allows you to define a sequence of mutations—**Batch Assignments**—that are executed in order to update document fields or manage internal rule state.
-
-## Purpose
-
-Use the Assignment action when you need to:
-- Update fields on the triggering document (e.g., change `status` to "Approved").
-- Initialize or update context variables (`vars`) to store intermediate calculation results.
-- Perform mathematical operations (Increment, Decrement) on numeric fields.
-- Manage collections (Append to lists, Merge dictionaries).
-
-## Action Capabilities
-
-| Capability | Support | Notes |
-| :--- | :--- | :--- |
-| **Batch Execution** | ✅ Yes | Execute multiple assignments in a single node. |
-| **Conditional Rows** | ✅ Yes | Each assignment row can have its own `when` condition. |
-| **Multi-Operator** | ✅ Yes | Supports Set, Clear, Increment, Decrement, Append, Merge, and Toggle. |
-| **Data Normalization**| ✅ Yes | Integrated pipelines for cleaning and transforming data. |
-| **Value Resolution** | ✅ Yes | Unified resolver for static values, formulas, and complex lookups. |
-
-## Configuration
-
-The Assignment action uses a grid-based interface where each row represents one mutation.
-
-### 1. Target Path
-Defines where the value will be stored.
-- `doc.field_name`: Updates a field on the current document.
-- `vars.variable_name`: Sets a temporary variable available for the rest of the rule execution.
-
-### 2. Operator
-Defines *how* the value is applied:
-- **Set**: Replaces the current value with the new value.
-- **Clear**: Removes the value (sets to `None` or empty).
-- **Increment / Decrement**: Adds or subtracts from the current numeric value.
-- **Append**: Adds a value to the end of a list/array.
-- **Merge**: Merges a dictionary into the target dictionary.
-- **Toggle**: Swaps a boolean value between `true` and `false`.
-
-### 3. Value
-The new value or operand. This can be:
-- **Static Value**: A hardcoded string, number, or date.
-- **Variable Path**: A reference to another field (e.g., `doc.base_amount`).
-- **Formula**: A Python-based expression for calculations.
-- **Data Pipeline**: A sequence of normalization steps (e.g., Trim → Uppercase).
-
-### 4. Condition (When)
-An optional expression that must evaluate to `true` for this specific assignment to run. This allows for complex "If-Else" logic within a single Assignment block.
-
-## Best Practices
-
-- **Use Variables for Clarity**: Instead of repeating a complex formula in multiple nodes, calculate it once and store it in a `vars.total_price` variable.
-- **Sequential Logic**: Remember that assignments run from top to bottom. If row 2 depends on the result of row 1, it will work correctly.
-- **Event Awareness**: FlexiRule prevents you from mutating `doc.*` fields during "After Save" or "On Submit" events to prevent database inconsistencies. Use "Before Save" for field updates.
-
-## Common Mistakes
-
-- **Incorrect Path**: Forgetting the `doc.` or `vars.` prefix. `status` will fail; `doc.status` will succeed.
-- **Type Mismatch**: Trying to `Increment` a text field or `Append` to a number.
-- **Infinite Loops**: Setting a field that triggers the same rule again (though FlexiRule has built-in cycle detection to catch this).
diff --git a/content/en/action-types/condition.md b/content/en/action-types/condition.md
deleted file mode 100644
index 23aa98b..0000000
--- a/content/en/action-types/condition.md
+++ /dev/null
@@ -1,68 +0,0 @@
----
-title: Condition
-description: Evaluate complex logic gates to determine the execution path.
-weight: 40
-entity_kind: action_operation
-category: logic-control
-mutation: false
-targets: ["Frappe DocType", "Context Variable"]
----
-
-# Condition Action (Check)
-
-The **Condition** action (referred to as **Check** in user-first documentation) is the primary decision-making node in FlexiRule. it evaluates one or more logical expressions and directs the flow to either the **True** (Success) or **False** (Failure) branch.
-
-## Purpose
-
-Use the Condition action to:
-- Validate data before proceeding (e.g., "Is the Sales Order date in the future?").
-- Branch logic based on field values (e.g., "If Category is 'Electronics', go to Step A, else go to Step B").
-- Evaluate complex business rules involving multiple fields and child tables.
-
-## Action Capabilities
-
-| Capability | Support | Notes |
-| :--- | :--- | :--- |
-| **Nested Groups** | ✅ Yes | Support for recursive AND/OR logic groups. |
-| **Collection Logic**| ✅ Yes | Check if **Any**, **All**, or **None** of the rows in a child table meet a criteria. |
-| **Fast Execution** | ✅ Yes | Conditions are pre-compiled into optimized Python strings. |
-| **Cross-Context** | ✅ Yes | Compare `doc` fields against `vars`, `session` user, or global constants. |
-
-## Configuration
-
-### 1. Condition Groups
-Conditions are organized into groups. Each group has a logical operator:
-- **ALL (AND)**: Every condition in the group must be true.
-- **ANY (OR)**: At least one condition in the group must be true.
-- **NONE (NOT)**: No conditions in the group can be true.
-
-### 2. Simple Conditions
-A simple condition consists of:
-- **Field/Subject**: The value being checked (e.g., `doc.status`).
-- **Operator**: The comparison logic (e.g., `Equals`, `Contains`, `Is Set`, `Matches Regex`).
-- **Value/Object**: The criteria to check against.
-
-### 3. Collection Evaluations (New in V2)
-You can now evaluate child tables (collections) directly:
-- **Target**: A child table field (e.g., `doc.items`).
-- **Evaluation**: "At least one row matches", "Every row matches", "No rows match".
-- **Criteria**: A nested set of conditions applied to each row in the collection.
-
-## Execution Semantics
-
-1. **Evaluation**: The engine evaluates the compiled expression against the current context.
-2. **Branching**:
- - If `True`: The engine follows the connection labeled **True** (next_step_if_true).
- - If `False`: The engine follows the connection labeled **False** (next_step_if_false).
-3. **Default Behavior**: If a branch is not connected, the rule execution finishes successfully at that node.
-
-## Best Practices
-
-- **Flatten Logic**: While FlexiRule supports deeply nested groups, keeping conditions shallow makes them easier for others to read.
-- **Check for "Set"**: Before comparing a field value, use the "Is Set" operator if the field might be empty, to avoid unexpected results.
-- **Visual Feedback**: During a Test Run, FlexiRule highlights the path taken, allowing you to see exactly why a condition evaluated the way it did.
-
-## Common Mistakes
-
-- **Comparing Strings and Numbers**: Ensure the types match. Comparing a string "100" to a number 100 might fail depending on the operator.
-- **Empty Groups**: An empty "ALL" group typically evaluates to `True`, while an empty "ANY" group evaluates to `False`.
diff --git a/content/en/action-types/entry-action.md b/content/en/action-types/entry-action.md
deleted file mode 100644
index 6a78668..0000000
--- a/content/en/action-types/entry-action.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: Entry Action
-description: The starting point of every business rule.
-weight: 5
-aliases:
- - /docs/actions/entry/
----
-
-# Entry Action
-
-Every business rule starts with an **Entry Action**. This node represents the document and data 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.
-
-## 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.
-
-**Note**: For branching logic *after* the rule has already started, use the [Condition Action]({{< relref "condition" >}}).
diff --git a/content/en/action-types/loop.md b/content/en/action-types/loop.md
deleted file mode 100644
index e71cbff..0000000
--- a/content/en/action-types/loop.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-title: Loop
-description: Repeat a sequence of actions for each item in a list.
-weight: 60
-aliases:
- - /docs/actions/loop/
----
-
-# Loop Action
-
-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.
-
-## 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.
-
-## 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.
-
-## 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**.
diff --git a/content/en/action-types/notify/_index.md b/content/en/action-types/notify/_index.md
deleted file mode 100644
index 2277f81..0000000
--- a/content/en/action-types/notify/_index.md
+++ /dev/null
@@ -1,74 +0,0 @@
----
-title: Notify
-description: Communication engine for emails, system alerts, and real-time UI messaging.
-weight: 20
-entity_kind: action_operation
-category: communication
-mutation: false
-targets: ["User", "Email", "System Notification"]
----
-
-# Notify Action
-
-The **Notify** action is FlexiRule's multi-channel communication node. It allows you to send information to users via various protocols, from simple browser alerts to formatted HTML emails and external service providers.
-
-## Purpose
-
-Use the Notify action to:
-- Alert users of important events (e.g., "High-value order submitted").
-- Send automated confirmations to customers.
-- Create internal "ToDo" style notifications in the Frappe Desk.
-- Provide real-time feedback to the user currently interacting with the system.
-
-## Action Capabilities
-
-| Capability | Support | Notes |
-| :--- | :--- | :--- |
-| **Multi-Channel** | ✅ Yes | Email, System Notification, Toast, Real-time, and custom Providers. |
-| **Jinja Templates** | ✅ Yes | Full support for Jinja2 in messages, subjects, and recipient fields. |
-| **Dynamic Attachments**| ✅ Yes | Automatically attach a PDF version of the triggering document. |
-| **Custom Providers** | ✅ Yes | Extendable via hooks for SMS, Slack, WhatsApp, etc. |
-
-## Notification Modes
-
-### 1. Email
-Sends a standard email via Frappe's email queue.
-- **Recipients**: Can be a list of emails or dynamic paths (e.g., `doc.contact_email`).
-- **Subject/Message**: Supports Jinja templates with access to `doc` and `vars`.
-- **Attach PDF**: Generates and attaches the PDF version of the triggering document.
-
-### 2. System Notification
-Creates a record in the **Notification Log** Doctype.
-- These appear in the notification bell icon in the Frappe Desk.
-- Best for internal alerts that require a permanent record.
-
-### 3. UI Toast
-Displays a temporary "alert" popup in the user's browser.
-- **Note**: This only works for synchronous rules triggered by user actions. It has no effect for background jobs or scheduled rules.
-
-### 4. Real-time (System)
-Publishes a message to the user's current session via Socket.io.
-- Useful for non-intrusive background updates while the user is working.
-
-### 5. Provider
-Dispatches the notification to a custom-defined provider (e.g., a Slack integration).
-- Providers are registered via the `flexirule_notification_providers` hook in custom apps.
-
-## Configuration
-
-The Notify action configuration changes based on the selected **Mode**.
-
-- **Subject**: (Email/System) The title of the notification.
-- **Message**: The body of the notification. Supports HTML and Jinja.
-- **Recipients/For User**: Who receives the message. Supports logic expressions.
-
-## Best Practices
-
-- **Avoid Spam**: Use **Condition** nodes before Notify actions to ensure notifications only go out when truly necessary.
-- **Traceability**: FlexiRule automatically appends a link to the "Source Rule" at the bottom of notifications to help administrators find the logic responsible for the message.
-- **Use Variables**: If you need to include calculated data, use an **Assignment** node to store it in a variable first, then reference it in your message via `{{ vars.my_variable }}`.
-
-## Common Mistakes
-
-- **Invalid Recipients**: Ensure the recipient field evaluates to a valid email address or user ID.
-- **Jinja Syntax Errors**: A typo in `{{ doc.field_name }}` will cause the notification to fail. Use the **Test Run** feature to verify your templates.
diff --git a/content/en/action-types/notify/email.md b/content/en/action-types/notify/email.md
deleted file mode 100644
index 3f62841..0000000
--- a/content/en/action-types/notify/email.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-title: Email
-description: Sending automated emails with attachments and dynamic templates.
-weight: 10
----
-
-# Email Notification
-
-The **Email** mode of the Notify action is the most common way to send information to customers and external stakeholders.
-
-## Configuration
-
-### 1. Recipients
-You can specify recipients in three ways:
-- **Static**: Enter a single email or a comma-separated list.
-- **Dynamic Variable**: Use `{{ doc.contact_email }}` or `{{ vars.manager_email }}`.
-- **User Link**: Select a User Link field from your DocType.
-
-### 2. Subject and Message
-Both fields support **Jinja2** templates.
-- **Example Subject**: `Order Confirmation: {{ doc.name }}`
-- **Example Message**:
- ```html
- Dear {{ doc.customer }},
- Your order placed on {{ doc.posting_date }} has been received.
- ```
-
-### 3. Attachments
-- **Attach PDF**: Generates a PDF of the triggering document using its default print format and attaches it to the email.
-
-## Execution Behavior
-Emails are added to the **Email Queue** in Frappe. They are not sent instantly by the web server but are picked up by the background worker (usually every minute).
diff --git a/content/en/action-types/query-records/_index.md b/content/en/action-types/query-records/_index.md
deleted file mode 100644
index 825b33e..0000000
--- a/content/en/action-types/query-records/_index.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-title: Query Records
-description: Retrieve data from the system using filters and aggregations.
-weight: 10
-entity_kind: action_operation
-category: data-operations
-mutation: false
-targets: ["Frappe DocType"]
----
-
-# Query Records Action
-
-The **Query Records** action is the data retrieval engine of FlexiRule. It allows you to fetch information from any DocType in the database, enabling logic that depends on records other than the one currently being processed.
-
-## Purpose
-
-Use the Query Records action when you need to:
-- **Validate**: Check if a duplicate record exists before allowing a save.
-- **Enrich**: Fetch a Customer's credit limit or a Supplier's lead time to use in calculations.
-- **Aggregate**: Calculate the total value of all unpaid invoices for a specific customer.
-- **Automate**: Find all overdue tasks and loop through them to send reminders.
-
-## Action Capabilities
-
-| Capability | Support | Notes |
-| :--- | :--- | :--- |
-| **Multi-Mode** | ✅ Yes | Query List, Query Doc, Count, Sum, Average, Min, Max, Exist. |
-| **Dynamic Filters** | ✅ Yes | Filter data using fields from the current context (`doc`, `vars`). |
-| **Date Formulas** | ✅ Yes | Built-in support for "Last 30 Days", "Current Month", etc. |
-| **Schema Refresh** | ✅ Yes | Automatically detects and maps resulting fields for use in later nodes. |
-| **Cached Lookups** | ✅ Yes | Support for `use_cached_doc` to improve performance. |
-
-## Query Modes
-
-### 1. Query Doc
-Retrieves a single record based on filters. Returns an **Object (Dictionary)**.
-- **Best For**: Getting the full details of a specific master record (e.g., Sales Person info).
-
-### 2. Query List
-Retrieves multiple records. Returns a **List of Objects**.
-- **Best For**: Finding all child records or multiple related documents to use in a **Loop**.
-
-### 3. Aggregations (Count, Sum, Avg, etc.)
-Performs a calculation on the database side and returns a **Number**.
-- **Example**: `Sum` of `base_grand_total` where `customer = doc.customer`.
-
-### 4. Exist Record
-A lightweight check that returns **True** if at least one matching record exists, otherwise **False**.
-
-## Configuration
-
-### Filters
-Filters are the heart of the query. You can combine multiple criteria using AND/OR logic:
-- **Field Comparison**: `status` Equals `Open`.
-- **Dynamic Context**: `customer` Equals `{{ doc.customer }}`.
-- **Date Range**: `posting_date` is `Within` `Last 30 Days`.
-
-### Field Selection
-To optimize performance, you can specify exactly which fields you want to retrieve instead of fetching the whole document.
-
-## Best Practices
-
-- **Limit Your Results**: If you only need one record, use `Query Doc` or set a `Limit` of 1 in `Query List`.
-- **Use "Exist" for Speed**: If you only need to know if a record is there (e.g., checking for duplicates), `Exist Record` is much faster than `Query List`.
-- **Refresh Schema**: Always click **Refresh Schema** after updating your query. This tells the Rule Builder which fields are available so you can select them from the autocomplete in later steps.
-
-## Common Mistakes
-
-- **Heavy Queries**: Querying a large DocType (like Stock Ledger) without enough filters can slow down your system.
-- **Mode Confusion**: Using `Query List` but expecting an Object. Remember that a list requires a **Loop** node to access individual field values.
diff --git a/content/en/action-types/query-records/query-doc.md b/content/en/action-types/query-records/query-doc.md
deleted file mode 100644
index 263e539..0000000
--- a/content/en/action-types/query-records/query-doc.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-title: Query Doc
-description: Retrieving a single record for data enrichment.
-weight: 10
----
-
-# Query Doc
-
-Use **Query Doc** when you need to fetch specific details from a single record in the system.
-
-## How it Works
-1. **Filters**: You provide filters to identify the unique record (e.g., `name` = `doc.customer`).
-2. **Result**: FlexiRule fetches the record and returns it as a single **Object**.
-3. **Availability**: All fields of that record are now available in the `vars` of your rule (if you assigned a return variable).
-
-## Example
-**Scenario**: You want to get the "Credit Limit" of a Customer while saving a Sales Order.
-- **DocType**: `Customer`
-- **Filters**: `name` Equals `{{ doc.customer }}`
-- **Return Variable**: `customer_info`
-
-In the next node, you can use `{{ vars.customer_info.credit_limit }}` in a calculation or condition.
-
-## Performance Note
-If you only need one or two fields, it is more efficient to specify those fields in the "Fields" configuration rather than fetching the whole document.
diff --git a/content/en/action-types/query-records/query-list.md b/content/en/action-types/query-records/query-list.md
deleted file mode 100644
index 42c2f70..0000000
--- a/content/en/action-types/query-records/query-list.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: Query List
-description: Finding multiple records for bulk processing or loops.
-weight: 20
----
-
-# Query List
-
-**Query List** is used when you expect to find multiple records.
-
-## How it Works
-1. **Filters**: Define criteria to find a set of records.
-2. **Result**: Returns a **List (Array)** of objects.
-3. **Looping**: Because the result is a list, you typically connect this node to a **Loop** node to perform actions on each individual record found.
-
-## Example
-**Scenario**: Find all "Overdue" Tasks for a Project.
-- **DocType**: `Task`
-- **Filters**: `project` = `doc.name` AND `status` = `Overdue`.
-- **Return Variable**: `overdue_tasks`.
-
-You can then loop over `vars.overdue_tasks` to send a reminder for each one.
diff --git a/content/en/action-types/update-record/_index.md b/content/en/action-types/update-record/_index.md
deleted file mode 100644
index af156a0..0000000
--- a/content/en/action-types/update-record/_index.md
+++ /dev/null
@@ -1,80 +0,0 @@
----
-title: Update Record
-description: Create, Update, or Delete documents in ERPNext and custom Frappe apps.
-weight: 30
-entity_kind: action_operation
-category: data-operations
-mutation: true
-targets: ["Frappe DocType"]
----
-
-# Update Record Action
-
-The **Update Record** action (internally known as **Document Action**) is used to perform CRUD operations on any DocType in the system. It is the bridge between rule logic and persistent data changes.
-
-## Purpose
-
-Use the Update Record action when you need to:
-- **Create New**: Generate a new document (e.g., Create a *Sales Order* from a *Quotation*).
-- **Update Existing**: Modify a specific record (e.g., Update a *Project* status when a *Task* is completed).
-- **Delete Record**: Remove a document from the system.
-- **Add Comment**: Post a message to the document timeline.
-- **Create ToDo**: Assign a task to a user based on rule logic.
-
-## Action Capabilities
-
-| Capability | Support | Notes |
-| :--- | :--- | :--- |
-| **Field Mapping** | ✅ Yes | Map values from the current rule context to the target document. |
-| **Table Mapping** | ✅ Yes | Bulk-populate child tables from source collections. |
-| **Same-Field Copy** | ✅ Yes | Automatically copy fields with matching names (Frappe Mapper style). |
-| **Async Support** | ✅ Yes | Offload document creation to background workers. |
-| **Permission Bypass**| ✅ Yes | Option to `ignore_permissions` with mandatory audit reason. |
-
-## Configuration Modes
-
-### 1. Create New
-Generates a fresh document.
-- **Reference DocType**: The type of document to create.
-- **Field Mappings**: Define which fields to populate.
-- **Static Values**: Fixed values that never change.
-- **Table Mappings**: Logic for copying child table rows (e.g., Quotation Items to Sales Order Items).
-
-### 2. Update Existing
-Modifies an existing record.
-- **Document Name**: Can be a fixed name or a dynamic expression (e.g., `doc.customer_project`).
-- **Mappings**: Only the mapped fields will be updated; others remain unchanged.
-
-### 3. Delete Record
-Removes a record based on name and DocType. Requires explicit permission or an audit-logged bypass.
-
-### 4. Specialized Modes
-- **Create ToDo**: Simplified UI for assigning Frappe ToDos.
-- **Add Comment**: Appends a comment to the timeline of the triggering document.
-
-## Field and Table Mapping
-
-Mappings are the heart of the Update Record action. They define the data flow:
-
-**Field Mapping Example:**
-- Target: `customer` ← Source: `doc.customer_name`
-- Target: `status` ← Source: `"Open"` (Static)
-
-**Table Mapping Example:**
-- Target Table: `items`
-- Source Collection: `doc.items`
-- Condition: `item.qty > 0`
-- Row Mapping:
- - `item_code` ← `item.item_code`
- - `qty` ← `item.qty`
-
-## Best Practices
-
-- **Use Async for Heavy Tasks**: If creating a document involves complex controller logic or many child rows, enable **Run Asynchronously** to keep the user interface responsive.
-- **Transactional Safety**: Document actions are part of the rule transaction. If the rule fails later, the document creation/update will be rolled back (unless executed asynchronously).
-- **Audit Reasons**: Always provide a clear reason when using "Skip Permissions" for compliance and debugging.
-
-## Common Mistakes
-
-- **Circular Updates**: Updating the *same* document that triggered the rule in an "On Save" event. This can cause recursion. Use **Assignment** for updates to the triggering document instead.
-- **Missing Required Fields**: Ensure all mandatory fields of the target DocType are either mapped or have default values.
diff --git a/content/en/action-types/update-record/create-new.md b/content/en/action-types/update-record/create-new.md
deleted file mode 100644
index 33f05b3..0000000
--- a/content/en/action-types/update-record/create-new.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-title: Create New
-description: Generating new documents automatically via rule logic.
-weight: 10
----
-
-# Create New Record
-
-This mode allows FlexiRule to generate brand-new records in any DocType.
-
-## Field Mappings
-You define how the new document's fields should be populated:
-- **Source**: Where the data comes from (`doc.field`, `vars.variable`, or a static `'String'`).
-- **Target**: The fieldname on the *new* document.
-
-## Table Mappings (Child Tables)
-You can also populate child tables (like Items in a Sales Order).
-- **Source Collection**: A list of items (e.g., `doc.items`).
-- **Row Mapping**: Define how each row in the source list maps to a row in the new document's child table.
-
-## Example
-**Scenario**: Automatically create a "Project" when a "Sales Order" is submitted.
-1. **Target DocType**: `Project`.
-2. **Field Mapping**:
- - `project_name` ← `doc.name`
- - `customer` ← `doc.customer`
-3. **Condition**: Only if `doc.order_type` is "Project-Based".
diff --git a/content/en/action-types/update-record/update-existing.md b/content/en/action-types/update-record/update-existing.md
deleted file mode 100644
index 571357c..0000000
--- a/content/en/action-types/update-record/update-existing.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-title: Update Existing
-description: Modifying specific records in the system.
-weight: 20
----
-
-# Update Existing Record
-
-Use this mode to change fields on a document that already exists in the database.
-
-## Identifying the Document
-You must tell FlexiRule *which* record to update:
-- **Document Name**: A fixed name (e.g., `PROJ-001`).
-- **Dynamic Expression**: A path to the name (e.g., `doc.linked_project`).
-
-## Partial Updates
-Unlike "Create New", you only need to map the fields you want to **change**. All other fields on the existing record will remain exactly as they are.
-
-## Example
-**Scenario**: When a "Task" is completed, update its parent "Project" status.
-1. **Target DocType**: `Project`.
-2. **Document Name**: `doc.project`.
-3. **Field Mapping**:
- - `status` ← `'In Progress'`
diff --git a/content/en/advanced-concepts/architecture/actions/condition.md b/content/en/advanced-concepts/architecture/actions/condition.md
deleted file mode 100644
index ec5337c..0000000
--- a/content/en/advanced-concepts/architecture/actions/condition.md
+++ /dev/null
@@ -1,74 +0,0 @@
----
-title: 'Condition: Architecture Reference'
-description: Internal implementation details and developer reference for the Condition
- action.
-weight: 20
----
-
-# Condition: Architecture Reference
-
-## Purpose
-The **Condition** action is implemented as a bridge between a visual logic tree (AST) and Python's native evaluation engine. It leverages `frappe.safe_eval` to provide high-performance logic execution while maintaining strict security boundaries.
-
-## Class Structure
-
-- **`ConditionHandler(ActionHandler)`**:
- - Located in `flexirule/ruleflow/core/action_handlers/condition.py`.
- - Responsible for validating the presence of the `compiled_expression`.
- - Dispatches evaluation to the engine.
-- **`RuleEngine`**:
- - Implements `_evaluate_python_condition(expression, context)`.
- - Manages the `safe_locals` environment.
-- **`SafeFrappeAPI`**:
- - Located in `flexirule/ruleflow/core/engine.py`.
- - A proxy class that restricts `frappe` methods to read-only operations.
-
-## Execution Pipeline
-
-1. **Engine Dispatch**: The `RuleEngine` identifies the action type and retrieves the `ConditionHandler` from the `HandlerRegistry`.
-2. **Handler Execution**: `ConditionHandler.execute()` is called.
-3. **Compilation Check**: The handler checks for `action.compiled_expression`. If missing, it raises a `ValueError`.
-4. **Runtime Eval**:
- - `engine._evaluate_python_condition()` is invoked.
- - It calls `eval_condition_bool()` from `flexirule.ruleflow.core.runtime_eval`.
- - The expression is evaluated using `frappe.safe_eval` within a restricted scope.
-5. **Coercion**: The result is passed through `bool()`, ensuring truthiness-based branching.
-6. **Navigation**: The handler returns `(result, next_id)`.
-
-## Context Mutation Model
-The Condition action follows a **Zero-Mutation** model.
-- **Input**: Reads from `ContextManager` scope.
-- **Internal**: May create temporary local variables if list comprehensions are used.
-- **Output**: Returns a boolean to the engine's graph traverser. No changes are persisted to the context or database.
-
-## Dependencies
-
-- **`flexirule.ruleflow.core.runtime_eval`**: Core logic for safe evaluation and error logging.
-- **`flexirule.ruleflow.core.condition_payload`**: Logic for extracting the JSON AST from the action configuration.
-- **`frappe.safe_eval`**: The underlying Python evaluation engine.
-- **`flexirule.ruleflow.utils.field_resolver`**: Used to resolve nested dot-notation paths (e.g., `doc.items.0.name`).
-
-## Extension Points
-
-### Custom Helper Functions
-Developers can add new helper functions to the condition evaluation scope by modifying the `_build_eval_locals` method in `RuleEngine`. These functions then become available to all rules globally.
-
-### Operator Customization
-New operators can be added to the frontend `SimpleCondition.vue` component. Since the frontend compiles these into standard Python expressions (e.g., `in`, `==`, `.startswith()`), no backend changes are typically required unless a new Python library is needed.
-
-## Internal Events
-- **`eval_condition_bool` (Log)**: Emitted via `frappe.logger` and `frappe.log_error` if an expression fails to evaluate.
-
-## Source Files
-
-- **Backend Handler**: `flexirule/ruleflow/core/action_handlers/condition.py`
-- **Compiler**: `flexirule/ruleflow/core/compiler.py` (Translates JSON AST to Python string)
-- **Frontend Builder**: `flexirule/public/js/flexirule/rule_builder/components/condition_builder/ConditionBuilder.vue`
-- **Runtime Evaluator**: `flexirule/ruleflow/core/runtime_eval.py`
-- **Payload Utilities**: `flexirule/ruleflow/core/condition_payload.py`
-- **Safe API Proxy**: `flexirule/ruleflow/core/engine.py` (see `SafeFrappeAPI`)
-- **Field Resolver**: `flexirule/ruleflow/utils/field_resolver.py` (Handles nested dot-notation)
-
-## Related Topics
-- [Action Documentation]({{< relref "action-types/condition.md" >}})
-- [Execution Semantics]({{< relref "advanced-concepts/reference/execution/condition.md" >}})
diff --git a/content/en/advanced-concepts/architecture/actions/document-action.md b/content/en/advanced-concepts/architecture/actions/document-action.md
deleted file mode 100644
index 2b68cd9..0000000
--- a/content/en/advanced-concepts/architecture/actions/document-action.md
+++ /dev/null
@@ -1,64 +0,0 @@
----
-title: 'Document Action: Architecture Reference'
-description: Class structure, Resource Mapper internals, and mode dispatch logic for
- the Document Action.
-weight: 30
----
-
-# Document Action: Architecture Reference
-
-## Purpose
-The **Document Action** implementation abstracts Frappe's CRUD operations into a declarative mapping-based engine. It centralizes document manipulation logic to ensure consistent application of permissions, background enqueuing, and context-aware value resolution.
-
-## Class Structure
-
-### `DocumentActionHandler(ActionHandler)`
-- **Responsibility**: The primary singleton handler registered in the `HandlerRegistry`.
-- **Key Methods**:
- - `execute()`: Orchestrates the overall lifecycle, applies input mappings, and dispatches to mode handlers.
- - `_create_new()`: Constructs document payloads and handles `is_async` enqueuing.
- - `_update_existing()`: Handles targeted record modification.
- - `_apply_table_mappings()`: Implements the recursive row-mapping engine.
- - `_get_same_field_mappings()`: Implements field-matching logic between source and target.
-
-## Execution Pipeline
-
-1. **Registry Lookup**: `RuleEngine` identifies the action type and fetches the `DocumentActionHandler` instance.
-2. **Mapping Layer**:
- - **Scalar Mappings**: Resolved via `_resolve_field_mappings` or `compiled_scalars` (pre-compiled Python dict).
- - **Static Values**: Merged last to ensure explicit configuration overrides dynamic discovery.
-3. **Table Engine**:
- - Iterates over `table_mappings`.
- - Resolves the source collection (usually a list of dicts from `doc` or `vars`).
- - For each row:
- - Creates a `row_context` with `item` (current row) and `loop` metadata.
- - Evaluates `condition` (inclusion check) and `filter` (exclusion check).
- - Applies field-level assignments to the row payload.
- - Appends the result to the parent document via `doc.append()`.
-4. **Dispatch**:
- - Sync: `frappe.get_doc(data).insert()` / `save()`.
- - Async: `frappe.enqueue("..._async_create_doc", doc_data=data)`.
-
-## Context Mutation Model
-- **Direct Memory Mutation**: For `Update Existing`, the handler performs `doc.set(field, value)` on a loaded object.
-- **Persistence Strategy**: Mutations are not committed to the database until the explicit `.insert()` or `.save()` call at the end of the mode handler.
-- **Context Injection**: The resulting document (post-save) is returned to the engine and injected into the `execution_context` (e.g., `vars.my_result`) using `apply_output_mapping`.
-
-## Dependencies
-- **Rule Engine Core**: Relies on `HandlerRegistry` for registration.
-- **Value Resolver**: Uses `_safe_eval` (inheriting from `ActionHandler`) for Python expression evaluation.
-- **Permissions**: Depends on `flexirule.ruleflow.core.permissions.can_skip_permissions` for role-based security bypassing.
-- **Utils**: Uses `flexirule.ruleflow.utils.mapping.apply_input_mapping` for pre-execution config hydration.
-
-## Extension Points
-- **Action Policies**: Developers can override operation-level policies (like `required_config_keys`) in `flexirule/ruleflow/core/contracts.py`.
-- **Custom Resolvers**: Custom Jinja filters or Python locals can be added to `_build_template_context` in the base `ActionHandler` to make them available to Document Action mappings.
-
-## Internal Events
-- **Background Task**: Triggers a `frappe.enqueue` event for asynchronous creation.
-- **Standard Hooks**: Indirectly triggers all Frappe document lifecycle hooks (`before_insert`, `after_save`, etc.) for the target DocType.
-
-## Source Files
-- **Backend**: `flexirule/ruleflow/core/action_handlers/create_doc.py`
-- **Frontend**: `flexirule/public/js/flexirule/rule_builder/components/rule_config/types/DocumentActionConfig.vue`
-- **Contract**: `flexirule/ruleflow/core/contracts.py`
diff --git a/content/en/advanced-reference/_index.md b/content/en/advanced-reference/_index.md
new file mode 100644
index 0000000..e50b049
--- /dev/null
+++ b/content/en/advanced-reference/_index.md
@@ -0,0 +1,15 @@
+---
+title: Advanced Reference
+weight: 40
+description: Detailed technical documentation and architectural reference for FlexiRule.
+---
+
+# Advanced Reference
+
+Welcome to the technical reference section. Here you will find detailed information about the system's architecture, APIs, and low-level configuration options.
+
+- **[Advanced Concepts]({{< relref "advanced-concepts/" >}})**: In-depth guides on engine internals, execution context, and complex logic patterns.
+- **[API Reference]({{< relref "api-reference/" >}})**: Documentation for public hooks, contracts, and system APIs.
+- **[Setup & Configuration]({{< relref "setup/" >}})**: Detailed installation and permission guides.
+- **[Performance & Optimization]({{< relref "performance/" >}})**: Understanding the engine's scale and efficiency.
+- **[Philosophy]({{< relref "philosophy/why-flexirule.md" >}})**: The underlying principles behind the FlexiRule orchestration layer.
diff --git a/content/en/advanced-concepts/_index.md b/content/en/advanced-reference/advanced-concepts/_index.md
similarity index 100%
rename from content/en/advanced-concepts/_index.md
rename to content/en/advanced-reference/advanced-concepts/_index.md
diff --git a/content/en/advanced-concepts/ai-features.md b/content/en/advanced-reference/advanced-concepts/ai-features.md
similarity index 91%
rename from content/en/advanced-concepts/ai-features.md
rename to content/en/advanced-reference/advanced-concepts/ai-features.md
index 0320b8d..96da5ca 100644
--- a/content/en/advanced-concepts/ai-features.md
+++ b/content/en/advanced-reference/advanced-concepts/ai-features.md
@@ -93,6 +93,6 @@ sequenceDiagram
## Related Topics
-- [Execution Engine]({{< relref "advanced-concepts/architecture/engine/execution-engine.md" >}})
-- [Variables]({{< relref "action-types/assignment#context-variables-vars" >}})
-- [Condition Builder]({{< relref "action-types/condition.md" >}})
+- [Execution Engine]({{< relref "advanced-reference/advanced-concepts/architecture/engine/execution-engine.md" >}})
+- [Variables]({{< relref "core-actions/set-value#context-variables-vars" >}})
+- [Condition Builder]({{< relref "core-actions/check.md" >}})
diff --git a/content/en/introduction/architecture.md b/content/en/advanced-reference/advanced-concepts/architecture.md
similarity index 100%
rename from content/en/introduction/architecture.md
rename to content/en/advanced-reference/advanced-concepts/architecture.md
diff --git a/content/en/advanced-concepts/architecture/_index.md b/content/en/advanced-reference/advanced-concepts/architecture/_index.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/_index.md
rename to content/en/advanced-reference/advanced-concepts/architecture/_index.md
diff --git a/content/en/advanced-concepts/architecture/actions/_index.md b/content/en/advanced-reference/advanced-concepts/architecture/actions/_index.md
similarity index 85%
rename from content/en/advanced-concepts/architecture/actions/_index.md
rename to content/en/advanced-reference/advanced-concepts/architecture/actions/_index.md
index 9322473..11e381e 100644
--- a/content/en/advanced-concepts/architecture/actions/_index.md
+++ b/content/en/advanced-reference/advanced-concepts/architecture/actions/_index.md
@@ -10,10 +10,10 @@ Welcome to the Actions section. This section contains detailed information about
## Sub-pages
-- **[Condition](condition.md)**
+- **[Condition](check.md)**
- **[Document Action](document-action.md)**
- **[Entry](entry.md)**
- **[Loop](loop.md)**
- **[Notify](notify.md)**
-- **[Query Records](query-records.md)**
+- **[Query Records](query-records)**
- **[Stop](stop.md)**
diff --git a/content/en/advanced-reference/advanced-concepts/architecture/actions/check.md b/content/en/advanced-reference/advanced-concepts/architecture/actions/check.md
new file mode 100644
index 0000000..aaefb2f
--- /dev/null
+++ b/content/en/advanced-reference/advanced-concepts/architecture/actions/check.md
@@ -0,0 +1,17 @@
+---
+title: Condition Action Architecture
+description: Technical implementation of logical evaluation.
+---
+
+# Condition Action Architecture
+
+The Condition action (internally `condition`) evaluates logical expressions using a recursive grouping strategy.
+
+## Evaluation Engine
+The engine converts the UI-defined condition groups into optimized Python expressions at runtime. These expressions are evaluated within a sandboxed environment with access to the `ExecutionContext`.
+
+## Collection Evaluation
+When evaluating collections (e.g., child tables), the engine iterates through the collection and applies the nested criteria to each element. It supports three evaluation modes:
+- `any`: Returns True if at least one element matches.
+- `all`: Returns True if all elements match.
+- `none`: Returns True if no elements match.
diff --git a/content/en/advanced-reference/advanced-concepts/architecture/actions/document-action.md b/content/en/advanced-reference/advanced-concepts/architecture/actions/document-action.md
new file mode 100644
index 0000000..4829096
--- /dev/null
+++ b/content/en/advanced-reference/advanced-concepts/architecture/actions/document-action.md
@@ -0,0 +1,17 @@
+---
+title: Document Action Architecture
+description: Technical implementation of Create/Update operations.
+---
+
+# Document Action Architecture
+
+The Document Action (internally `document_action`) handles CRUD operations on Frappe DocTypes.
+
+## Field Mapping
+Mappings define how values are transferred from the execution context to the target document. It supports:
+- Direct value set-value.
+- Formula-based mapping.
+- Type-aware conversion.
+
+## Asynchronous Execution
+For performance-heavy operations, document actions can be configured to execute in background workers, preventing UI lag during complex record creation chains.
diff --git a/content/en/advanced-concepts/architecture/actions/entry.md b/content/en/advanced-reference/advanced-concepts/architecture/actions/entry.md
similarity index 96%
rename from content/en/advanced-concepts/architecture/actions/entry.md
rename to content/en/advanced-reference/advanced-concepts/architecture/actions/entry.md
index 476c89d..a80219a 100644
--- a/content/en/advanced-concepts/architecture/actions/entry.md
+++ b/content/en/advanced-reference/advanced-concepts/architecture/actions/entry.md
@@ -47,7 +47,7 @@ The Entry Action uses **Implicit Initialization**. It does not perform explicit
## Extension Points
The Entry Action is considered a "Closed Core" component. Developers should not override the `EntryActionHandler` as it would break the fundamental graph-traversal guarantees of the engine.
-If customization is needed for "initialization" logic, it is recommended to use an [Assignment]({{< relref "action-types/assignment" >}}) node immediately following the Entry Action.
+If customization is needed for "initialization" logic, it is recommended to use an [Assignment]({{< relref "core-actions/set-value" >}}) node immediately following the Entry Action.
## Internal Events
- **`rule_execution_start`**: Fired by the `RuleEngine` immediately before the Entry Action is processed.
diff --git a/content/en/advanced-concepts/architecture/actions/notify.md b/content/en/advanced-reference/advanced-concepts/architecture/actions/notify.md
similarity index 96%
rename from content/en/advanced-concepts/architecture/actions/notify.md
rename to content/en/advanced-reference/advanced-concepts/architecture/actions/notify.md
index cb93fa5..a65e996 100644
--- a/content/en/advanced-concepts/architecture/actions/notify.md
+++ b/content/en/advanced-reference/advanced-concepts/architecture/actions/notify.md
@@ -87,8 +87,8 @@ The Notify action is strictly **Read-Only** regarding the Rule Context. It does
- **Action Metadata**: `flexirule/ruleflow/core/contracts.py`
## Related Topics
-- [Action Documentation]({{< relref "action-types/notify/" >}})
-- [Execution Semantics]({{< relref "advanced-concepts/reference/execution/notify.md" >}})
+- [Action Documentation]({{< relref "core-actions/notify-action" >}})
+- [Execution Semantics]({{< relref "advanced-reference/advanced-concepts/reference/execution/notify.md" >}})
## Performance Considerations
- **Synchronous vs. Asynchronous**: While the rule engine executes synchronously, modes like `Email` are effectively asynchronous as they rely on the Frappe Email Queue.
diff --git a/content/en/advanced-concepts/architecture/actions/query-records.md b/content/en/advanced-reference/advanced-concepts/architecture/actions/query-records.md
similarity index 96%
rename from content/en/advanced-concepts/architecture/actions/query-records.md
rename to content/en/advanced-reference/advanced-concepts/architecture/actions/query-records.md
index 3ea0089..d89b36c 100644
--- a/content/en/advanced-concepts/architecture/actions/query-records.md
+++ b/content/en/advanced-reference/advanced-concepts/architecture/actions/query-records.md
@@ -33,8 +33,8 @@ The **Query Records** action is implemented as a core Action Handler within the
The handler translates UI-level filter definitions into the tuple format expected by `frappe.get_list`. Detailed operator mappings and natural language keyword resolution are shared across the system.
-- **Operator Mappings**: See [Query Filters Reference]({{< relref "advanced-concepts/reference/query-filters" >}}).
-- **Timespan Resolution**: Handled via `_resolve_timespan_range()`, using the logic defined in [Timespan Keywords]({{< relref "advanced-concepts/reference/timespan-keywords" >}}).
+- **Operator Mappings**: See [Query Filters Reference]({{< relref "advanced-reference/advanced-concepts/reference/query-filters" >}}).
+- **Timespan Resolution**: Handled via `_resolve_timespan_range()`, using the logic defined in [Timespan Keywords]({{< relref "advanced-reference/advanced-concepts/reference/timespan-keywords" >}}).
### Nested Field Support
The architecture supports "dot-notation" for filtering on child table fields and linked documents. The `_doctype_has_field` method recursively validates these references against the DocType metadata at validation time.
diff --git a/content/en/advanced-concepts/architecture/actions/loop.md b/content/en/advanced-reference/advanced-concepts/architecture/actions/repeat.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/actions/loop.md
rename to content/en/advanced-reference/advanced-concepts/architecture/actions/repeat.md
diff --git a/content/en/advanced-reference/advanced-concepts/architecture/actions/set-value.md b/content/en/advanced-reference/advanced-concepts/architecture/actions/set-value.md
new file mode 100644
index 0000000..05ef39a
--- /dev/null
+++ b/content/en/advanced-reference/advanced-concepts/architecture/actions/set-value.md
@@ -0,0 +1,22 @@
+---
+title: Assignment Action Architecture
+description: Technical implementation details of the Assignment action.
+---
+
+# Assignment Action Architecture
+
+The Assignment action (internally `set-value`) is responsible for state mutation within the FlexiRule engine.
+
+## Normalization Value Resolver
+The set-value action leverages the `NormalizationValueResolver` to process values before they are applied to the target. This includes:
+- Type casting.
+- String transformations (trim, uppercase, lowercase).
+- Handling of complex formula evaluation via the `FormulaEvaluator`.
+
+## Batch Assignments
+Assignments are executed as a batch. The engine iterates through the defined rows, evaluates the `when` condition for each row, and if true, resolves the value and applies the operator to the target path.
+
+## Target Resolution
+Targets are resolved against the `ExecutionContext`.
+- `doc.*` paths are mapped to the primary document object.
+- `vars.*` paths are mapped to the local execution variables.
diff --git a/content/en/advanced-concepts/architecture/actions/stop.md b/content/en/advanced-reference/advanced-concepts/architecture/actions/stop.md
similarity index 88%
rename from content/en/advanced-concepts/architecture/actions/stop.md
rename to content/en/advanced-reference/advanced-concepts/architecture/actions/stop.md
index df36c9a..676e5e3 100644
--- a/content/en/advanced-concepts/architecture/actions/stop.md
+++ b/content/en/advanced-reference/advanced-concepts/architecture/actions/stop.md
@@ -41,5 +41,5 @@ The Stop action is **Read-Only**. It never modifies the context. However, in `Er
- **Contract**: `flexirule/ruleflow/core/contracts.py`
## Related Topics
-- [Action Documentation]({{< relref "advanced-concepts/architecture/actions/stop.md" >}})
-- [Execution Semantics]({{< relref "advanced-concepts/reference/execution/stop.md" >}})
+- [Action Documentation]({{< relref "advanced-reference/advanced-concepts/architecture/actions/stop.md" >}})
+- [Execution Semantics]({{< relref "advanced-reference/advanced-concepts/reference/execution/stop.md" >}})
diff --git a/content/en/advanced-concepts/architecture/contracts/_index.md b/content/en/advanced-reference/advanced-concepts/architecture/contracts/_index.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/contracts/_index.md
rename to content/en/advanced-reference/advanced-concepts/architecture/contracts/_index.md
diff --git a/content/en/advanced-concepts/architecture/engine/_index.md b/content/en/advanced-reference/advanced-concepts/architecture/engine/_index.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/engine/_index.md
rename to content/en/advanced-reference/advanced-concepts/architecture/engine/_index.md
diff --git a/content/en/advanced-concepts/architecture/engine/action-implementation.md b/content/en/advanced-reference/advanced-concepts/architecture/engine/action-implementation.md
similarity index 92%
rename from content/en/advanced-concepts/architecture/engine/action-implementation.md
rename to content/en/advanced-reference/advanced-concepts/architecture/engine/action-implementation.md
index 3604bda..7e65b57 100644
--- a/content/en/advanced-concepts/architecture/engine/action-implementation.md
+++ b/content/en/advanced-reference/advanced-concepts/architecture/engine/action-implementation.md
@@ -15,11 +15,11 @@ This page provides a technical deep-dive into how FlexiRule actions are implemen
The Assignment action handles batch state mutation of the execution context.
### Backend Handler
-- **Class**: `flexirule.ruleflow.core.action_handlers.assignment.AssignmentHandler`
-- **Logic**: Iterates through a configured array of assignment rows, resolving values and applying operators sequentially.
+- **Class**: `flexirule.ruleflow.core.action_handlers.set-value.AssignmentHandler`
+- **Logic**: Iterates through a configured array of set-value rows, resolving values and applying operators sequentially.
### Path Protection & Validation
-To maintain system integrity, the engine enforces strict validation on assignment targets:
+To maintain system integrity, the engine enforces strict validation on set-value targets:
- **Namespace Protection**: The `_validate_target_path` method blocks writes to `meta.*`, `frappe.*`, `rule.*`, and `caller.*`.
- **Allowed Prefixes**: Targets must start with either `doc.` (document mutation) or `vars.` (context variable mutation).
- **Event Restrictions**: Mutations to `doc.*` are restricted during specific lifecycle events (e.g., `after_save`, `on_update`) to prevent recursive hook loops. These are defined in the `AFTER_EVENT_MUTATION_BLOCKLIST`.
@@ -62,7 +62,7 @@ config:
FlexiRule uses a **Direct Mutation Model** for document fields and local variables.
-1. **In-Memory Buffer**: When an assignment target starts with `doc.`, the engine modifies the in-memory document object. It does not perform an immediate `db.sql` or `doc.db_set` operation unless explicitly handled by the trigger context.
+1. **In-Memory Buffer**: When an set-value target starts with `doc.`, the engine modifies the in-memory document object. It does not perform an immediate `db.sql` or `doc.db_set` operation unless explicitly handled by the trigger context.
2. **Variable Lifecycle**: Targets starting with `vars.` are stored in the `execution_context`. These variables are transient and are destroyed once the rule execution path terminates or the maximum iteration limit is reached.
3. **Sequential Visibility**: Because mutations are applied to the active context, Row 2 of an Assignment action "sees" the changes made by Row 1. This is critical for cumulative calculations.
diff --git a/content/en/advanced-concepts/architecture/engine/condition-system.md b/content/en/advanced-reference/advanced-concepts/architecture/engine/condition-system.md
similarity index 99%
rename from content/en/advanced-concepts/architecture/engine/condition-system.md
rename to content/en/advanced-reference/advanced-concepts/architecture/engine/condition-system.md
index aa82314..05e693f 100644
--- a/content/en/advanced-concepts/architecture/engine/condition-system.md
+++ b/content/en/advanced-reference/advanced-concepts/architecture/engine/condition-system.md
@@ -32,7 +32,7 @@ The **Condition Builder** is a recursive Vue 3 interface that allows users to co
- **Input**: User interactions (drag-and-drop, field selection, operator picking).
- **Output**: A standardized **JSON AST (Abstract Syntax Tree)**.
- **Key Files**: `ConditionBuilder.vue`, `ConditionNode.vue`, `SimpleCondition.vue`.
-- **Detailed Guide**: [Condition Builder Frontend]({{< relref "action-types/condition.md" >}})
+- **Detailed Guide**: [Condition Builder Frontend]({{< relref "core-actions/check.md" >}})
### 2. The Condition Compiler (Backend - Save-Time)
diff --git a/content/en/advanced-concepts/architecture/engine/execution-engine.md b/content/en/advanced-reference/advanced-concepts/architecture/engine/execution-engine.md
similarity index 92%
rename from content/en/advanced-concepts/architecture/engine/execution-engine.md
rename to content/en/advanced-reference/advanced-concepts/architecture/engine/execution-engine.md
index 81c3f3e..ff4052b 100644
--- a/content/en/advanced-concepts/architecture/engine/execution-engine.md
+++ b/content/en/advanced-reference/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" >}})
-- [Glossary]({{< relref "advanced-concepts/reference/glossary.md" >}})
-- [API Reference]({{< relref "api-reference/public-apis.md" >}})
+- [Rule Building]({{< relref "using-the-builder/canvas-navigation.md" >}})
+- [Glossary]({{< relref "advanced-reference/advanced-concepts/reference/glossary.md" >}})
+- [API Reference]({{< relref "advanced-reference/api-reference/public-apis.md" >}})
diff --git a/content/en/advanced-concepts/architecture/engine/orchestration.md b/content/en/advanced-reference/advanced-concepts/architecture/engine/orchestration.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/engine/orchestration.md
rename to content/en/advanced-reference/advanced-concepts/architecture/engine/orchestration.md
diff --git a/content/en/advanced-concepts/architecture/internals/_index.md b/content/en/advanced-reference/advanced-concepts/architecture/internals/_index.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/internals/_index.md
rename to content/en/advanced-reference/advanced-concepts/architecture/internals/_index.md
diff --git a/content/en/advanced-concepts/architecture/overview.md b/content/en/advanced-reference/advanced-concepts/architecture/overview.md
similarity index 89%
rename from content/en/advanced-concepts/architecture/overview.md
rename to content/en/advanced-reference/advanced-concepts/architecture/overview.md
index fcbb036..a242b0a 100644
--- a/content/en/advanced-concepts/architecture/overview.md
+++ b/content/en/advanced-reference/advanced-concepts/architecture/overview.md
@@ -89,6 +89,6 @@ The system includes a built-in technical audit mechanism to ensure rule integrit
## Related Topics
-- [Execution Engine]({{< relref "advanced-concepts/architecture/engine/execution-engine.md" >}})
-- [API Reference]({{< relref "api-reference/public-apis.md" >}})
-- [DocType Reference]({{< relref "advanced-concepts/reference/doctypes.md" >}})
+- [Execution Engine]({{< relref "advanced-reference/advanced-concepts/architecture/engine/execution-engine.md" >}})
+- [API Reference]({{< relref "advanced-reference/api-reference/public-apis.md" >}})
+- [DocType Reference]({{< relref "advanced-reference/advanced-concepts/reference/doctypes.md" >}})
diff --git a/content/en/advanced-concepts/architecture/resolver/_index.md b/content/en/advanced-reference/advanced-concepts/architecture/resolver/_index.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/resolver/_index.md
rename to content/en/advanced-reference/advanced-concepts/architecture/resolver/_index.md
diff --git a/content/en/advanced-concepts/architecture/resolver/resolver-patterns.md b/content/en/advanced-reference/advanced-concepts/architecture/resolver/resolver-patterns.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/resolver/resolver-patterns.md
rename to content/en/advanced-reference/advanced-concepts/architecture/resolver/resolver-patterns.md
diff --git a/content/en/advanced-concepts/architecture/runtime/_index.md b/content/en/advanced-reference/advanced-concepts/architecture/runtime/_index.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/runtime/_index.md
rename to content/en/advanced-reference/advanced-concepts/architecture/runtime/_index.md
diff --git a/content/en/advanced-concepts/architecture/runtime/execution-context.md b/content/en/advanced-reference/advanced-concepts/architecture/runtime/execution-context.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/runtime/execution-context.md
rename to content/en/advanced-reference/advanced-concepts/architecture/runtime/execution-context.md
diff --git a/content/en/advanced-concepts/architecture/runtime/graph-orchestration.md b/content/en/advanced-reference/advanced-concepts/architecture/runtime/graph-orchestration.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/runtime/graph-orchestration.md
rename to content/en/advanced-reference/advanced-concepts/architecture/runtime/graph-orchestration.md
diff --git a/content/en/advanced-concepts/architecture/runtime/overview.md b/content/en/advanced-reference/advanced-concepts/architecture/runtime/overview.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/runtime/overview.md
rename to content/en/advanced-reference/advanced-concepts/architecture/runtime/overview.md
diff --git a/content/en/advanced-concepts/architecture/ui/_index.md b/content/en/advanced-reference/advanced-concepts/architecture/ui/_index.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/ui/_index.md
rename to content/en/advanced-reference/advanced-concepts/architecture/ui/_index.md
diff --git a/content/en/advanced-concepts/architecture/ui/action-config-panels.md b/content/en/advanced-reference/advanced-concepts/architecture/ui/action-config-panels.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/ui/action-config-panels.md
rename to content/en/advanced-reference/advanced-concepts/architecture/ui/action-config-panels.md
diff --git a/content/en/advanced-concepts/architecture/ui/component-registry.md b/content/en/advanced-reference/advanced-concepts/architecture/ui/component-registry.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/ui/component-registry.md
rename to content/en/advanced-reference/advanced-concepts/architecture/ui/component-registry.md
diff --git a/content/en/advanced-concepts/architecture/ui/controls.md b/content/en/advanced-reference/advanced-concepts/architecture/ui/controls.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/ui/controls.md
rename to content/en/advanced-reference/advanced-concepts/architecture/ui/controls.md
diff --git a/content/en/advanced-concepts/architecture/ui/dynamic-forms.md b/content/en/advanced-reference/advanced-concepts/architecture/ui/dynamic-forms.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/ui/dynamic-forms.md
rename to content/en/advanced-reference/advanced-concepts/architecture/ui/dynamic-forms.md
diff --git a/content/en/advanced-concepts/architecture/ui/overview.md b/content/en/advanced-reference/advanced-concepts/architecture/ui/overview.md
similarity index 100%
rename from content/en/advanced-concepts/architecture/ui/overview.md
rename to content/en/advanced-reference/advanced-concepts/architecture/ui/overview.md
diff --git a/content/en/advanced-concepts/data-manipulation/_index.md b/content/en/advanced-reference/advanced-concepts/data-manipulation/_index.md
similarity index 100%
rename from content/en/advanced-concepts/data-manipulation/_index.md
rename to content/en/advanced-reference/advanced-concepts/data-manipulation/_index.md
diff --git a/content/en/advanced-concepts/data-manipulation/normalization-value-resolver.md b/content/en/advanced-reference/advanced-concepts/data-manipulation/normalization-value-resolver.md
similarity index 96%
rename from content/en/advanced-concepts/data-manipulation/normalization-value-resolver.md
rename to content/en/advanced-reference/advanced-concepts/data-manipulation/normalization-value-resolver.md
index 49cf63b..2780a5a 100644
--- a/content/en/advanced-concepts/data-manipulation/normalization-value-resolver.md
+++ b/content/en/advanced-reference/advanced-concepts/data-manipulation/normalization-value-resolver.md
@@ -78,11 +78,11 @@ The Resolver includes a built-in testing area where you can:
By using the Normalization Value Resolver, business users can:
- **Enforce Data Integrity**: Ensure that inputs (like phone numbers or names) follow a consistent format before they are saved.
-- **Simplify Rules**: Reduce the number of nodes in a rule by handling data cleaning within the assignment or condition itself.
+- **Simplify Rules**: Reduce the number of nodes in a rule by handling data cleaning within the set-value or condition itself.
- **Bridge Data Formats**: Easily transform data between different formats (e.g., converting a raw string into a URL-safe slug).
## Where to find it?
The Normalization Value Resolver is integrated into:
-- [Assignment Action]({{< relref "action-types/assignment/" >}})
-- [Condition Nodes]({{< relref "action-types/condition/" >}})
+- [Assignment Action]({{< relref "core-actions/set-value/" >}})
+- [Condition Nodes]({{< relref "core-actions/check" >}})
- Any configuration panel requiring data mapping.
diff --git a/content/en/advanced-concepts/decision-trees.md b/content/en/advanced-reference/advanced-concepts/decision-trees.md
similarity index 92%
rename from content/en/advanced-concepts/decision-trees.md
rename to content/en/advanced-reference/advanced-concepts/decision-trees.md
index 9f1b80b..91b9e03 100644
--- a/content/en/advanced-concepts/decision-trees.md
+++ b/content/en/advanced-reference/advanced-concepts/decision-trees.md
@@ -83,6 +83,6 @@ Need to process a collection?
## Related Topics
-- [Glossary]({{< relref "advanced-concepts/reference/glossary.md" >}})
-- [Rule Builder]({{< relref "rule-builder/canvas-navigation.md" >}})
-- [Action Zone]({{< relref "action-types/" >}})
+- [Glossary]({{< relref "advanced-reference/advanced-concepts/reference/glossary.md" >}})
+- [Rule Builder]({{< relref "using-the-builder/canvas-navigation.md" >}})
+- [Action Zone]({{< relref "core-actions/" >}})
diff --git a/content/en/advanced-concepts/reference/_index.md b/content/en/advanced-reference/advanced-concepts/reference/_index.md
similarity index 100%
rename from content/en/advanced-concepts/reference/_index.md
rename to content/en/advanced-reference/advanced-concepts/reference/_index.md
diff --git a/content/en/advanced-concepts/reference/ai/_index.md b/content/en/advanced-reference/advanced-concepts/reference/ai/_index.md
similarity index 100%
rename from content/en/advanced-concepts/reference/ai/_index.md
rename to content/en/advanced-reference/advanced-concepts/reference/ai/_index.md
diff --git a/content/en/advanced-concepts/reference/ai/action-metadata-schema.md b/content/en/advanced-reference/advanced-concepts/reference/ai/action-metadata-schema.md
similarity index 98%
rename from content/en/advanced-concepts/reference/ai/action-metadata-schema.md
rename to content/en/advanced-reference/advanced-concepts/reference/ai/action-metadata-schema.md
index 9c2b1e1..c032b5a 100644
--- a/content/en/advanced-concepts/reference/ai/action-metadata-schema.md
+++ b/content/en/advanced-reference/advanced-concepts/reference/ai/action-metadata-schema.md
@@ -26,7 +26,7 @@ Standardized metadata allows AI models and system tools to understand the capabi
| Field | Type | Description |
| :--- | :--- | :--- |
-| `action` | `string` | The unique identifier of the action (e.g., `assignment`, `query-records`). |
+| `action` | `string` | The unique identifier of the action (e.g., `set-value`, `query-records`). |
| `category` | `string` | The high-level grouping (e.g., `data`, `flow`, `integration`). |
| `targets` | `array` | List of data types this action can modify (`doc`, `vars`, `db`). |
| `operators` | `array` | List of supported operations (if applicable). |
@@ -49,7 +49,7 @@ Standardized metadata allows AI models and system tools to understand the capabi
### 1. Assignment Action
```json
{
- "action": "assignment",
+ "action": "set-value",
"category": "data",
"targets": ["doc", "vars"],
"operators": ["set", "clear", "increment", "decrement", "append", "merge", "toggle"],
diff --git a/content/en/advanced-concepts/reference/doctypes.md b/content/en/advanced-reference/advanced-concepts/reference/doctypes.md
similarity index 85%
rename from content/en/advanced-concepts/reference/doctypes.md
rename to content/en/advanced-reference/advanced-concepts/reference/doctypes.md
index 3bf783f..ae902f4 100644
--- a/content/en/advanced-concepts/reference/doctypes.md
+++ b/content/en/advanced-reference/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 "using-the-builder/canvas-navigation.md" >}}), which handles the creation of these child records automatically.
| Field | Type | Description |
| :--- | :--- | :--- |
@@ -93,6 +93,6 @@ 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" >}})
-- [API Reference]({{< relref "api-reference/public-apis.md" >}})
+- [Execution Engine]({{< relref "advanced-reference/advanced-concepts/architecture/engine/execution-engine.md" >}})
+- [Rule Builder]({{< relref "using-the-builder/canvas-navigation.md" >}})
+- [API Reference]({{< relref "advanced-reference/api-reference/public-apis.md" >}})
diff --git a/content/en/advanced-concepts/reference/execution/_index.md b/content/en/advanced-reference/advanced-concepts/reference/execution/_index.md
similarity index 85%
rename from content/en/advanced-concepts/reference/execution/_index.md
rename to content/en/advanced-reference/advanced-concepts/reference/execution/_index.md
index de7e654..b0f3e9b 100644
--- a/content/en/advanced-concepts/reference/execution/_index.md
+++ b/content/en/advanced-reference/advanced-concepts/reference/execution/_index.md
@@ -10,10 +10,10 @@ Welcome to the Execution section. This section contains detailed information abo
## Sub-pages
-- **[Condition](condition.md)**
+- **[Condition](check.md)**
- **[Document Action](document-action.md)**
- **[Entry](entry.md)**
- **[Loop](loop.md)**
- **[Notify](notify.md)**
-- **[Query Records](query-records.md)**
+- **[Query Records](query-records)**
- **[Stop](stop.md)**
diff --git a/content/en/advanced-concepts/reference/execution/condition.md b/content/en/advanced-reference/advanced-concepts/reference/execution/condition.md
similarity index 94%
rename from content/en/advanced-concepts/reference/execution/condition.md
rename to content/en/advanced-reference/advanced-concepts/reference/execution/condition.md
index 84ac705..ad21a5d 100644
--- a/content/en/advanced-concepts/reference/execution/condition.md
+++ b/content/en/advanced-reference/advanced-concepts/reference/execution/condition.md
@@ -61,6 +61,6 @@ Since the action is read-only and operates on the local execution context, it is
- **Memory**: The action has a negligible memory footprint as it does not store large datasets.
## Related Topics
-- [Action Documentation]({{< relref "action-types/condition.md" >}})
-- [Architecture Reference]({{< relref "advanced-concepts/architecture/actions/condition.md" >}})
-- [Condition Builder Guide]({{< relref "action-types/condition.md" >}})
+- [Action Documentation]({{< relref "core-actions/check.md" >}})
+- [Architecture Reference]({{< relref "advanced-reference/advanced-concepts/architecture/actions/check.md" >}})
+- [Condition Builder Guide]({{< relref "core-actions/check.md" >}})
diff --git a/content/en/advanced-concepts/reference/execution/document-action.md b/content/en/advanced-reference/advanced-concepts/reference/execution/document-action.md
similarity index 100%
rename from content/en/advanced-concepts/reference/execution/document-action.md
rename to content/en/advanced-reference/advanced-concepts/reference/execution/document-action.md
diff --git a/content/en/advanced-concepts/reference/execution/entry.md b/content/en/advanced-reference/advanced-concepts/reference/execution/entry.md
similarity index 100%
rename from content/en/advanced-concepts/reference/execution/entry.md
rename to content/en/advanced-reference/advanced-concepts/reference/execution/entry.md
diff --git a/content/en/advanced-concepts/reference/execution/loop.md b/content/en/advanced-reference/advanced-concepts/reference/execution/loop.md
similarity index 96%
rename from content/en/advanced-concepts/reference/execution/loop.md
rename to content/en/advanced-reference/advanced-concepts/reference/execution/loop.md
index db5b720..f120d8e 100644
--- a/content/en/advanced-concepts/reference/execution/loop.md
+++ b/content/en/advanced-reference/advanced-concepts/reference/execution/loop.md
@@ -63,4 +63,4 @@ The Loop action itself is **not inherently idempotent** if it modifies document
- **Collection Size**: Large collections (e.g., thousands of items) significantly increase execution time and memory consumption as the entire collection is resolved at every iteration check.
- **Graph Depth**: Deeply nested loops increase the complexity of the execution trace and context memory.
-- **Recommendation**: For processing very large datasets, offload logic to a [Process]({{< relref "advanced-concepts/architecture/overview.md" >}}) or use background jobs via the Rule configuration.
+- **Recommendation**: For processing very large datasets, offload logic to a [Process]({{< relref "advanced-reference/advanced-concepts/architecture/overview.md" >}}) or use background jobs via the Rule configuration.
diff --git a/content/en/advanced-concepts/reference/execution/notify.md b/content/en/advanced-reference/advanced-concepts/reference/execution/notify.md
similarity index 95%
rename from content/en/advanced-concepts/reference/execution/notify.md
rename to content/en/advanced-reference/advanced-concepts/reference/execution/notify.md
index 0bdea8f..201c13b 100644
--- a/content/en/advanced-concepts/reference/execution/notify.md
+++ b/content/en/advanced-reference/advanced-concepts/reference/execution/notify.md
@@ -52,8 +52,8 @@ The Notify action interacts with transactions differently depending on the mode:
The Notify action is **not idempotent**. Executing the same Notify action multiple times will result in multiple emails being sent or multiple notifications being created. Use conditional logic (`Run If`) to prevent redundant notifications in re-entrant rules.
## Related Topics
-- [Action Documentation]({{< relref "action-types/notify/" >}})
-- [Architecture Reference]({{< relref "advanced-concepts/architecture/actions/notify.md" >}})
+- [Action Documentation]({{< relref "core-actions/notify-action" >}})
+- [Architecture Reference]({{< relref "advanced-reference/advanced-concepts/architecture/actions/notify.md" >}})
## Performance Notes
- **Email Overhead**: While `frappe.sendmail` is generally fast (queuing), generating complex PDF attachments can be resource-intensive.
diff --git a/content/en/advanced-concepts/reference/execution/query-records.md b/content/en/advanced-reference/advanced-concepts/reference/execution/query-records.md
similarity index 93%
rename from content/en/advanced-concepts/reference/execution/query-records.md
rename to content/en/advanced-reference/advanced-concepts/reference/execution/query-records.md
index aff9313..aefa212 100644
--- a/content/en/advanced-concepts/reference/execution/query-records.md
+++ b/content/en/advanced-reference/advanced-concepts/reference/execution/query-records.md
@@ -23,7 +23,7 @@ When a Query Records action is executed, the engine follows this strict sequence
3. **Filter Resolution**:
- Configuration filters are recursively traversed.
- Expressions (e.g., `{{doc.name}}`) are resolved via the `ValueResolver`.
- - Natural language date keywords are resolved into static date ranges (See [Timespan Keywords]({{< relref "advanced-concepts/reference/timespan-keywords" >}})).
+ - Natural language date keywords are resolved into static date ranges (See [Timespan Keywords]({{< relref "advanced-reference/advanced-concepts/reference/timespan-keywords" >}})).
4. **Database Dispatch**: The query is dispatched to the database layer based on the selected **Mode**.
5. **Output Mutation**: The results are injected into the specified context variable (e.g., `vars.result`).
@@ -50,7 +50,7 @@ Modes like **Count**, **Sum**, **Avg**, **Min**, and **Max** return a primitive
### Complex Outputs
- **Group By**: Returns a list of dictionaries with the keys `[group_field, "value"]`.
-- **Query Report**: Returns an object containing `columns` and `result`. See the [Query Report Detail]({{< relref "action-types/query-records.md" >}}) for usage examples.
+- **Query Report**: Returns an object containing `columns` and `result`. See the [Query Report Detail]({{< relref "core-actions/query-records" >}}) for usage examples.
---
diff --git a/content/en/advanced-concepts/reference/execution/stop.md b/content/en/advanced-reference/advanced-concepts/reference/execution/stop.md
similarity index 88%
rename from content/en/advanced-concepts/reference/execution/stop.md
rename to content/en/advanced-reference/advanced-concepts/reference/execution/stop.md
index 943d041..0533193 100644
--- a/content/en/advanced-concepts/reference/execution/stop.md
+++ b/content/en/advanced-reference/advanced-concepts/reference/execution/stop.md
@@ -31,7 +31,7 @@ The Stop action has read-only access to:
The transaction behavior of the Stop action depends entirely on its mode:
- **Success**: The action has no impact on the current database transaction. The transaction continues as normal and will commit when the overall rule execution (and any other triggered rules) finishes successfully.
-- **Error**: Raising a `frappe.ValidationError` triggers a standard database **Rollback**. Any changes made by previous nodes in the same rule flow (e.g., [Assignment]({{< relref "action-types/assignment" >}}) updates to `doc`) will be reverted.
+- **Error**: Raising a `frappe.ValidationError` triggers a standard database **Rollback**. Any changes made by previous nodes in the same rule flow (e.g., [Assignment]({{< relref "core-actions/set-value" >}}) updates to `doc`) will be reverted.
## Failure Behavior
If the Jinja template in the error message fails to render, the engine will raise a secondary rendering error. However, since the intent was already to stop with an error, the result is still a termination of the flow and a rollback of the transaction.
@@ -43,5 +43,5 @@ The Stop action is inherently idempotent in **Success** mode. In **Error** mode,
The Stop action is extremely lightweight. In `Success` mode, it involves a simple return statement. In `Error` mode, it involves a single Jinja rendering and a standard Python exception.
## Related Topics
-- [Action Documentation]({{< relref "advanced-concepts/architecture/actions/stop.md" >}})
-- [Architecture Reference]({{< relref "advanced-concepts/architecture/actions/stop.md" >}})
+- [Action Documentation]({{< relref "advanced-reference/advanced-concepts/architecture/actions/stop.md" >}})
+- [Architecture Reference]({{< relref "advanced-reference/advanced-concepts/architecture/actions/stop.md" >}})
diff --git a/content/en/advanced-concepts/reference/glossary.md b/content/en/advanced-reference/advanced-concepts/reference/glossary.md
similarity index 84%
rename from content/en/advanced-concepts/reference/glossary.md
rename to content/en/advanced-reference/advanced-concepts/reference/glossary.md
index d80c12d..38e6267 100644
--- a/content/en/advanced-concepts/reference/glossary.md
+++ b/content/en/advanced-reference/advanced-concepts/reference/glossary.md
@@ -15,7 +15,7 @@ Common terminology and core concepts used throughout the FlexiRule documentation
The top-level container for logic. A Rule defines when logic should trigger (e.g., on DocType events, schedulers, or manual calls) and contains the graph of actions to be executed.
Action
- A single node in the Rule's execution graph. Each action represents a specific step, such as a condition, an assignment, or a process execution.
+ A single node in the Rule's execution graph. Each action represents a specific step, such as a condition, an set-value, or a process execution.
Condition
A logic node that evaluates a Python expression to branch the execution flow. It determines which path (True or False) the engine should follow.
@@ -46,6 +46,6 @@ Common terminology and core concepts used throughout the FlexiRule documentation
## Related Topics
-- [System Architecture]({{< relref "advanced-concepts/architecture/" >}})
-- [Execution Engine]({{< relref "advanced-concepts/architecture/engine/execution-engine.md" >}})
-- [Rule Building]({{< relref "rule-builder/canvas-navigation.md" >}})
+- [System Architecture]({{< relref "advanced-reference/advanced-concepts/architecture/" >}})
+- [Execution Engine]({{< relref "advanced-reference/advanced-concepts/architecture/engine/execution-engine.md" >}})
+- [Rule Building]({{< relref "using-the-builder/canvas-navigation.md" >}})
diff --git a/content/en/advanced-concepts/reference/localized/_index.md b/content/en/advanced-reference/advanced-concepts/reference/localized/_index.md
similarity index 100%
rename from content/en/advanced-concepts/reference/localized/_index.md
rename to content/en/advanced-reference/advanced-concepts/reference/localized/_index.md
diff --git a/content/en/advanced-concepts/reference/localized/arabic-overview.md b/content/en/advanced-reference/advanced-concepts/reference/localized/arabic-overview.md
similarity index 100%
rename from content/en/advanced-concepts/reference/localized/arabic-overview.md
rename to content/en/advanced-reference/advanced-concepts/reference/localized/arabic-overview.md
diff --git a/content/en/advanced-concepts/reference/query-filters/index.md b/content/en/advanced-reference/advanced-concepts/reference/query-filters/index.md
similarity index 94%
rename from content/en/advanced-concepts/reference/query-filters/index.md
rename to content/en/advanced-reference/advanced-concepts/reference/query-filters/index.md
index 281f17f..08e1d06 100644
--- a/content/en/advanced-concepts/reference/query-filters/index.md
+++ b/content/en/advanced-reference/advanced-concepts/reference/query-filters/index.md
@@ -69,4 +69,4 @@ Instead of typing a fixed value, you can use the **Value Resolver** to pull data
- `{{vars.target_date}}`: Resolves to a variable calculated in a previous node.
- `{{Today - 7 days}}`: Resolves to a calculated date.
-*See the [Value Resolver]({{< relref "advanced-concepts/architecture/resolver/_index.md" >}}) for full expression syntax.*
+*See the [Value Resolver]({{< relref "advanced-reference/advanced-concepts/architecture/resolver/_index.md" >}}) for full expression syntax.*
diff --git a/content/en/advanced-concepts/reference/terminology.md b/content/en/advanced-reference/advanced-concepts/reference/terminology.md
similarity index 100%
rename from content/en/advanced-concepts/reference/terminology.md
rename to content/en/advanced-reference/advanced-concepts/reference/terminology.md
diff --git a/content/en/advanced-concepts/reference/timespan-keywords/index.md b/content/en/advanced-reference/advanced-concepts/reference/timespan-keywords/index.md
similarity index 100%
rename from content/en/advanced-concepts/reference/timespan-keywords/index.md
rename to content/en/advanced-reference/advanced-concepts/reference/timespan-keywords/index.md
diff --git a/content/en/advanced-concepts/registry-contracts.md b/content/en/advanced-reference/advanced-concepts/registry-contracts.md
similarity index 100%
rename from content/en/advanced-concepts/registry-contracts.md
rename to content/en/advanced-reference/advanced-concepts/registry-contracts.md
diff --git a/content/en/advanced-concepts/roadmap/_index.md b/content/en/advanced-reference/advanced-concepts/roadmap/_index.md
similarity index 81%
rename from content/en/advanced-concepts/roadmap/_index.md
rename to content/en/advanced-reference/advanced-concepts/roadmap/_index.md
index d9bf3ed..785e9ea 100644
--- a/content/en/advanced-concepts/roadmap/_index.md
+++ b/content/en/advanced-reference/advanced-concepts/roadmap/_index.md
@@ -9,5 +9,5 @@ weight: 90
## Vision
- [Platform Potential]({{< relref "platform-potential.md" >}})
- [Event Driven Architecture]({{< relref "event-driven-architecture.md" >}})
-- [Assignment Action Improvements]({{< relref "assignment-action-improvements.md" >}})
+- [Assignment Action Improvements]({{< relref "set-value-action-improvements.md" >}})
- [Runtime Optimization]({{< relref "runtime-optimization.md" >}})
diff --git a/content/en/advanced-concepts/roadmap/documentation-standardization.md b/content/en/advanced-reference/advanced-concepts/roadmap/documentation-standardization.md
similarity index 92%
rename from content/en/advanced-concepts/roadmap/documentation-standardization.md
rename to content/en/advanced-reference/advanced-concepts/roadmap/documentation-standardization.md
index 5b537ec..3d3d242 100644
--- a/content/en/advanced-concepts/roadmap/documentation-standardization.md
+++ b/content/en/advanced-reference/advanced-concepts/roadmap/documentation-standardization.md
@@ -28,8 +28,8 @@ As of the implementation of the documentation framework:
| Action | Task | Benefit |
| :--- | :--- | :--- |
-| **Assignment** | Extract implementation details from `architecture/engine/action-implementation.md` to `architecture/actions/assignment.md`. | Cleans up engine docs; follows 3-layer model. |
-| **Assignment** | Create `reference/execution/assignment.md` by moving "Execution Guarantees" and "State Mutation Model". | Separates runtime behavior from implementation. |
+| **Assignment** | Extract implementation details from `architecture/engine/action-implementation.md` to `architecture/actions/set-value.md`. | Cleans up engine docs; follows 3-layer model. |
+| **Assignment** | Create `reference/execution/set-value.md` by moving "Execution Guarantees" and "State Mutation Model". | Separates runtime behavior from implementation. |
| **All Actions** | Audit and update Layer 1 frontmatter to match the new `capabilities` dimensions. | Ensures UI components render correctly. |
### 2. Structural Refactors (Medium Priority)
diff --git a/content/en/advanced-concepts/roadmap/event-driven-architecture.md b/content/en/advanced-reference/advanced-concepts/roadmap/event-driven-architecture.md
similarity index 100%
rename from content/en/advanced-concepts/roadmap/event-driven-architecture.md
rename to content/en/advanced-reference/advanced-concepts/roadmap/event-driven-architecture.md
diff --git a/content/en/advanced-concepts/roadmap/platform-potential.md b/content/en/advanced-reference/advanced-concepts/roadmap/platform-potential.md
similarity index 100%
rename from content/en/advanced-concepts/roadmap/platform-potential.md
rename to content/en/advanced-reference/advanced-concepts/roadmap/platform-potential.md
diff --git a/content/en/advanced-concepts/roadmap/runtime-optimization.md b/content/en/advanced-reference/advanced-concepts/roadmap/runtime-optimization.md
similarity index 100%
rename from content/en/advanced-concepts/roadmap/runtime-optimization.md
rename to content/en/advanced-reference/advanced-concepts/roadmap/runtime-optimization.md
diff --git a/content/en/advanced-concepts/roadmap/assignment-action-improvements.md b/content/en/advanced-reference/advanced-concepts/roadmap/set-value-action-improvements.md
similarity index 95%
rename from content/en/advanced-concepts/roadmap/assignment-action-improvements.md
rename to content/en/advanced-reference/advanced-concepts/roadmap/set-value-action-improvements.md
index 630cc78..798f2b6 100644
--- a/content/en/advanced-concepts/roadmap/assignment-action-improvements.md
+++ b/content/en/advanced-reference/advanced-concepts/roadmap/set-value-action-improvements.md
@@ -28,7 +28,7 @@ The current Assignment implementation (v1) provides fundamental batch mutation c
### Engine Enhancements
- **Initialization Guard (High)**: Automatically initialize `vars` to a default value (0, empty string, etc.) if they don't exist during an `increment` or `append` operation to avoid manual initialization rows.
-- **Field-Level Suppress (Medium)**: Add a flag to skip change-tracking hooks for specific assignments to prevent triggering recursive rules.
+- **Field-Level Suppress (Medium)**: Add a flag to skip change-tracking hooks for specific set-values to prevent triggering recursive rules.
- **Strict Boolean Toggle (Low)**: Update `Toggle` operator to strictly enforce boolean input, raising a clear validation error for non-boolean types instead of best-effort coercion.
### UI / Builder Enhancements
@@ -48,7 +48,7 @@ The current Assignment implementation (v1) provides fundamental batch mutation c
### UI / Builder Enhancements
- **Mutation Preview (High)**: A "Simulation Mode" in the builder that shows a before/after diff of the document based on the current Assignment configuration.
-- **Execution Trace Visualization (Medium)**: Enhanced visual logs showing the value resolution for every single row in a batch assignment.
+- **Execution Trace Visualization (Medium)**: Enhanced visual logs showing the value resolution for every single row in a batch set-value.
---
@@ -58,7 +58,7 @@ The current Assignment implementation (v1) provides fundamental batch mutation c
### Functional Evolution
- **Cross-Document Mutations (High)**: Support for `link.TARGET_DOC.field` targets, allowing a rule on an Invoice to directly update its parent Sales Order.
-- **State Snapshots & Atomic Rollbacks (Medium)**: The ability to "checkpoint" document state before a batch assignment and perform a partial rollback of just that node on failure.
+- **State Snapshots & Atomic Rollbacks (Medium)**: The ability to "checkpoint" document state before a batch set-value and perform a partial rollback of just that node on failure.
- **Reactive Trigger Suppression (Low)**: Intelligence to detect and block "Circular Assignment Paths" at compile-time (e.g., `doc.A` updates `doc.B`, which has a rule that updates `doc.A`).
---
diff --git a/content/en/advanced-concepts/rule-entry-condition-vs-condition-action.md b/content/en/advanced-reference/advanced-concepts/rule-entry-condition-vs-condition-action.md
similarity index 96%
rename from content/en/advanced-concepts/rule-entry-condition-vs-condition-action.md
rename to content/en/advanced-reference/advanced-concepts/rule-entry-condition-vs-condition-action.md
index 081e47c..3cc8615 100644
--- a/content/en/advanced-concepts/rule-entry-condition-vs-condition-action.md
+++ b/content/en/advanced-reference/advanced-concepts/rule-entry-condition-vs-condition-action.md
@@ -21,7 +21,7 @@ However, they serve very different purposes.
## Quick Summary
-| Use Case | Rule Entry Condition | [Condition Action]({{< relref "action-types/condition.md" >}}) |
+| Use Case | Rule Entry Condition | [Condition Action]({{< relref "core-actions/check.md" >}}) |
| :--- | :---: | :---: |
| Decide whether the rule should run at all | ✅ Yes | ❌ No |
| Create branching logic inside a rule | ❌ No | ✅ Yes |
@@ -34,7 +34,7 @@ However, they serve very different purposes.
## What is a Rule Entry Condition?
-A **Rule Entry Condition** acts as a gatekeeper for the entire rule. It is configured as part of the [Rule Trigger Configuration]({{< relref "advanced-concepts/triggers/_index.md" >}}).
+A **Rule Entry Condition** acts as a gatekeeper for the entire rule. It is configured as part of the [Rule Trigger Configuration]({{< relref "advanced-reference/advanced-concepts/triggers/_index.md" >}}).
{{< info >}}
While the UI uses the term **Rule Entry Condition**, it is best understood as the **Trigger Condition** or **Trigger Filter**.
@@ -108,7 +108,7 @@ Condition: Customer is VIP?
### Recommended Uses
-Use a [Condition Action]({{< relref "action-types/condition.md" >}}) when you need:
+Use a [Condition Action]({{< relref "core-actions/check.md" >}}) when you need:
- **If / Else logic**: Branching into different paths.
- **Guarded Sequences**: Executing specific actions only under certain conditions within a larger flow.
- **Decision Trees**: Handling complex business logic after the rule has been triggered.
diff --git a/content/en/advanced-concepts/system-philosophy.md b/content/en/advanced-reference/advanced-concepts/system-philosophy.md
similarity index 100%
rename from content/en/advanced-concepts/system-philosophy.md
rename to content/en/advanced-reference/advanced-concepts/system-philosophy.md
diff --git a/content/en/advanced-concepts/triggers/_index.md b/content/en/advanced-reference/advanced-concepts/triggers/_index.md
similarity index 92%
rename from content/en/advanced-concepts/triggers/_index.md
rename to content/en/advanced-reference/advanced-concepts/triggers/_index.md
index 1480bca..a3cb222 100644
--- a/content/en/advanced-concepts/triggers/_index.md
+++ b/content/en/advanced-reference/advanced-concepts/triggers/_index.md
@@ -28,4 +28,4 @@ Triggers act as the entry point for all business logic in FlexiRule. They determ
---
## Technical Details
-For implementation details on the dispatcher, see **[Rule Coordinator]({{< relref "advanced-concepts/architecture/runtime/overview.md" >}})**.
+For implementation details on the dispatcher, see **[Rule Coordinator]({{< relref "advanced-reference/advanced-concepts/architecture/runtime/overview.md" >}})**.
diff --git a/content/en/advanced-concepts/triggers/callable-triggers.md b/content/en/advanced-reference/advanced-concepts/triggers/callable-triggers.md
similarity index 100%
rename from content/en/advanced-concepts/triggers/callable-triggers.md
rename to content/en/advanced-reference/advanced-concepts/triggers/callable-triggers.md
diff --git a/content/en/advanced-concepts/triggers/context-reference.md b/content/en/advanced-reference/advanced-concepts/triggers/context-reference.md
similarity index 100%
rename from content/en/advanced-concepts/triggers/context-reference.md
rename to content/en/advanced-reference/advanced-concepts/triggers/context-reference.md
diff --git a/content/en/advanced-concepts/triggers/engine-details.md b/content/en/advanced-reference/advanced-concepts/triggers/engine-details.md
similarity index 100%
rename from content/en/advanced-concepts/triggers/engine-details.md
rename to content/en/advanced-reference/advanced-concepts/triggers/engine-details.md
diff --git a/content/en/advanced-concepts/triggers/event-triggers.md b/content/en/advanced-reference/advanced-concepts/triggers/event-triggers.md
similarity index 100%
rename from content/en/advanced-concepts/triggers/event-triggers.md
rename to content/en/advanced-reference/advanced-concepts/triggers/event-triggers.md
diff --git a/content/en/advanced-concepts/triggers/scheduler-triggers.md b/content/en/advanced-reference/advanced-concepts/triggers/scheduler-triggers.md
similarity index 100%
rename from content/en/advanced-concepts/triggers/scheduler-triggers.md
rename to content/en/advanced-reference/advanced-concepts/triggers/scheduler-triggers.md
diff --git a/content/en/api-reference/_index.md b/content/en/advanced-reference/api-reference/_index.md
similarity index 100%
rename from content/en/api-reference/_index.md
rename to content/en/advanced-reference/api-reference/_index.md
diff --git a/content/en/api-reference/contracts.md b/content/en/advanced-reference/api-reference/contracts.md
similarity index 100%
rename from content/en/api-reference/contracts.md
rename to content/en/advanced-reference/api-reference/contracts.md
diff --git a/content/en/api-reference/hooks.md b/content/en/advanced-reference/api-reference/hooks.md
similarity index 100%
rename from content/en/api-reference/hooks.md
rename to content/en/advanced-reference/api-reference/hooks.md
diff --git a/content/en/api-reference/public-apis.md b/content/en/advanced-reference/api-reference/public-apis.md
similarity index 100%
rename from content/en/api-reference/public-apis.md
rename to content/en/advanced-reference/api-reference/public-apis.md
diff --git a/content/en/developer-guide/_index.md b/content/en/advanced-reference/developer-guide/_index.md
similarity index 100%
rename from content/en/developer-guide/_index.md
rename to content/en/advanced-reference/developer-guide/_index.md
diff --git a/content/en/introduction/performance.md b/content/en/advanced-reference/performance.md
similarity index 100%
rename from content/en/introduction/performance.md
rename to content/en/advanced-reference/performance.md
diff --git a/content/en/performance/_index.md b/content/en/advanced-reference/performance/_index.md
similarity index 100%
rename from content/en/performance/_index.md
rename to content/en/advanced-reference/performance/_index.md
diff --git a/content/en/performance/architecture.md b/content/en/advanced-reference/performance/architecture.md
similarity index 100%
rename from content/en/performance/architecture.md
rename to content/en/advanced-reference/performance/architecture.md
diff --git a/content/en/performance/optimization.md b/content/en/advanced-reference/performance/optimization.md
similarity index 93%
rename from content/en/performance/optimization.md
rename to content/en/advanced-reference/performance/optimization.md
index e408951..b55ada2 100644
--- a/content/en/performance/optimization.md
+++ b/content/en/advanced-reference/performance/optimization.md
@@ -19,7 +19,7 @@ FlexiRule automatically watches fields used in your conditions. If you have a ve
## 3. Efficient Assignments
When using the **Assignment** action, try to group related updates into a single node.
-- Each node has a small overhead. 1 node with 5 assignment rows is slightly faster than 5 nodes with 1 row each.
+- Each node has a small overhead. 1 node with 5 set-value rows is slightly faster than 5 nodes with 1 row each.
## 4. Query Records Best Practices
The **Query Records** action can be the most expensive node in a rule.
diff --git a/content/en/introduction/better-than-hard-coded.md b/content/en/advanced-reference/philosophy/better-than-hard-coded.md
similarity index 100%
rename from content/en/introduction/better-than-hard-coded.md
rename to content/en/advanced-reference/philosophy/better-than-hard-coded.md
diff --git a/content/en/introduction/do-i-need-flexirule.md b/content/en/advanced-reference/philosophy/do-i-need-flexirule.md
similarity index 100%
rename from content/en/introduction/do-i-need-flexirule.md
rename to content/en/advanced-reference/philosophy/do-i-need-flexirule.md
diff --git a/content/en/introduction/erpnext-need.md b/content/en/advanced-reference/philosophy/erpnext-need.md
similarity index 100%
rename from content/en/introduction/erpnext-need.md
rename to content/en/advanced-reference/philosophy/erpnext-need.md
diff --git a/content/en/introduction/why-flexirule.md b/content/en/advanced-reference/philosophy/why-flexirule.md
similarity index 100%
rename from content/en/introduction/why-flexirule.md
rename to content/en/advanced-reference/philosophy/why-flexirule.md
diff --git a/content/en/setup/_index.md b/content/en/advanced-reference/setup/_index.md
similarity index 100%
rename from content/en/setup/_index.md
rename to content/en/advanced-reference/setup/_index.md
diff --git a/content/en/setup/initial-configuration.md b/content/en/advanced-reference/setup/initial-configuration.md
similarity index 100%
rename from content/en/setup/initial-configuration.md
rename to content/en/advanced-reference/setup/initial-configuration.md
diff --git a/content/en/setup/installation.md b/content/en/advanced-reference/setup/installation.md
similarity index 100%
rename from content/en/setup/installation.md
rename to content/en/advanced-reference/setup/installation.md
diff --git a/content/en/setup/permissions.md b/content/en/advanced-reference/setup/permissions.md
similarity index 100%
rename from content/en/setup/permissions.md
rename to content/en/advanced-reference/setup/permissions.md
diff --git a/content/en/setup/settings.md b/content/en/advanced-reference/setup/settings.md
similarity index 100%
rename from content/en/setup/settings.md
rename to content/en/advanced-reference/setup/settings.md
diff --git a/content/en/setup/troubleshooting.md b/content/en/advanced-reference/setup/troubleshooting.md
similarity index 100%
rename from content/en/setup/troubleshooting.md
rename to content/en/advanced-reference/setup/troubleshooting.md
diff --git a/content/en/troubleshooting/_index.md b/content/en/advanced-reference/troubleshooting/_index.md
similarity index 100%
rename from content/en/troubleshooting/_index.md
rename to content/en/advanced-reference/troubleshooting/_index.md
diff --git a/content/en/troubleshooting/faq.md b/content/en/advanced-reference/troubleshooting/faq.md
similarity index 100%
rename from content/en/troubleshooting/faq.md
rename to content/en/advanced-reference/troubleshooting/faq.md
diff --git a/content/en/troubleshooting/troubleshooting.md b/content/en/advanced-reference/troubleshooting/troubleshooting.md
similarity index 100%
rename from content/en/troubleshooting/troubleshooting.md
rename to content/en/advanced-reference/troubleshooting/troubleshooting.md
diff --git a/content/en/action-types/_index.md b/content/en/core-actions/_index.md
similarity index 100%
rename from content/en/action-types/_index.md
rename to content/en/core-actions/_index.md
diff --git a/content/en/core-actions/check.md b/content/en/core-actions/check.md
new file mode 100644
index 0000000..4d18cd9
--- /dev/null
+++ b/content/en/core-actions/check.md
@@ -0,0 +1,43 @@
+---
+title: Check
+description: Branch your logic based on specific criteria.
+weight: 20
+---
+
+# Check
+
+The **Check** block is the primary way to make decisions in your rule. It looks at your data and decides which path the rule should follow.
+
+## How it Works
+A Check block has two exits:
+- **True (Green)**: The path followed if the conditions are met.
+- **False (Red)**: The path followed if the conditions are NOT met.
+
+## Configuration
+
+### 1. Grouping Logic
+You can decide how multiple conditions work together:
+- **ALL**: Every condition must be true.
+- **ANY**: Only one of the conditions needs to be true.
+- **NONE**: None of the conditions can be true.
+
+### 2. Adding conditions
+Each condition requires:
+- **Field**: What you are checking (e.g., `doc.grand_total`).
+- **Operator**: The comparison (e.g., `is greater than`, `equals`, `contains`).
+- **Value**: What you are checking against (e.g., `5000`).
+
+### 3. Checking Lists (Child Tables)
+You can check if items in a list meet certain criteria. For example: "Check if **any** row in the Items table has a quantity greater than 100."
+
+## Common Examples
+- **High Value Check**: `doc.total_amount` is greater than `10000`.
+- **Status Check**: `doc.status` equals `Draft`.
+- **Customer Check**: `doc.customer_group` is in `[VIP, VVIP]`.
+
+---
+
+## Pro Tips
+- **Keep it Simple**: If your conditions are getting too complex, consider splitting them into two separate Check blocks.
+- **Visual Debugging**: Run a **Test Run** to see which way your Check block went. The path taken will be highlighted in green on the canvas.
+- **Stop if False**: If you don't connect anything to the **False** port, the rule will simply stop there if the condition isn't met.
diff --git a/content/en/core-actions/notify-action.md b/content/en/core-actions/notify-action.md
new file mode 100644
index 0000000..487ac50
--- /dev/null
+++ b/content/en/core-actions/notify-action.md
@@ -0,0 +1,38 @@
+---
+title: Notify
+description: Send alerts, emails, and messages to users and customers.
+weight: 40
+---
+
+# Notify
+
+The **Notify** block is used to send information. Whether it's a quick pop-up for the current user or an email to a customer, this block handles all outgoing communication.
+
+## Types of Notifications (Modes)
+
+### 1. Toast (Pop-up)
+A "Toast" is a small message that appears in the top-right corner of the user's screen. Use this for instant feedback.
+- **Best for**: Confirmations like "Record Updated!" or warnings like "Low Stock Detected."
+- **Note**: This only works for the user who is currently interacting with the system.
+
+### 2. Email
+Send a formatted email to one or more recipients.
+- **Recipients**: Can be a fixed email address or dynamic (e.g., `doc.contact_email`).
+- **Templates**: You can write your own message or use an existing Email Template.
+- **Attachments**: You can automatically attach a PDF of the current document (e.g., a PDF of the Sales Invoice).
+
+### 3. System Notification
+Creates a notification in the Frappe notification center (the bell icon).
+- **Best for**: Internal alerts for specific users or roles.
+
+## Dynamic Content
+You can include data from your document directly in your messages using curly braces.
+- **Subject**: `Order {{ doc.name }} has been shipped!`
+- **Message**: `Hello {{ doc.customer_name }}, your order is on its way.`
+
+---
+
+## Pro Tips
+- **Email Queue**: Emails sent via FlexiRule are added to the standard Frappe Email Queue. They usually send within a minute.
+- **Rich Text**: Emails support HTML, so you can add bold text, links, and tables to your messages.
+- **Test Runs**: When you test a rule, "Toast" notifications will actually appear in your browser, while "Emails" will show up in the test log instead of being sent to real people.
diff --git a/content/en/action-types/process.md b/content/en/core-actions/process.md
similarity index 100%
rename from content/en/action-types/process.md
rename to content/en/core-actions/process.md
diff --git a/content/en/core-actions/query-records.md b/content/en/core-actions/query-records.md
new file mode 100644
index 0000000..df60cfd
--- /dev/null
+++ b/content/en/core-actions/query-records.md
@@ -0,0 +1,37 @@
+---
+title: Query Records
+description: Search for data across your entire system.
+weight: 50
+---
+
+# Query Records
+
+The **Query Records** block allows your rule to look up information from other parts of the system. Use this when you need data that isn't on the document that triggered the rule.
+
+## Common Uses
+- **Find a Manager**: Look up the Manager's email for a specific department.
+- **Check History**: See if a customer has any other open orders.
+- **Bulk Action**: Find all overdue tasks to send a summary report.
+
+## How it Works
+
+### 1. What to Search For
+Pick the **DocType** (the type of record) you want to find (e.g., `Customer`, `User`, or `Project`).
+
+### 2. Filters
+Define your search criteria. This works just like the filters in a Frappe Report or List View.
+- **Field**: The field to check (e.g., `status`).
+- **Condition**: The comparison (e.g., `equals`).
+- **Value**: What to look for. This can be a fixed value or dynamic (e.g., `doc.department`).
+
+### 3. Save the Results
+You must give the result a name (a **Variable**) so you can use it in later steps.
+- **Query One**: Finds only the first matching record. Useful for looking up a single setting or person.
+- **Query Many**: Finds every record that matches your filters. This is usually followed by a **Repeat** block to process each result.
+
+---
+
+## Pro Tips
+- **Performance**: Always use filters. Searching for "all Sales Invoices" without a filter will slow down your rule if you have thousands of records.
+- **No Results**: If no records are found, the result variable will be empty. You can use a **Check** block after a query to see if anything was found before proceeding.
+- **Limit and Sort**: You can limit the number of results (e.g., "Find the top 5 most recent orders") and sort them by date or value.
diff --git a/content/en/core-actions/repeat.md b/content/en/core-actions/repeat.md
new file mode 100644
index 0000000..6f0e5f8
--- /dev/null
+++ b/content/en/core-actions/repeat.md
@@ -0,0 +1,35 @@
+---
+title: Repeat
+description: Perform actions multiple times, once for each item in a list.
+weight: 30
+---
+
+# Repeat
+
+The **Repeat** block (formerly *Loop*) allows you to run the same set of actions for every item in a list. This is perfect for processing child tables (like items in an order) or the results of a search.
+
+## How it Works
+
+1. **The List**: You pick a list of items (e.g., `doc.items` or the results of a "Query Records" block).
+2. **The Sequence**: You connect the actions you want to repeat. These actions will run over and over until every item in the list has been processed.
+3. **The Current Item**: For each "lap" of the repeat block, you have access to the specific item being handled right now.
+
+## Common Uses
+- **Update All Items**: Change the status or warehouse for every item in a Sales Order.
+- **Bulk Notifications**: Send an email for every overdue invoice found in a search.
+- **Calculations**: Sum up specific values from a list.
+
+## Configuration
+
+### 1. Source List
+Select the list you want to iterate through. This is usually a child table on your document or a list of records found by a search.
+
+### 2. Item Name (Variable)
+Give a name to the item currently being processed (e.g., `current_item`). You can then use this name in following blocks to access that specific record's data.
+
+---
+
+## Pro Tips
+- **Performance**: Try to filter your lists *before* they reach the Repeat block so you aren't processing more items than necessary.
+- **Visual Path**: During a **Test Run**, you can see the repeat block "pulse" as it iterates through items.
+- **Finished Path**: Once every item has been processed, the rule will continue from the "Finished" port of the Repeat block.
diff --git a/content/en/core-actions/set-value.md b/content/en/core-actions/set-value.md
new file mode 100644
index 0000000..a449ee0
--- /dev/null
+++ b/content/en/core-actions/set-value.md
@@ -0,0 +1,45 @@
+---
+title: Set Value
+description: Update document fields or store temporary information.
+weight: 10
+---
+
+# Set Value
+
+The **Set Value** block is used to change data. It is the primary way to update fields on your document or save information to use later in the rule.
+
+## Common Uses
+- **Update Status**: Change a Sales Order from `Draft` to `Open`.
+- **Calculations**: Calculate a discount and save it to a field.
+- **Store Data**: Save the result of a search (like a Manager's email) into a temporary variable to use in a later step.
+
+## How to Configure
+
+The Set Value block uses a simple table where each row represents one change.
+
+### 1. Target (Where to save)
+Choose where you want to save the data:
+- `doc.field_name`: This updates a field on the document that triggered the rule (e.g., `doc.status`).
+- `vars.my_variable`: This saves data into a temporary "bucket" that exists only while this rule is running. Use this for intermediate steps. {#context-variables-vars}
+
+### 2. Operator (How to change)
+- **Set**: Replaces the old value with a new one.
+- **Clear**: Empties the field.
+- **Increment / Decrement**: Adds or subtracts a number (great for counters or totals).
+- **Append**: Adds an item to a list.
+
+### 3. Value (The new data)
+You can enter a fixed value (like `100` or `Approved`) or use the **Selector** to pick data from:
+- Other fields on the document.
+- Results from previous blocks (like a Query).
+- Mathematical formulas.
+
+### 4. Only If (Conditional updates)
+You can add a condition to each row so that the update only happens if certain criteria are met (e.g., "Set status to VIP *only if* grand total is > 5000").
+
+---
+
+## Pro Tips
+- **Top to Bottom**: Updates happen in order from the top row to the bottom.
+- **Before vs After**: If you want to update fields on the current document, make sure your rule is set to trigger **Before Save**.
+- **Variables are Temporary**: Anything saved to `vars.` disappears once the rule finishes running. If you need to keep the data permanently, save it to a `doc.` field.
diff --git a/content/en/core-actions/start.md b/content/en/core-actions/start.md
new file mode 100644
index 0000000..ceb4e23
--- /dev/null
+++ b/content/en/core-actions/start.md
@@ -0,0 +1,21 @@
+---
+title: Start
+description: The entry point for every rule.
+weight: 5
+---
+
+# Start
+
+The **Start** block (formerly *Entry Action*) is the starting point for every rule. You cannot delete this block, and every rule must have exactly one.
+
+## What it Does
+The Start block doesn't perform a specific task like sending an email or updating a field. Instead, it serves as the connection point for the "Trigger" that started the rule.
+
+## Configuration
+In most cases, the Start block requires no configuration. It simply passes the document that triggered the rule (available as `doc`) into the next block in your flow.
+
+---
+
+## Pro Tips
+- **Trigger Info**: While the block itself is simple, remember that the data it carries depends on the **Trigger Event** you chose in the Rule dashboard (e.g., "Before Save" or "On Submit").
+- **Isolated Rules**: If you see the Start block but no lines coming out of it, your rule will never do anything! Always connect the Start block to at least one other action.
diff --git a/content/en/action-types/stop-error.md b/content/en/core-actions/stop-error.md
similarity index 100%
rename from content/en/action-types/stop-error.md
rename to content/en/core-actions/stop-error.md
diff --git a/content/en/action-types/sub-rule.md b/content/en/core-actions/sub-rule.md
similarity index 100%
rename from content/en/action-types/sub-rule.md
rename to content/en/core-actions/sub-rule.md
diff --git a/content/en/action-types/switch.md b/content/en/core-actions/switch.md
similarity index 100%
rename from content/en/action-types/switch.md
rename to content/en/core-actions/switch.md
diff --git a/content/en/core-actions/update-record.md b/content/en/core-actions/update-record.md
new file mode 100644
index 0000000..8d82a33
--- /dev/null
+++ b/content/en/core-actions/update-record.md
@@ -0,0 +1,28 @@
+---
+title: Update Record
+description: Create new records or update existing ones in the system.
+weight: 60
+---
+
+# Update Record
+
+While the **Set Value** block is used to update the *current* document, the **Update Record** block is used to create or modify *other* documents in the system.
+
+## Modes
+
+### 1. Create New
+Use this to automatically generate a new document.
+- **Example**: When a "Service Request" is approved, automatically create a "Task" for the technician.
+- **Mapping**: You can map fields from your current document to the new one (e.g., set the `customer` on the Task to be the same as the `customer` on the Request).
+
+### 2. Update Existing
+Use this to change data on a specific, existing document.
+- **Example**: When a "Delivery Note" is signed, update the related "Sales Order" status to "Delivered."
+- **Requirement**: You must specify which document to update, usually by providing its name or ID (which you might have found using a **Query Records** block).
+
+---
+
+## Pro Tips
+- **Automation**: This block is powerful for "Chain Reactions" where one action in the system automatically triggers several others.
+- **Validation**: FlexiRule will respect all standard Frappe permissions and validation rules when creating or updating records. If a field is mandatory in the target DocType, you must provide a value for it here.
+- **Results**: After creating a new record, the "Update Record" block returns the ID of the new document so you can use it in later steps.
diff --git a/content/en/action-types/wait.md b/content/en/core-actions/wait.md
similarity index 100%
rename from content/en/action-types/wait.md
rename to content/en/core-actions/wait.md
diff --git a/content/en/getting-started/_index.md b/content/en/getting-started/_index.md
index eb49b32..d656d07 100644
--- a/content/en/getting-started/_index.md
+++ b/content/en/getting-started/_index.md
@@ -1,5 +1,14 @@
---
title: Getting Started
-weight: 20
-description: A step-by-step guide for non-technical users to build their first automation.
+weight: 10
+description: Learn the fundamentals of FlexiRule and how to build your first automation.
---
+
+# Getting Started
+
+Welcome to FlexiRule! This section will help you understand the core concepts and get you up and running quickly.
+
+1. **[Introduction]({{< relref "introduction.md" >}})**: Understand the fundamental purpose of FlexiRule and the problems it solves.
+2. **[Quick Start]({{< relref "quick-start.md" >}})**: Build your first automation in under 5 minutes.
+
+For a deeper dive into the philosophy and technical architecture, check out the **[Advanced Reference]({{< relref "advanced-reference/" >}})** section.
diff --git a/content/en/introduction/what-is-flexirule.md b/content/en/getting-started/introduction.md
similarity index 55%
rename from content/en/introduction/what-is-flexirule.md
rename to content/en/getting-started/introduction.md
index b9d5b50..f7345d1 100644
--- a/content/en/introduction/what-is-flexirule.md
+++ b/content/en/getting-started/introduction.md
@@ -1,15 +1,13 @@
---
-title: What is FlexiRule?
+title: Introduction
weight: 10
description: A high-level overview of FlexiRule and its role in the Frappe ecosystem.
---
-# What is FlexiRule?
+# Introduction to FlexiRule
FlexiRule is a **Visual Rule Engineering & Orchestration Engine** built specifically for the Frappe Framework and ERPNext. It provides a visual, graph-based layer that allows you to design, execute, and manage complex business logic without writing scattered Python code.
-In modern enterprise systems, business logic often evolves into a fragmented web of Python hooks, server scripts, and custom app overrides. This "technical debt" makes execution order difficult to track, debugging nearly impossible, and system upgrades risky. FlexiRule changes this paradigm by centralizing logic into a visual, auditable orchestration layer.
-
## The Problem: "Hook Hell"
As ERPNext implementations grow, developers typically resort to:
@@ -25,10 +23,13 @@ FlexiRule sits as a middle layer between the Frappe Framework and your business
- **Deterministic**: You define the exact execution path.
- **Observable**: Every step is logged and traceable on the canvas.
-- **Safe**: Built-in validation, cycle detection, and sandboxing prevent system instability.
+- **Safe**: Built-in validation and cycle detection prevent system instability.
-## Role in the Ecosystem
+## Why Use FlexiRule?
-FlexiRule is not a replacement for Frappe; it is an enhancement. It leverages standard Frappe features—like DocTypes, Events, and Permissions—while providing a superior way to organize the logic that connects them.
+FlexiRule shifts the focus from **writing code** to **configuring business logic**, enabling your team to respond to changes with speed.
-Whether you are automating a simple notification or a multi-stage credit approval process, FlexiRule provides the tools to build it visually and manage it professionally.
+- **Business Agility**: Functional consultants can update rules instantly without developer deployments.
+- **Reduced Costs**: Lower skill ceiling for 80% of automations.
+- **Easier Upgrades**: Logic is separated from application code, making system upgrades safer.
+- **Full Visibility**: Execution logs show the exact path a document took on the canvas.
diff --git a/content/en/getting-started/quick-start.md b/content/en/getting-started/quick-start.md
index f5e4ff2..6a2fc5d 100644
--- a/content/en/getting-started/quick-start.md
+++ b/content/en/getting-started/quick-start.md
@@ -1,7 +1,7 @@
---
title: Quick Start
description: Build your first automation in under 5 minutes.
-weight: 10
+weight: 20
---
# Quick Start Guide
@@ -10,41 +10,41 @@ Ready to see FlexiRule in action? Follow this guide to build a simple automation
## 1. Create your First Rule
Go to **Rule List** and click **New**.
-- **Rule Name**: "High Value Alert"
-- **Document Type**: "Sales Invoice"
-- **Trigger Event**: "Before Save"
+- **Rule Name**: `High Value Alert`
+- **Document Type**: `Sales Invoice`
+- **Trigger Event**: `Before Save`
## 2. Open the Builder
-Click the **Open Rule Builder** button in the dashboard. You'll see a blank canvas with an **Entry Action**.
+Click the **Open Rule Builder** button. You'll see a blank canvas with a **Start** block.
-## 3. Add a Condition (Check)
-1. Hover over the **Entry Action** and click the **+** icon.
-2. Search for **Condition** and add it.
-3. In the config panel:
+## 3. Add a Check (Condition)
+1. Click the **+** icon on the **Start** block.
+2. Select **Check**.
+3. In the configuration panel:
- Click **Add Condition**.
- Select field: `grand_total`.
- Operator: `is greater than`.
- Value: `10000`.
## 4. Add a Notification
-1. Drag a line from the **True** (Green) port of your Condition.
+1. Drag a line from the **True** (Green) port of your Check block.
2. Select **Notify**.
-3. In the config panel:
- - **Mode**: "Toast".
- - **Message**: "💰 High value invoice detected! ID: {{ doc.name }}".
+3. In the configuration panel:
+ - **Mode**: `Toast`.
+ - **Message**: `💰 High value invoice detected! ID: {{ doc.name }}`.
## 5. Test it
-1. Click **Test Run**.
+1. Click **Test Run** in the top bar.
2. Pick an existing Sales Invoice with a total > 10,000.
3. Click **Run Test**.
-4. You should see a success toast and a green path on your canvas!
+4. You should see a success toast and the logic path highlighted in green on your canvas!
## 6. Go Live
Close the builder, set the Rule to **Enabled**, and click **Save**. You've just built your first FlexiRule!
---
-## Common Beginner Mistakes
-- **Forgetting to Enable**: A rule won't run automatically unless the "Enabled" checkbox is checked on the main Rule document.
-- **Wrong Trigger Event**: If you want to update a field on the document being saved, use "Before Save". If you use "After Save", the document is already in the database and your changes might not be persisted.
-- **Broken Connections**: Ensure every node in your logic is connected. An isolated node will never execute.
+### Pro Tips
+- **Always Enable**: A rule only runs automatically if the **Enabled** checkbox is checked.
+- **Visual Paths**: Use the execution logs to see exactly why a rule followed a specific path.
+- **Before vs After**: Use `Before Save` to modify fields on the current document, and `After Save` for actions that should happen after the record is finalized (like sending emails).
diff --git a/content/en/introduction/_index.md b/content/en/introduction/_index.md
deleted file mode 100644
index 75b5a0c..0000000
--- a/content/en/introduction/_index.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: Introduction
-weight: 10
-description: Welcome to FlexiRule. Learn about the core philosophy and why it is the preferred solution for Frappe automation.
----
-
-Welcome to the FlexiRule documentation. This section provides a comprehensive overview of the platform's vision, architecture, and core capabilities.
-
-Whether you are a functional consultant looking to automate business processes or a developer seeking to reduce technical debt, these pages will provide the foundation you need to succeed with FlexiRule.
-
-### Start Your Journey
-
-1. **{{< relref "what-is-flexirule.md" >}}**: Understand the fundamental purpose of FlexiRule and the problems it solves.
-2. **{{< relref "why-flexirule.md" >}}**: Explore the business value and agility provided by visual orchestration.
-3. **{{< relref "erpnext-need.md" >}}**: Learn how FlexiRule complements standard ERPNext features.
-4. **{{< relref "do-i-need-flexirule.md" >}}**: Determine if FlexiRule is the right fit for your organization.
-5. **{{< relref "better-than-hard-coded.md" >}}**: A detailed comparison with traditional hard-coded customizations.
-6. **{{< relref "performance.md" >}}**: Deep dive into the architectural optimizations powering the engine.
-7. **{{< relref "core-concepts.md" >}}**: Master the fundamental building blocks of the ecosystem.
-8. **{{< relref "architecture.md" >}}**: A technical overview of the system stack and execution pipeline.
-9. **{{< relref "key-capabilities.md" >}}**: Functional highlights and major features of the platform.
diff --git a/content/en/introduction/core-concepts.md b/content/en/introduction/core-concepts.md
deleted file mode 100644
index 87e2dc2..0000000
--- a/content/en/introduction/core-concepts.md
+++ /dev/null
@@ -1,172 +0,0 @@
----
-title: Core Concepts
-weight: 70
-description: The fundamental building blocks of the FlexiRule ecosystem.
----
-
-# Core Concepts
-
-FlexiRule is built from a small set of reusable concepts. A rule is not a single script; it is a flow of blocks that read data, make decisions, and perform actions. Understanding these building blocks will help you design, read, and troubleshoot rules, and each concept will later have its own dedicated page for deeper explanation.
-
-## How a rule runs
-
-```text
-Business Event
- │
- ▼
- Trigger
- │
- ▼
- Rule
- │
- ▼
-Execution Context
- │
- ▼
- Blocks
- │
- ▼
-Queries, Value Resolvers, and Logical Commands
- │
- ▼
-Execution Result
-```
-
-In practice, a business event starts the process, a trigger decides whether the rule should run, the rule creates an execution context, and the blocks inside the rule use queries, values, and logic to produce the final result.
-
----
-
-## 1. Rule
-
-A **Rule** is the top-level automation definition in FlexiRule, and it exists so business behavior can be modeled in one place instead of being scattered across hard-coded application logic; it interacts with the trigger that starts execution, the execution context that carries runtime data, and the blocks that perform the actual work, and for example a rule can automatically approve a Sales Order when the total amount is below a configured limit and the customer is in good standing.
-
----
-
-## 2. Trigger
-
-A **Trigger** is the entry point that starts a rule, and it exists so FlexiRule only evaluates automation when the correct business event happens instead of running continuously; it interacts with the rule by deciding whether execution should begin, and if the trigger matches then the execution context is created and the rule continues, for example a trigger can run when a Purchase Invoice is submitted or on a nightly schedule to check overdue documents.
-
----
-
-## 3. Execution Context
-
-The **Execution Context** is the runtime memory available while a rule is running, and it exists so blocks can share data and reuse values during execution without losing state between steps; it interacts with the rule, blocks, value resolvers, and logical commands by holding the current document as `doc`, the previous state as `old_doc` when available, and custom runtime values in `vars`, and for example a customer credit check rule can store the calculated credit limit in `vars.credit_limit` and use it later in the same flow.
-
----
-
-## 4. Block (Rule Action)
-
-A **Block** is one node in the visual rule canvas, and it exists so automation can be built as a sequence of small, understandable steps instead of one large script; it interacts with the rule as a contained step, uses an action type to determine what it does, reads from and writes to the execution context, and may branch the flow based on a condition, for example one block may fetch related records, another may check whether a condition is true, and a third may send a notification.
-
----
-
-## 5. Action Type
-
-An **Action Type** defines what a block actually does, and it exists so different automation steps can perform different kinds of work while still fitting into the same visual rule structure; it interacts with the block as the behavior behind it and often uses value resolvers, queries, and logical commands to complete its task, and for example action types may retrieve data, set values, send notifications, run reusable logic, or evaluate decisions.
-
----
-
-## 6. Query Records
-
-**Query Records** is an action type used to fetch full records from a DocType, and it exists so a rule can inspect related documents before deciding what to do next; it interacts with the execution context by reading filter values from it and returning matching documents that can be stored in `vars` or used by later blocks, and for example before approving a Sales Order the rule can query all open invoices for the same customer to check whether there are overdue payments.
-
----
-
-## 7. Query List
-
-**Query List** is an action type used to fetch a lightweight list of values, and it exists so a rule can work with only the small amount of data it needs instead of loading full records; it interacts with the execution context by reading filters and field selections from it and returning a compact result that can be used in conditions, notifications, or assignments, and for example a rule can get the list of item codes from a Purchase Order to check whether any restricted items are included.
-
----
-
-## 8. Set Value
-
-**Set Value** is an action type used to assign a value to a field or variable, and it exists so rules can calculate, update, or overwrite values as part of automation; it interacts with the execution context by usually using a value resolver to calculate the final value and then writing the result into `doc` or `vars`, and for example a rule can set `doc.approval_status` to `Approved` when the rule conditions are satisfied.
-
----
-
-## 9. Notify
-
-**Notify** is an action type used to send messages or alerts, and it exists so automation can inform the right people at the right time instead of only changing data; it interacts with the execution context by using values from it and often combining them with resolved values from value resolvers, and for example a rule can send an email to the finance team when a Purchase Invoice exceeds the approval threshold.
-
----
-
-## 10. Process
-
-**Process** is an action type used to run reusable logic, and it exists so business logic that is needed in multiple rules can be centralized instead of duplicated; it interacts with the execution context by receiving data from it, calling internal logic or a reusable module, and returning results that later blocks can use, and for example a rule can run a reusable stock validation process before confirming a Sales Order.
-
----
-
-## 11. Value Resolver
-
-A **Value Resolver** is the mechanism that turns a dynamic expression into a real value at runtime, and it exists so rules can work with values that are not known until execution time; it interacts with the execution context by reading from `doc`, `old_doc`, `vars`, or query results and is used by Set Value, Notify, Query Records, Query List, and Condition blocks, and for example it can resolve `doc.grand_total`, `vars.credit_limit`, or a calculated discount before comparing values or updating a field.
-
----
-
-## 12. Logical Command for Frontend FlexValue Control
-
-A **Logical Command** is a decision or comparison primitive used inside rule logic, and it exists so rules have a structured way to evaluate business decisions such as equals, not equals, greater than, less than, contains, AND, OR, and NOT; it interacts with value resolvers and condition blocks by determining whether the rule continues down one path or another, and for example it can check whether `doc.grand_total > vars.credit_limit AND doc.customer_status == "Active"` before allowing the rule to continue.
-
----
-
-## 13. Trigger Condition
-
-A **Trigger Condition** is a pre-check attached to the trigger itself, and it exists so FlexiRule can decide very early whether a rule is worth loading and executing at all; it interacts with the trigger rather than the main rule flow, but it still uses the same Condition Builder and the same logical building blocks to evaluate data, and for example a trigger condition can prevent a Sales Order rule from running unless the document belongs to a specific company, a specific customer group, or a specific workflow state.
-
-This concept is different from a normal **Condition** block inside the rule flow:
-
-* A **Trigger Condition** decides whether the rule should start.
-* A **Condition** block decides what should happen after the rule has already started.
-
-They may look similar because both use the Condition Builder, but they serve different purposes. The trigger condition is a fast gate at the entry point, while the condition block is part of the actual execution path inside the rule.
-
----
-
-## 14. Condition and Branching
-
-A **Condition** block uses logical commands to choose the next path in the rule, and it exists so business processes can follow different outcomes depending on the data; it interacts with logical commands, the execution context, and the next block in the flow by evaluating to true or false and deciding which branch should execute, and for example if a Sales Order total is below the approval limit the rule can continue to approval, otherwise it can send the document for manager review.
-
----
-
-## 15. Variables
-
-**Variables** are custom values stored during rule execution, and they exist so blocks can share intermediate results without changing the document immediately; they interact with the execution context through `vars`, can be created or updated by one block, and can then be read by later blocks together with value resolvers and logical commands, and for example a rule can store `vars.discount_rate = 10` after a pricing check and reuse it in a notification and a field update.
-
----
-
-## 16. Lifecycle States
-
-Rules move through lifecycle states to control how they are used, and these states exist so live business logic can be managed safely without accidental changes; they interact with the rule by controlling whether it can be edited or executed, where Draft means the rule can be edited and tested but does not run automatically, Active means it is live and can be triggered by the system, Disabled means it is temporarily turned off without being deleted, and Archived means it is retired and kept for historical reference.
-
----
-
-## 17. Versioning (Amending)
-
-**Versioning**, also called **Amending**, is the safe way to update a live rule, and it exists so active business logic is never edited directly while it is running in production; it interacts with lifecycle states by creating a new Draft version from an Active rule, allowing the current live version to continue running while the new version is edited and tested, and for example if the approval threshold for a Purchase Invoice changes you can amend the active rule, update the draft, test it, and then activate the new version.
-
----
-
-## Summary Table
-
-| Concept | Purpose | Typical Questions |
-| --------------------- | --------------------------------------- | ----------------------------------------------------------- |
-| Rule | Defines a complete automation | What should happen? |
-| Trigger | Starts rule execution | When should it run? |
-| Execution Context | Holds runtime data | What data is available now? |
-| Block (Rule Action) | Represents one step in the flow | What should happen next? |
-| Action Type | Defines the behavior of a block | Is this a query, value update, notification, or process? |
-| Query Records | Fetches full documents | Which records match these filters? |
-| Query List | Fetches a lightweight list of values | Which values do I need? |
-| Set Value | Updates a field or variable | What value should be written? |
-| Notify | Sends alerts or messages | Who should be informed? |
-| Process | Runs reusable logic | Which shared logic should be executed? |
-| Value Resolver | Resolves dynamic values at runtime | What is the actual value right now? |
-| Logical Command | Evaluates comparisons and boolean logic | Is this condition true or false? |
-| Trigger Condition | Decides whether the rule should start | Should this trigger load the rule at all? |
-| Condition | Chooses the next branch | Which path should run? |
-| Variables | Stores temporary runtime values | What data should be reused later? |
-| Lifecycle States | Controls rule availability | Is the rule draft, active, disabled, or archived? |
-| Versioning (Amending) | Safely updates live rules | How do I change a running rule without breaking production? |
-
----
-
-Understanding these concepts gives you the foundation for everything else in FlexiRule. Once you know how rules, triggers, blocks, queries, values, and logic work together, the rest of the documentation becomes much easier to follow.
diff --git a/content/en/introduction/key-capabilities.md b/content/en/introduction/key-capabilities.md
deleted file mode 100644
index 467c517..0000000
--- a/content/en/introduction/key-capabilities.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: Key Capabilities
-weight: 90
-description: A summary of the major features and functional highlights of FlexiRule.
----
-
-# Key Capabilities
-
-FlexiRule combines the power of visual programming with enterprise-grade governance. Here are the major features that define the platform:
-
-## Visual Rule Builder
-- **Vue 3 Interface**: A modern, responsive canvas for designing complex logic.
-- **Drag-and-Drop**: Easily add and connect logic blocks.
-- **Real-time Validation**: The builder alerts you to missing configuration or broken connections as you work.
-
-## Advanced Logic Control
-- **Nested Conditions**: Build multi-level `if-then-else` logic visually.
-- **Switch Blocks**: Handle multiple branching scenarios from a single node.
-- **Sub-Rules**: Call one rule from another to maintain modularity and reuse logic.
-
-## Safety and Governance
-- **Cycle Detection**: Native protection against infinite loops in the graph.
-- **Sandboxed Environment**: Rules are executed in a safe container that prevents unauthorized database modifications.
-- **Role-Based Permissions**: Control who can view, edit, or execute specific rules.
-
-## High-Performance Engine
-- **Condition Compilation**: Logic is pre-compiled for near-zero execution overhead.
-- **Layered Caching**: Multi-level cache (Redis + Local) for lightning-fast rule lookups.
-- **Asynchronous Processing**: Offload heavy tasks to background workers without slowing down the user.
-
-## Observability
-- **Execution Logs**: Detailed audit trail for every rule run.
-- **Visual Path Trace**: See exactly which path a document took through your logic graph.
-- **Debug Mode**: Enable enhanced logging for complex troubleshooting.
-
-## Developer Friendly
-- **JSON Schema Driven**: Configuration forms for custom logic are auto-generated.
-- **Extensible Actions**: Register custom Python logic as new block types.
-- **Git Friendly**: Rules are stored as DocTypes, making them easy to migrate between environments.
diff --git a/content/en/rule-builder/adding-managing-actions.md b/content/en/rule-builder/adding-managing-actions.md
deleted file mode 100644
index 428a1a6..0000000
--- a/content/en/rule-builder/adding-managing-actions.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-title: Adding and Managing Actions
-description: Learn how to use the Action Zone to build your rule logic.
-weight: 20
----
-
-# Adding and Managing Actions
-
-Building logic in FlexiRule is centered around adding and connecting "Action" nodes.
-
-## The Action Zone
-
-The **Action Zone** is the primary way to add new logic. It provides a searchable menu of all available actions.
-
-{{< video src="/images/add-action-from-action-zone.webm" autoplay="true" loop="true" muted="true" >}}
-
-### How to Add an Action
-1. **Hover**: Hover your mouse over any connection line or empty space on the canvas.
-2. **Trigger**: Click the `+` icon that appears.
-3. **Search & Select**: Browse categories or type to find the action you need (e.g., "Email" or "Update Record").
-4. **Insert**: The new node is automatically inserted and connected into your flow.
-
-## Managing Connections
-
-### Reconnecting Nodes
-If you delete a node between two others, FlexiRule intelligently heals the connection to maintain your logic flow.
-
-{{< video src="/images/remove-a-node-will-dynamically-reconnet-nodes.webm" >}}
-
-### Manual Connections
-You can also manually connect nodes by dragging from the output handle of one node to the input handle of another.
-
-## Intelligent Configuration
-
-When you select an action, a configuration panel opens on the right.
-
-- **Smart Pickers**: Field pickers only show variables that are actually available at that point in the rule.
-- **Validation**: The builder alerts you if required fields are missing before you save.
diff --git a/content/en/rule-builder/_index.md b/content/en/using-the-builder/_index.md
similarity index 100%
rename from content/en/rule-builder/_index.md
rename to content/en/using-the-builder/_index.md
diff --git a/content/en/using-the-builder/adding-managing-actions.md b/content/en/using-the-builder/adding-managing-actions.md
new file mode 100644
index 0000000..7b33074
--- /dev/null
+++ b/content/en/using-the-builder/adding-managing-actions.md
@@ -0,0 +1,43 @@
+---
+title: Adding and Managing Actions
+description: Learn how to use the Action Zone to build your rule logic.
+weight: 20
+---
+
+# Adding and Managing Actions
+
+Building logic in FlexiRule is centered around adding and connecting functional **Blocks**.
+
+## The Action Zone
+
+The **Action Zone** is the primary way to add new logic. It provides a searchable menu of all available actions.
+
+{{< video src="/images/add-action-from-action-zone.webm" autoplay="true" loop="true" muted="true" >}}
+
+### How to Add a Block
+1. **Hover**: Hover your mouse over any connection line or an output port (the colored circles) of an existing block.
+2. **Trigger**: Click the `+` icon that appears.
+3. **Search & Select**: Browse categories or type to find the block you need (e.g., "Notify" or "Update Record").
+4. **Insert**: The new block is automatically inserted and connected into your flow.
+
+## Managing Connections
+
+### Connecting Blocks
+Connections define the order in which your logic executes.
+- **Drag and Drop**: Click an output port of a block and drag a line to the input port of another block.
+- **Color Coding**:
+ - **Grey**: Standard execution path.
+ - **Green (True)**: The path taken if a condition is met.
+ - **Red (False)**: The path taken if a condition is NOT met.
+
+### Reconnecting and Deleting
+If you delete a block between two others, FlexiRule intelligently "heals" the connection by linking the previous block directly to the next one, ensuring your logic flow isn't broken.
+
+{{< video src="/images/remove-a-node-will-dynamically-reconnet-nodes.webm" >}}
+
+## Intelligent Configuration
+
+When you select a block, a configuration panel opens on the right.
+
+- **Dynamic Pickers**: Field selectors only show data and variables that are actually available at that specific point in the rule.
+- **Real-time Validation**: The builder alerts you if required fields are missing or if there are logic errors (like a loop) before you save.
diff --git a/content/en/rule-builder/canvas-navigation.md b/content/en/using-the-builder/canvas-navigation.md
similarity index 53%
rename from content/en/rule-builder/canvas-navigation.md
rename to content/en/using-the-builder/canvas-navigation.md
index bb87973..625ebc8 100644
--- a/content/en/rule-builder/canvas-navigation.md
+++ b/content/en/using-the-builder/canvas-navigation.md
@@ -10,21 +10,24 @@ aliases:
The Rule Builder is your visual workspace for designing business logic. It provides a drag-and-drop canvas where you can orchestrate workflows while maintaining full visibility into the execution flow.
-
-
## Core Canvas Interactions
### Moving and Zooming
- **Pan**: Click and drag any empty space on the canvas to move around.
- **Zoom**: Use your mouse wheel or the zoom controls in the corner to adjust the view.
-### Working with Nodes
-- **Select**: Click a node to select it and open its configuration panel.
-- **Move**: Drag a node to reposition it.
-- **Delete**: Select a node and press `Backspace` or `Delete`. The builder will automatically attempt to reconnect the remaining nodes.
+### Working with Blocks
+In FlexiRule, every step in your logic is represented by a **Block**.
+- **Select**: Click a block to open its configuration panel on the right.
+- **Move**: Click and drag a block to reposition it.
+- **Delete**: Select a block and press `Backspace` or `Delete`. The builder will automatically attempt to reconnect the remaining blocks.
+
+### The Action Zone
+The **Action Zone** is the interactive space around blocks and connection points.
+- **Quick Add**: Hover over a connection line or a port (the circles on the sides of a block) to see the `+` icon. Clicking this opens the Action Menu to insert a new block at that exact location.
### Bulk Actions
-You can select multiple nodes by holding `Shift` and dragging a selection box. This allows you to move or copy groups of logic at once.
+You can select multiple blocks by holding `Shift` and dragging a selection box. This allows you to move or copy groups of logic at once.
{{< video src="/images/shift-click-nodes-to-copy.webm" >}}
@@ -33,12 +36,12 @@ You can select multiple nodes by holding `Shift` and dragging a selection box. T
The Rule Builder includes built-in tools to test your rules in real-time.
### Visual Execution Path
-When you run a test, the builder highlights the exact path taken during execution, showing you exactly which nodes were triggered.
+When you run a test, the builder highlights the exact path taken during execution in green, showing you exactly which blocks were triggered.
{{< video src="/images/debug-rule-view-execution-path.webm" >}}
### Inspecting Results
-You can click on any node after a test run to see its specific results, including modified variables and return values.
+You can click on any block after a test run to see its specific results, including modified variables and data returned by that step.
diff --git a/content/en/rule-builder/lifecycle-execution.md b/content/en/using-the-builder/lifecycle-execution.md
similarity index 100%
rename from content/en/rule-builder/lifecycle-execution.md
rename to content/en/using-the-builder/lifecycle-execution.md
diff --git a/content/en/tutorials/_index.md b/content/en/using-the-builder/tutorials/_index.md
similarity index 100%
rename from content/en/tutorials/_index.md
rename to content/en/using-the-builder/tutorials/_index.md
diff --git a/content/en/tutorials/automatic-assignment.md b/content/en/using-the-builder/tutorials/automatic-assignment.md
similarity index 100%
rename from content/en/tutorials/automatic-assignment.md
rename to content/en/using-the-builder/tutorials/automatic-assignment.md
diff --git a/content/en/tutorials/manager-approval.md b/content/en/using-the-builder/tutorials/manager-approval.md
similarity index 100%
rename from content/en/tutorials/manager-approval.md
rename to content/en/using-the-builder/tutorials/manager-approval.md
diff --git a/content/en/tutorials/send-email-sales-order.md b/content/en/using-the-builder/tutorials/send-email-sales-order.md
similarity index 100%
rename from content/en/tutorials/send-email-sales-order.md
rename to content/en/using-the-builder/tutorials/send-email-sales-order.md