chore: update README

Author: lanycrost

README.md

@@ -1,47 +1,71 @@
-# 🤖 bobrapet - Kubernetes-Native AI Workflow Engine
+# 🤖 bobrapet - A Declarative, Kubernetes-Native AI Workflow Engine
 
-> **Declarative, Composable, Cloud-Native AI Workflows**
-
-Bobrapet is a Kubernetes-native workflow engine designed specifically for AI and data processing workloads. It uses Custom Resource Definitions (CRDs) to define, execute, and manage complex, multi-step workflows directly within your Kubernetes cluster.
+Bobrapet is a powerful, cloud-native workflow engine for orchestrating complex AI and data processing pipelines on Kubernetes. It leverages the declarative power of Custom Resource Definitions (CRDs) to let you define, manage, and execute multi-step, event-driven workflows with unparalleled flexibility and control.
 
 ## 🌟 Key Features
 
-- **Declarative Workflows**: Define complex pipelines as Kubernetes resources (`Story`).
-- **Composable Components**: Package reusable tasks as `Engrams`, backed by versioned, cluster-scoped `EngramTemplates`.
-- **Flexible Triggers**: Initiate workflows from events using `Impulses`, backed by `ImpulseTemplates`.
-- **Full Observability**: Track the state of every workflow (`StoryRun`) and each individual step (`StepRun`).
-- **Cross-Namespace Support**: Orchestrate workflows that span multiple Kubernetes namespaces, enabling multi-tenant and shared service models.
+- **Declarative & GitOps-Friendly**: Define your entire workflow as a `Story` resource. Treat your AI pipelines as code and manage them through GitOps.
+- **Advanced DAG Orchestration**: A sophisticated Directed Acyclic Graph (DAG) engine orchestrates your steps, enabling complex dependencies and execution flows.
+- **Parallel-by-Default Execution**: For maximum performance, independent steps run in parallel automatically. Use the `needs` keyword to define an explicit execution order.
+- **Dynamic Control Flow**: Implement powerful logic directly in your workflows with built-in primitives and Common Expression Language (CEL) for `if` conditions.
+- **Composable & Reusable Components**: Package reusable tasks as `Engrams`, backed by versioned, cluster-scoped `EngramTemplates` for consistency.
+- **Flexible Streaming Strategies**: Optimize for long-running tasks with `PerStory` (always-on) or `PerStoryRun` (on-demand) resource allocation.
+- **Cross-Namespace Orchestration**: Securely reference resources and orchestrate workflows across multiple Kubernetes namespaces.
+- **Event-Driven Triggers**: Initiate workflows from various event sources using `Impulses`.
+
+## 🏗️ Architecture
+
+The `bobrapet` operator is engineered for robustness and maintainability, following best practices for Kubernetes controller design. The core `StoryRun` controller, for example, is built on a modular, sub-reconciler pattern:
+
+- **Main Controller**: Acts as a lean, high-level orchestrator.
+- **RBAC Manager**: Manages all RBAC-related resources (`ServiceAccount`, `Role`, `RoleBinding`).
+- **DAG Reconciler**: Contains the entire workflow state machine, handling state synchronization, dependency analysis, and scheduling.
+- **Step Executor**: Manages the specific logic for launching different types of steps (`engram`, `executeStory`, etc.).
+
+This clean separation of concerns makes the operator highly scalable, testable, and easy to extend.
 
 ## 📚 Core Concepts
 
 - **`Story`**: The top-level definition of a workflow, composed of steps.
 - **`Engram`**: A configured, runnable instance of a component (a "worker").
 - **`Impulse`**: A trigger that creates workflow instances based on external events.
 - **`StoryRun`**: An instance of an executing `Story`.
-- **`StepRun`**: An instance of a single step executing within a `StoryRun`.
+- **`StepRun`**: An instance of a single `engram` step executing within a `StoryRun`.
 - **`EngramTemplate` & `ImpulseTemplate`**: Reusable, cluster-scoped definitions for `Engrams` and `Impulses`.
 
+## 🧰 Workflow Primitives
+
+Beyond running custom `Engrams`, `Story` resources can use a rich set of built-in primitives for advanced control flow:
+
+- **`executeStory`**: Run another `Story` as a sub-workflow, either synchronously or asynchronously.
+- **`if` condition**: Use CEL expressions to conditionally execute steps.
+- **`switch`**: Implement multi-way branching (like a switch/case statement).
+- **`loop`**: Iterate over arrays or repeat actions.
+- **`parallel`**: Group steps to be executed concurrently.
+- And many more for flow control, data transformation, and state management (`sleep`, `stop`, `filter`, `transform`, `setData`, etc.).
+
 ## 🚀 Quick Start
 
 ### Prerequisites
-- A running Kubernetes cluster (e.g., KinD, Minikube, or a cloud provider).
+- A running Kubernetes cluster (e.g., KinD, Minikube).
 - `kubectl` configured to access your cluster.
 
 ### 1. Install the Operator
 
-First, install the Custom Resource Definitions (CRDs) that define the `bobrapet` resources:
+First, install the Custom Resource Definitions (CRDs):
 ```bash
 make install
 ```
 
 Next, deploy the operator controller to your cluster:
 ```bash
-make deploy
+make deploy IMG=<your-repo>/bobrapet:latest
 ```
+*(Replace `<your-repo>` with your container registry)*
 
 ### 2. Deploy a Sample Workflow
 
-This example defines a two-step workflow that fetches content from a URL and uses an AI model to summarize it.
+The following example defines a two-step workflow that fetches content from a URL and uses an AI model to summarize it. Notice how the `summarize` step implicitly depends on the output of the `fetch-content` step.
 
 Apply the sample manifests, which include the necessary `EngramTemplates`, `Engrams`, and the `Story` definition:
 ```bash
@@ -51,11 +75,11 @@ kubectl apply -k config/samples
 This creates:
 - An `Engram` named `http-request-engram` to fetch web content.
 - An `Engram` named `openai-summarizer-engram` to summarize text.
-- A `Story` named `summarize-website-story` that chains them together.
+- A `Story` named `summarize-website-story` that defines the workflow.
 
 ### 3. Run the Workflow
 
-Create a `StoryRun` resource to trigger the workflow with a specific URL:
+Create a `StoryRun` resource to trigger the workflow. This `StoryRun` provides the initial input `url` required by the `Story`.
 
 ```yaml
 # ./run.yaml
@@ -64,10 +88,10 @@ kind: StoryRun
 metadata:
   name: summarize-k8s-docs
 spec:
-  inputs:
-    url: https://kubernetes.io/docs/concepts/overview/
   storyRef:
     name: summarize-website-story
+  inputs:
+    url: https://kubernetes.io/docs/concepts/overview/
 ```
 
 Apply it:
@@ -77,7 +101,7 @@ kubectl apply -f ./run.yaml
 
 ### 4. Observe the Results
 
-You can monitor the execution of the workflow by checking the `StoryRun` and its child `StepRuns`.
+Monitor the execution of the workflow by checking the `StoryRun` and its child `StepRuns`.
 
 ```bash
 # Check the overall status of the workflow
@@ -87,18 +111,16 @@ kubectl get storyrun summarize-k8s-docs -o yaml
 kubectl get stepruns -l bubu.sh/storyrun=summarize-k8s-docs
 ```
 
-## 🛠️ Development
-
-To develop the operator locally:
+## 🛠️ Local Development
 
 1.  **Clone the repository:**
     ```bash
     git clone https://github.com/bubustack/bobrapet.git
     cd bobrapet
     ```
 
-2.  **Run the controller:**
-    This command will run the operator on your local machine, using your local `kubeconfig` to communicate with the cluster.
+2.  **Run the controller locally:**
+    This command runs the operator on your machine, using your local `kubeconfig` to communicate with the cluster. This is great for rapid development and debugging.
     ```bash
     make run
     ```