From a7f4e8f104fc77fc0d33829babdf515e4d87fa6e Mon Sep 17 00:00:00 2001
From: Seva Kaloshin <vsevolod.kaloshin@gmail.com>
Date: Tue, 8 Jul 2025 11:08:09 +0200
Subject: [PATCH 1/4] make human readable

---
 README.md | 496 +++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 397 insertions(+), 99 deletions(-)

diff --git a/README.md b/README.md
index 2189b20b..fcf926cd 100644
--- a/README.md
+++ b/README.md
@@ -1,169 +1,467 @@
 # Cadence Samples ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/uber-common/cadence-samples/build.yml)
 
-These are some samples to demostrate various capabilities of Cadence client and server.  You can learn more about cadence at:
-* Cadence Server: https://github.com/cadence-workflow/cadence
-* Cadence Client: https://github.com/cadence-workflow/cadence-go-client
+Welcome to the Cadence Samples repository! This collection demonstrates the powerful capabilities of Cadence workflow orchestration through practical, real-world examples. Whether you're new to Cadence or looking to implement specific patterns, these samples will help you understand how to build reliable, scalable, and maintainable workflow applications.
 
-## Prerequisite for running samples
+## What is Cadence?
 
-Run Cadence server:
+Cadence is a distributed, scalable, durable, and highly available orchestration engine that helps developers build reliable applications. It provides:
+
+- **Reliability**: Automatic retry mechanisms, error handling, and fault tolerance
+- **Scalability**: Distributed execution across multiple workers
+- **Durability**: Persistent workflow state that survives failures
+- **Observability**: Built-in monitoring, tracing, and querying capabilities
+
+Learn more about Cadence at:
+- [Documentation](https://cadenceworkflow.io)
+- [Cadence Server](https://github.com/cadence-workflow/cadence)
+- [Cadence Go Client](https://github.com/cadence-workflow/cadence-go-client)
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+1. **Clone the Repository**:
+```bash
+git clone https://github.com/uber-common/cadence-samples.git && cd cadence-samples
 ```
-curl -LO https://raw.githubusercontent.com/cadence-workflow/cadence/refs/heads/master/docker/docker-compose.yml
-docker-compose up
+
+2. **Start Cadence Server**:
+```bash
+curl -LO https://raw.githubusercontent.com/cadence-workflow/cadence/refs/heads/master/docker/docker-compose.yml && docker-compose up --wait
 ```
 
+This downloads and starts all required dependencies including Cadence server, database, and [Cadence Web UI](https://github.com/uber/cadence-web). You can view your sample workflows at [http://localhost:8088](http://localhost:8088).
 
-## Steps to run samples
-### Build Samples
-```
+3. **Build All Samples**:
+```bash
 make
 ```
 
-### Run HelloWorld Sample
+## 📚 Sample Categories
 
-* Start workers for helloworld workflow and activities
-```
-./bin/helloworld -m worker
-```
+### 🎯 **Getting Started Examples**
 
-* Start workflow execution for helloworld workflow
-```
-./bin/helloworld -m trigger
+#### [Hello World](cmd/samples/recipes/helloworld/)
+* **Shows**: Basic Cadence workflow concepts and activity execution.
+* **What it does**: Executes a single activity that returns a greeting message.
+* **Real-world use case**: Foundation for understanding workflow structure, activity execution, and basic error handling.
+* **Key concepts**: Workflow definition, activity execution, error handling, worker setup.
+
+```bash
+./bin/helloworld -m worker    # Start worker
+./bin/helloworld -m trigger   # Execute workflow
 ```
 
-### Commands to run other samples
+#### [Greetings](cmd/samples/recipes/greetings/)
+* **Shows**: Sequential activity execution and result passing between activities.
+* **What it does**: Executes three activities in sequence: get greeting, get name, then combine them.
+* **Real-world use case**: Multi-step processes like user registration, order processing, or data transformation pipelines.
+* **Key concepts**: Sequential execution, activity chaining, result passing between activities.
 
-#### cron
+```bash
+./bin/greetings -m worker
+./bin/greetings -m trigger
 ```
+
+### ⏰ **Scheduling & Timing Examples**
+
+#### [Cron](cmd/samples/cron/)
+* **Shows**: Automated recurring tasks and cron scheduling.
+* **What it does**: Executes a workflow based on cron expressions (e.g., every minute, daily at 2 AM).
+* **Real-world use case**: Data backups, report generation, system maintenance, periodic data synchronization.
+* **Key concepts**: Cron scheduling, workflow persistence, time-based execution.
+
+```bash
 ./bin/cron -m worker
-```
-Start workflow with cron expression scheduled to run every minute.
-```
-./bin/cron -m trigger -cron "* * * * *"
+./bin/cron -m trigger -cron "* * * * *"  # Run every minute
 ```
 
-#### dsl
-```
-./bin/dsl -m worker
-```
-```
-./bin/dsl -m trigger -dslConfig cmd/samples/dsl/workflow1.yaml
-./bin/dsl -m trigger -dslConfig cmd/samples/dsl/workflow2.yaml
+#### [Timer](cmd/samples/recipes/timer/)
+* **Shows**: Timeout and delay handling with parallel execution.
+* **What it does**: Starts a long-running process and sends a notification if it takes too long.
+* **Real-world use case**: Order processing with SLA monitoring, payment processing with timeout alerts, API calls with fallback mechanisms.
+* **Key concepts**: Timer creation, timeout handling, parallel execution with cancellation.
+
+```bash
+./bin/timer -m worker
+./bin/timer -m trigger
 ```
 
-#### expense
-See more details in https://github.com/uber-common/cadence-samples/blob/master/cmd/samples/expense/README.md
+#### [Delay Start](cmd/samples/recipes/delaystart/)
+* **Shows**: Deferred execution and delayed workflow execution.
+* **What it does**: Waits for a specified duration before executing the main workflow logic.
+* **Real-world use case**: Scheduled maintenance windows, delayed notifications, batch processing at specific times.
+* **Key concepts**: Delayed execution, time-based workflow scheduling.
 
-#### fileprocessing
-```
-./bin/fileprocessing -m worker
-```
-```
-./bin/fileprocessing -m trigger
+```bash
+./bin/delaystart -m worker
+./bin/delaystart -m trigger
 ```
 
-#### recipes/branch
-```
+### 🔄 **Parallel Execution Examples**
+
+#### [Branch](cmd/samples/recipes/branch/)
+* **Shows**: Parallel activity execution and concurrent activity management.
+* **What it does**: Executes multiple activities in parallel and waits for all to complete.
+* **Real-world use case**: Processing multiple orders simultaneously, calling multiple APIs in parallel, batch data processing.
+* **Key concepts**: Parallel execution, Future handling, concurrent activity management.
+
+```bash
 ./bin/branch -m worker
-```
-Run branch workflow
-```
-./bin/branch -m trigger -c branch
-```
-Run parallel branch workflow
-```
-./bin/branch -m trigger -c parallel this will run the parallel branch workflow
+./bin/branch -m trigger -c branch      # Single branch workflow
+./bin/branch -m trigger -c parallel    # Parallel branch workflow
 ```
 
-#### recipes/choice
-```
-./bin/choice -m worker
-```
-Run the single choice workflow
-```
-./bin/choice -m trigger -c single
-```
-Run the multi choice workflow
-```
-./bin/choice -m trigger -c multi
-```
+#### [Split-Merge](cmd/samples/recipes/splitmerge/)
+* **Shows**: Divide and conquer pattern with parallel processing.
+* **What it does**: Splits a large task into chunks, processes them in parallel, then merges results.
+* **Real-world use case**: Large file processing, batch data analysis, image/video processing, ETL pipelines.
+* **Key concepts**: Work splitting, parallel processing, result aggregation, worker coordination.
 
-#### greetings
-```
-./bin/greetings -m worker
-```
-```
-./bin/greetings -m trigger
+```bash
+./bin/splitmerge -m worker
+./bin/splitmerge -m trigger
 ```
 
-#### pickfirst
-```
+#### [Pick First](cmd/samples/recipes/pickfirst/)
+* **Shows**: Race condition handling and activity cancellation.
+* **What it does**: Runs multiple activities in parallel and uses the result from whichever completes first.
+* **Real-world use case**: Multi-provider API calls, redundant service calls, failover mechanisms, load balancing.
+* **Key concepts**: Parallel execution, cancellation, race condition handling.
+
+```bash
 ./bin/pickfirst -m worker
-```
-```
 ./bin/pickfirst -m trigger
 ```
 
-#### mutex
+### 🎲 **Decision Making Examples**
+
+#### [Choice](cmd/samples/recipes/choice/)
+* **Shows**: Conditional execution and decision-based activity routing.
+* **What it does**: Executes different activities based on the result of a decision activity.
+* **Real-world use case**: Order routing based on type, user authentication flows, approval workflows, conditional processing.
+* **Key concepts**: Conditional logic, decision trees, workflow branching.
+
+```bash
+./bin/choice -m worker
+./bin/choice -m trigger -c single    # Single choice workflow
+./bin/choice -m trigger -c multi     # Multi-choice workflow
 ```
-./bin/mutex -m worker
+
+### 🔄 **Error Handling & Recovery Examples**
+
+#### [Retry Activity](cmd/samples/recipes/retryactivity/)
+* **Shows**: Resilient processing with retry policies and heartbeat tracking.
+* **What it does**: Demonstrates activity retry policies with heartbeat progress tracking.
+* **Real-world use case**: API calls with intermittent failures, database operations, external service integration.
+* **Key concepts**: Retry policies, heartbeat mechanisms, progress tracking, failure recovery.
+
+```bash
+./bin/retryactivity -m worker
+./bin/retryactivity -m trigger
 ```
+
+#### [Cancel Activity](cmd/samples/recipes/cancelactivity/)
+* **Shows**: Graceful cancellation and cleanup operations.
+* **What it does**: Shows how to cancel running activities and perform cleanup operations.
+* **Real-world use case**: User-initiated cancellations, timeout handling, resource cleanup, emergency stops.
+* **Key concepts**: Cancellation handling, cleanup operations, graceful shutdown.
+
+```bash
+./bin/cancelactivity -m worker
+./bin/cancelactivity -m trigger
+# To cancel: ./bin/cancelactivity -m cancel -w <WorkflowID>
 ```
+
+### 🔐 **Resource Management Examples**
+
+#### [Mutex](cmd/samples/recipes/mutex/)
+* **Shows**: Resource locking and distributed locking patterns.
+* **What it does**: Ensures only one workflow can access a specific resource at a time.
+* **Real-world use case**: Database migrations, configuration updates, resource allocation, critical section protection.
+* **Key concepts**: Distributed locking, resource coordination, mutual exclusion.
+
+```bash
+./bin/mutex -m worker
 ./bin/mutex -m trigger
 ```
 
-#### retryactivity
-```
-./bin/retryactivity -m worker
+### 🔍 **Querying & Monitoring Examples**
+
+#### [Query](cmd/samples/recipes/query/)
+* **Shows**: Workflow state inspection and custom query handlers.
+* **What it does**: Demonstrates custom query handlers to inspect workflow state.
+* **Real-world use case**: Progress monitoring, status dashboards, debugging running workflows, user interfaces.
+* **Key concepts**: Query handlers, state inspection, workflow monitoring.
+
+**📖 [Detailed Guide](cmd/samples/recipes/query/README.md)**
+
+```bash
+./bin/query -m worker
+./bin/query -m trigger
+./bin/query -m query -w <workflow_id> -r <run_id> -t state
 ```
+
+#### [Consistent Query](cmd/samples/recipes/consistentquery/)
+* **Shows**: Consistent state queries and signal handling.
+* **What it does**: Shows how to query workflow state consistently while handling signals.
+* **Real-world use case**: Real-time dashboards, progress tracking, state synchronization.
+* **Key concepts**: Consistent queries, signal handling, state management.
+
+**📖 [Detailed Guide](cmd/samples/recipes/consistentquery/README.md)**
+
+```bash
+./bin/query -m worker
+./bin/query -m trigger
 ```
-./bin/retryactivity -m trigger
+
+### 🔄 **Advanced Workflow Patterns**
+
+#### [Child Workflow](cmd/samples/recipes/childworkflow/)
+* **Shows**: Workflow composition and parent-child workflow relationships.
+* **What it does**: Demonstrates parent-child workflow relationships with ContinueAsNew pattern.
+* **Real-world use case**: Complex business processes, workflow decomposition, modular workflow design.
+* **Key concepts**: Child workflows, ContinueAsNew, workflow composition.
+
+```bash
+./bin/childworkflow -m worker
+./bin/childworkflow -m trigger
 ```
 
-#### splitmerge
+#### [Dynamic](cmd/samples/recipes/dynamic/)
+* **Shows**: Dynamic activity invocation and string-based execution.
+* **What it does**: Demonstrates calling activities using string names for dynamic behavior.
+* **Real-world use case**: Plugin systems, dynamic workflow composition, configuration-driven workflows.
+* **Key concepts**: Dynamic activity invocation, string-based execution, flexible workflow design.
+
+```bash
+./bin/dynamic -m worker
+./bin/dynamic -m trigger
 ```
-./bin/splitmerge -m worker
+
+#### [Local Activity](cmd/samples/recipes/localactivity/)
+* **Shows**: High-performance local execution and lightweight operations.
+* **What it does**: Shows how to use local activities for quick operations that don't need external execution.
+* **Real-world use case**: Data validation, simple calculations, condition checking, fast decision making.
+* **Key concepts**: Local activities, performance optimization, lightweight operations.
+
+**📖 [Detailed Guide](cmd/samples/recipes/localactivity/README.md)**
+
+```bash
+./bin/localactivity -m worker
+./bin/localactivity -m trigger
+./bin/localactivity -m signal -s "_1_" -w <workflow_id>
 ```
+
+### 🔄 **Versioning & Evolution Examples**
+
+#### [Versioning](cmd/samples/recipes/versioning/)
+* **Shows**: Safe workflow evolution and backward compatibility.
+* **What it does**: Shows workflow versioning with backward compatibility and safe rollbacks.
+* **Real-world use case**: Production deployments, feature rollouts, backward compatibility, safe migrations.
+* **Key concepts**: Workflow versioning, backward compatibility, safe deployments.
+
+**📖 [Detailed Guide](cmd/samples/recipes/versioning/README.md)**
+
+```bash
+# Start with version 1
+./bin/versioning -m worker -v 1
+./bin/versioning -m trigger
+
+# Upgrade to version 2
+./bin/versioning -m worker -v 2
+# Kill version 1 worker to see migration
+
+# Continue with versions 3 and 4...
 ```
-./bin/splitmerge -m trigger
+
+### 🔍 **Advanced Features Examples**
+
+#### [Search Attributes](cmd/samples/recipes/searchattributes/)
+* **Shows**: Workflow indexing and search for workflow discovery.
+* **What it does**: Shows how to add searchable attributes to workflows and query them.
+* **Real-world use case**: Workflow discovery, filtering, reporting, operational dashboards.
+* **Key concepts**: Search attributes, workflow indexing, ElasticSearch integration.
+
+**📖 [Detailed Guide](cmd/samples/recipes/searchattributes/README.md)**
+
+```bash
+# Requires ElasticSearch
+docker-compose -f docker-compose-es.yml up
+./bin/searchattributes -m worker
+./bin/searchattributes -m trigger
 ```
 
-#### timer
+#### [Context Propagation](cmd/samples/recipes/ctxpropagation/)
+* **Shows**: Cross-workflow context and context propagation.
+* **What it does**: Demonstrates passing context (like user info, trace IDs) through workflow execution.
+* **Real-world use case**: Distributed tracing, user context propagation, audit trails, debugging.
+* **Key concepts**: Context propagation, distributed tracing, cross-service context.
+
+```bash
+./bin/ctxpropagation -m worker
+./bin/ctxpropagation -m trigger
 ```
-./bin/timer -m worker
+
+#### [Tracing](cmd/samples/recipes/tracing/)
+* **Shows**: Distributed tracing and integration with tracing systems.
+* **What it does**: Shows how to add distributed tracing to Cadence workflows.
+* **Real-world use case**: Performance monitoring, debugging, observability, APM integration.
+* **Key concepts**: Distributed tracing, Jaeger integration, observability.
+
+```bash
+./bin/tracing -m worker
+./bin/tracing -m trigger
 ```
+
+#### [Side Effect](cmd/samples/recipes/sideeffect/)
+* **Shows**: Non-deterministic operations and replay safety.
+* **What it does**: Demonstrates the SideEffect API for handling non-deterministic operations.
+* **Real-world use case**: ID generation, random number generation, external state queries.
+* **Key concepts**: Side effects, non-deterministic operations, replay safety.
+
+```bash
+./bin/sideeffect
 ```
-./bin/timer -m trigger
+
+### 🏢 **Business Application Examples**
+
+#### [Expense](cmd/samples/expense/)
+* **Shows**: Human-in-the-loop workflows and approval workflows.
+* **What it does**: Creates an expense report, waits for approval, then processes payment.
+* **Real-world use case**: Expense approval, purchase orders, document review, approval workflows.
+* **Key concepts**: Human-in-the-loop, async completion, approval workflows.
+
+**📖 [Detailed Guide](cmd/samples/expense/README.md)**
+
+```bash
+# Start dummy server
+./bin/expense_dummy
+
+# Start worker
+./bin/expense -m worker
+
+# Start workflow
+./bin/expense -m trigger
+
+# Approve at http://localhost:8099/list
 ```
 
-#### childworkflow
+#### [File Processing](cmd/samples/fileprocessing/)
+* **Shows**: Distributed file processing across multiple hosts.
+* **What it does**: Downloads, processes, and uploads files with host-specific execution.
+* **Real-world use case**: Large file processing, ETL pipelines, media processing, data transformation.
+* **Key concepts**: File processing, host-specific execution, session management, retry policies.
+
+```bash
+./bin/fileprocessing -m worker
+./bin/fileprocessing -m trigger
 ```
-./bin/childworkflow -m worker
+
+#### [DSL](cmd/samples/dsl/)
+* **Shows**: Domain-specific language and custom workflow language creation.
+* **What it does**: Implements a simple DSL for defining workflows using YAML configuration.
+* **Real-world use case**: Business user workflow definition, configuration-driven workflows, workflow templates.
+* **Key concepts**: DSL implementation, YAML parsing, dynamic workflow creation.
+
+**📖 [Detailed Guide](cmd/samples/dsl/README.md)**
+
+```bash
+./bin/dsl -m worker
+./bin/dsl -m trigger -dslConfig cmd/samples/dsl/workflow1.yaml
+./bin/dsl -m trigger -dslConfig cmd/samples/dsl/workflow2.yaml
 ```
+
+#### [Page Flow](cmd/samples/pageflow/)
+* **Shows**: UI-driven workflows and web application integration.
+* **What it does**: Shows a React frontend that interacts with Cadence workflows through signals and queries.
+* **Real-world use case**: Multi-step forms, wizard interfaces, approval workflows, user onboarding.
+* **Key concepts**: UI integration, signal handling, state management, frontend-backend coordination.
+
+**📖 [Detailed Guide](cmd/samples/pageflow/README.md)**
+
 ```
-./bin/childworkflow -m trigger
+
+### 🔬 **Advanced Technical Examples**
+
+#### [Batch](cmd/samples/batch/)
+* **Shows**: Batch processing and concurrency control.
+* **What it does**: Processes large batches of tasks with controlled concurrency.
+* **Real-world use case**: Batch data processing, bulk operations, ETL jobs, report generation.
+* **Key concepts**: Batch processing, concurrency control, task distribution.
+
+```bash
+./bin/batch -m worker
+./bin/batch -m trigger
 ```
 
-#### dynamic
+#### [PSO (Particle Swarm Optimization)](cmd/samples/pso/)
+* **Shows**: Complex mathematical workflows and long-running optimization workflows.
+* **What it does**: Implements particle swarm optimization with child workflows and ContinueAsNew.
+* **Real-world use case**: Mathematical optimization, machine learning training, complex calculations.
+* **Key concepts**: Long-running workflows, ContinueAsNew, child workflows, custom data converters.
+
+**📖 [Detailed Guide](cmd/samples/pso/README.md)**
+
+```bash
+./bin/pso -m worker
+./bin/pso -m trigger
+./bin/pso -m query -w <workflow_id> -r <run_id> -t state
 ```
-./bin/dynamic -m worker
+
+#### [Recovery](cmd/samples/recovery/)
+* **Shows**: Workflow recovery and failure handling.
+* **What it does**: Shows how to restart failed workflows and replay signals.
+* **Real-world use case**: Disaster recovery, workflow repair, system restoration.
+* **Key concepts**: Workflow recovery, signal replay, failure handling.
+
+**📖 [Detailed Guide](cmd/samples/recovery/README.md)**
+
+```bash
+./bin/recovery -m worker
+./bin/recovery -m trigger -w UserA -wt main.TripWorkflow
+./bin/recovery -m signal -w UserA -s '{"ID": "Trip1", "Total": 10}'
+./bin/recovery -m trigger -w UserB -wt recoveryworkflow -i '{"Type": "TripWorkflow", "Concurrency": 2}'
 ```
+
+## 🛠 **Development & Testing**
+
+### Building Samples
+```bash
+make
 ```
-./bin/dynamic -m trigger
+
+### Running Tests
+```bash
+# Run all tests
+go test ./...
+
+# Run specific sample tests
+go test ./cmd/samples/recipes/helloworld/
 ```
 
-#### localactivity
-See more details in https://github.com/uber-common/cadence-samples/blob/master/cmd/samples/recipes/localactivity/README.md
+### Worker Modes
+Most samples support these modes:
+- `worker`: Start a worker to handle workflow execution
+- `trigger`: Start a new workflow execution
+- `query`: Query a running workflow (where applicable)
+- `signal`: Send a signal to a workflow (where applicable)
+
+
+## 🤝 **Contributing**
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## 📄 **License**
 
-#### query
-See more details in https://github.com/uber-common/cadence-samples/blob/master/cmd/samples/recipes/query/README.md
+Apache 2.0 License - see [LICENSE](LICENSE) for details.
 
-#### recovery
-See more details in https://github.com/uber-common/cadence-samples/blob/master/cmd/samples/recovery/README.md
+## 🆘 **Getting Help**
 
-#### versioning
-See more details in https://github.com/uber-common/cadence-samples/blob/master/cmd/samples/versioning/README.md
+- **Documentation**: [Cadence Documentation](https://cadenceworkflow.io/docs/)
+- **Community**: [Cadence Community](https://cadenceworkflow.io/community/)
+- **Issues**: [GitHub Issues](https://github.com/uber-common/cadence-samples/issues)
 
-## License
+---
 
-Apache 2.0 License, please see [LICENSE](https://github.com/cadence-workflow/cadence-samples/blob/master/LICENSE) for details.
\ No newline at end of file
+**Happy Workflowing! 🚀**
\ No newline at end of file

From 977f6716f2d0130d34b0c27389e82349ab445b10 Mon Sep 17 00:00:00 2001
From: Seva Kaloshin <vsevolod.kaloshin@gmail.com>
Date: Tue, 8 Jul 2025 11:36:04 +0200
Subject: [PATCH 2/4] remove copies of detailed guides

---
 README.md | 304 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 175 insertions(+), 129 deletions(-)

diff --git a/README.md b/README.md
index fcf926cd..b90421c1 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ Learn more about Cadence at:
 git clone https://github.com/uber-common/cadence-samples.git && cd cadence-samples
 ```
 
-2. **Start Cadence Server**:
+2. Start Cadence Server*
 ```bash
 curl -LO https://raw.githubusercontent.com/cadence-workflow/cadence/refs/heads/master/docker/docker-compose.yml && docker-compose up --wait
 ```
@@ -39,7 +39,7 @@ make
 
 ## 📚 Sample Categories
 
-### 🎯 **Getting Started Examples**
+### 🎯 **Basic Examples**
 
 #### [Hello World](cmd/samples/recipes/helloworld/)
 * **Shows**: Basic Cadence workflow concepts and activity execution.
@@ -47,9 +47,15 @@ make
 * **Real-world use case**: Foundation for understanding workflow structure, activity execution, and basic error handling.
 * **Key concepts**: Workflow definition, activity execution, error handling, worker setup.
 
+##### How to run
+Start Worker:
 ```bash
-./bin/helloworld -m worker    # Start worker
-./bin/helloworld -m trigger   # Execute workflow
+./bin/helloworld -m worker
+```
+
+Start Workflow:
+```bash
+./bin/helloworld -m trigger
 ```
 
 #### [Greetings](cmd/samples/recipes/greetings/)
@@ -58,12 +64,16 @@ make
 * **Real-world use case**: Multi-step processes like user registration, order processing, or data transformation pipelines.
 * **Key concepts**: Sequential execution, activity chaining, result passing between activities.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/greetings -m worker
-./bin/greetings -m trigger
 ```
 
-### ⏰ **Scheduling & Timing Examples**
+Start Workflow:
+```bash
+./bin/greetings -m trigger
+```
 
 #### [Cron](cmd/samples/cron/)
 * **Shows**: Automated recurring tasks and cron scheduling.
@@ -71,8 +81,14 @@ make
 * **Real-world use case**: Data backups, report generation, system maintenance, periodic data synchronization.
 * **Key concepts**: Cron scheduling, workflow persistence, time-based execution.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/cron -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/cron -m trigger -cron "* * * * *"  # Run every minute
 ```
 
@@ -82,8 +98,14 @@ make
 * **Real-world use case**: Order processing with SLA monitoring, payment processing with timeout alerts, API calls with fallback mechanisms.
 * **Key concepts**: Timer creation, timeout handling, parallel execution with cancellation.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/timer -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/timer -m trigger
 ```
 
@@ -93,8 +115,14 @@ make
 * **Real-world use case**: Scheduled maintenance windows, delayed notifications, batch processing at specific times.
 * **Key concepts**: Delayed execution, time-based workflow scheduling.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/delaystart -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/delaystart -m trigger
 ```
 
@@ -106,10 +134,20 @@ make
 * **Real-world use case**: Processing multiple orders simultaneously, calling multiple APIs in parallel, batch data processing.
 * **Key concepts**: Parallel execution, Future handling, concurrent activity management.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/branch -m worker
-./bin/branch -m trigger -c branch      # Single branch workflow
-./bin/branch -m trigger -c parallel    # Parallel branch workflow
+```
+
+Start Single Branch Workflow:
+```bash
+./bin/branch -m trigger -c branch
+```
+
+Start Parallel Branch Workflow:
+```bash
+./bin/branch -m trigger -c parallel
 ```
 
 #### [Split-Merge](cmd/samples/recipes/splitmerge/)
@@ -118,8 +156,14 @@ make
 * **Real-world use case**: Large file processing, batch data analysis, image/video processing, ETL pipelines.
 * **Key concepts**: Work splitting, parallel processing, result aggregation, worker coordination.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/splitmerge -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/splitmerge -m trigger
 ```
 
@@ -129,12 +173,18 @@ make
 * **Real-world use case**: Multi-provider API calls, redundant service calls, failover mechanisms, load balancing.
 * **Key concepts**: Parallel execution, cancellation, race condition handling.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/pickfirst -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/pickfirst -m trigger
 ```
 
-### 🎲 **Decision Making Examples**
+### 🔍 **Advanced Examples**
 
 #### [Choice](cmd/samples/recipes/choice/)
 * **Shows**: Conditional execution and decision-based activity routing.
@@ -142,13 +192,21 @@ make
 * **Real-world use case**: Order routing based on type, user authentication flows, approval workflows, conditional processing.
 * **Key concepts**: Conditional logic, decision trees, workflow branching.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/choice -m worker
-./bin/choice -m trigger -c single    # Single choice workflow
-./bin/choice -m trigger -c multi     # Multi-choice workflow
 ```
 
-### 🔄 **Error Handling & Recovery Examples**
+Start Single Choice Workflow:
+```bash
+./bin/choice -m trigger -c single
+```
+
+Start Multi-Choice Workflow:
+```bash
+./bin/choice -m trigger -c multi
+```
 
 #### [Retry Activity](cmd/samples/recipes/retryactivity/)
 * **Shows**: Resilient processing with retry policies and heartbeat tracking.
@@ -156,8 +214,14 @@ make
 * **Real-world use case**: API calls with intermittent failures, database operations, external service integration.
 * **Key concepts**: Retry policies, heartbeat mechanisms, progress tracking, failure recovery.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/retryactivity -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/retryactivity -m trigger
 ```
 
@@ -167,13 +231,21 @@ make
 * **Real-world use case**: User-initiated cancellations, timeout handling, resource cleanup, emergency stops.
 * **Key concepts**: Cancellation handling, cleanup operations, graceful shutdown.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/cancelactivity -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/cancelactivity -m trigger
-# To cancel: ./bin/cancelactivity -m cancel -w <WorkflowID>
 ```
 
-### 🔐 **Resource Management Examples**
+**Cancel Workflow:**
+```bash
+./bin/cancelactivity -m cancel -w <WorkflowID>
+```
 
 #### [Mutex](cmd/samples/recipes/mutex/)
 * **Shows**: Resource locking and distributed locking patterns.
@@ -181,12 +253,16 @@ make
 * **Real-world use case**: Database migrations, configuration updates, resource allocation, critical section protection.
 * **Key concepts**: Distributed locking, resource coordination, mutual exclusion.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/mutex -m worker
-./bin/mutex -m trigger
 ```
 
-### 🔍 **Querying & Monitoring Examples**
+Start Workflow:
+```bash
+./bin/mutex -m trigger
+```
 
 #### [Query](cmd/samples/recipes/query/)
 * **Shows**: Workflow state inspection and custom query handlers.
@@ -194,13 +270,8 @@ make
 * **Real-world use case**: Progress monitoring, status dashboards, debugging running workflows, user interfaces.
 * **Key concepts**: Query handlers, state inspection, workflow monitoring.
 
-**📖 [Detailed Guide](cmd/samples/recipes/query/README.md)**
-
-```bash
-./bin/query -m worker
-./bin/query -m trigger
-./bin/query -m query -w <workflow_id> -r <run_id> -t state
-```
+##### How to run
+* Check **[Detailed Guide](cmd/samples/recipes/query/README.md)** to run the sample
 
 #### [Consistent Query](cmd/samples/recipes/consistentquery/)
 * **Shows**: Consistent state queries and signal handling.
@@ -208,14 +279,8 @@ make
 * **Real-world use case**: Real-time dashboards, progress tracking, state synchronization.
 * **Key concepts**: Consistent queries, signal handling, state management.
 
-**📖 [Detailed Guide](cmd/samples/recipes/consistentquery/README.md)**
-
-```bash
-./bin/query -m worker
-./bin/query -m trigger
-```
-
-### 🔄 **Advanced Workflow Patterns**
+##### How to run
+* Check **[Detailed Guide](cmd/samples/recipes/consistentquery/README.md)** to run the sample
 
 #### [Child Workflow](cmd/samples/recipes/childworkflow/)
 * **Shows**: Workflow composition and parent-child workflow relationships.
@@ -223,8 +288,14 @@ make
 * **Real-world use case**: Complex business processes, workflow decomposition, modular workflow design.
 * **Key concepts**: Child workflows, ContinueAsNew, workflow composition.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/childworkflow -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/childworkflow -m trigger
 ```
 
@@ -234,8 +305,14 @@ make
 * **Real-world use case**: Plugin systems, dynamic workflow composition, configuration-driven workflows.
 * **Key concepts**: Dynamic activity invocation, string-based execution, flexible workflow design.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/dynamic -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/dynamic -m trigger
 ```
 
@@ -245,15 +322,8 @@ make
 * **Real-world use case**: Data validation, simple calculations, condition checking, fast decision making.
 * **Key concepts**: Local activities, performance optimization, lightweight operations.
 
-**📖 [Detailed Guide](cmd/samples/recipes/localactivity/README.md)**
-
-```bash
-./bin/localactivity -m worker
-./bin/localactivity -m trigger
-./bin/localactivity -m signal -s "_1_" -w <workflow_id>
-```
-
-### 🔄 **Versioning & Evolution Examples**
+##### How to run
+* Check **[Detailed Guide](cmd/samples/recipes/localactivity/README.md)** to run the sample
 
 #### [Versioning](cmd/samples/recipes/versioning/)
 * **Shows**: Safe workflow evolution and backward compatibility.
@@ -261,21 +331,8 @@ make
 * **Real-world use case**: Production deployments, feature rollouts, backward compatibility, safe migrations.
 * **Key concepts**: Workflow versioning, backward compatibility, safe deployments.
 
-**📖 [Detailed Guide](cmd/samples/recipes/versioning/README.md)**
-
-```bash
-# Start with version 1
-./bin/versioning -m worker -v 1
-./bin/versioning -m trigger
-
-# Upgrade to version 2
-./bin/versioning -m worker -v 2
-# Kill version 1 worker to see migration
-
-# Continue with versions 3 and 4...
-```
-
-### 🔍 **Advanced Features Examples**
+##### How to run
+* Check **[Detailed Guide](cmd/samples/recipes/versioning/README.md)** to run the sample
 
 #### [Search Attributes](cmd/samples/recipes/searchattributes/)
 * **Shows**: Workflow indexing and search for workflow discovery.
@@ -283,14 +340,8 @@ make
 * **Real-world use case**: Workflow discovery, filtering, reporting, operational dashboards.
 * **Key concepts**: Search attributes, workflow indexing, ElasticSearch integration.
 
-**📖 [Detailed Guide](cmd/samples/recipes/searchattributes/README.md)**
-
-```bash
-# Requires ElasticSearch
-docker-compose -f docker-compose-es.yml up
-./bin/searchattributes -m worker
-./bin/searchattributes -m trigger
-```
+##### How to run
+* Check **[Detailed Guide](cmd/samples/recipes/searchattributes/README.md)** to run the sample
 
 #### [Context Propagation](cmd/samples/recipes/ctxpropagation/)
 * **Shows**: Cross-workflow context and context propagation.
@@ -298,8 +349,14 @@ docker-compose -f docker-compose-es.yml up
 * **Real-world use case**: Distributed tracing, user context propagation, audit trails, debugging.
 * **Key concepts**: Context propagation, distributed tracing, cross-service context.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/ctxpropagation -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/ctxpropagation -m trigger
 ```
 
@@ -309,8 +366,14 @@ docker-compose -f docker-compose-es.yml up
 * **Real-world use case**: Performance monitoring, debugging, observability, APM integration.
 * **Key concepts**: Distributed tracing, Jaeger integration, observability.
 
+##### How to run
+Start Worker:
 ```bash
 ./bin/tracing -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/tracing -m trigger
 ```
 
@@ -320,10 +383,47 @@ docker-compose -f docker-compose-es.yml up
 * **Real-world use case**: ID generation, random number generation, external state queries.
 * **Key concepts**: Side effects, non-deterministic operations, replay safety.
 
+##### How to run
+Start Workflow:
 ```bash
 ./bin/sideeffect
 ```
 
+#### [Batch](cmd/samples/batch/)
+* **Shows**: Batch processing and concurrency control.
+* **What it does**: Processes large batches of tasks with controlled concurrency.
+* **Real-world use case**: Batch data processing, bulk operations, ETL jobs, report generation.
+* **Key concepts**: Batch processing, concurrency control, task distribution.
+
+##### How to run
+Start Worker:
+```bash
+./bin/batch -m worker
+```
+
+Start Workflow:
+```bash
+./bin/batch -m trigger
+```
+
+#### [PSO (Particle Swarm Optimization)](cmd/samples/pso/)
+* **Shows**: Complex mathematical workflows and long-running optimization workflows.
+* **What it does**: Implements particle swarm optimization with child workflows and ContinueAsNew.
+* **Real-world use case**: Mathematical optimization, machine learning training, complex calculations.
+* **Key concepts**: Long-running workflows, ContinueAsNew, child workflows, custom data converters.
+
+##### How to run
+* Check **[Detailed Guide](cmd/samples/pso/README.md)** to run the sample
+
+#### [Recovery](cmd/samples/recovery/)
+* **Shows**: Workflow recovery and failure handling.
+* **What it does**: Shows how to restart failed workflows and replay signals.
+* **Real-world use case**: Disaster recovery, workflow repair, system restoration.
+* **Key concepts**: Workflow recovery, signal replay, failure handling.
+
+##### How to run
+* Check **[Detailed Guide](cmd/samples/recovery/README.md)** to run the sample
+
 ### 🏢 **Business Application Examples**
 
 #### [Expense](cmd/samples/expense/)
@@ -332,20 +432,8 @@ docker-compose -f docker-compose-es.yml up
 * **Real-world use case**: Expense approval, purchase orders, document review, approval workflows.
 * **Key concepts**: Human-in-the-loop, async completion, approval workflows.
 
-**📖 [Detailed Guide](cmd/samples/expense/README.md)**
-
-```bash
-# Start dummy server
-./bin/expense_dummy
-
-# Start worker
-./bin/expense -m worker
-
-# Start workflow
-./bin/expense -m trigger
-
-# Approve at http://localhost:8099/list
-```
+##### How to run
+* Check **[Detailed Guide](cmd/samples/expense/README.md)** to run the sample
 
 #### [File Processing](cmd/samples/fileprocessing/)
 * **Shows**: Distributed file processing across multiple hosts.
@@ -353,8 +441,14 @@ docker-compose -f docker-compose-es.yml up
 * **Real-world use case**: Large file processing, ETL pipelines, media processing, data transformation.
 * **Key concepts**: File processing, host-specific execution, session management, retry policies.
 
+##### How to run:
+Start Worker:
 ```bash
 ./bin/fileprocessing -m worker
+```
+
+Start Workflow:
+```bash
 ./bin/fileprocessing -m trigger
 ```
 
@@ -364,13 +458,8 @@ docker-compose -f docker-compose-es.yml up
 * **Real-world use case**: Business user workflow definition, configuration-driven workflows, workflow templates.
 * **Key concepts**: DSL implementation, YAML parsing, dynamic workflow creation.
 
-**📖 [Detailed Guide](cmd/samples/dsl/README.md)**
-
-```bash
-./bin/dsl -m worker
-./bin/dsl -m trigger -dslConfig cmd/samples/dsl/workflow1.yaml
-./bin/dsl -m trigger -dslConfig cmd/samples/dsl/workflow2.yaml
-```
+##### How to run
+* Check **[Detailed Guide](cmd/samples/dsl/README.md)** to run the sample
 
 #### [Page Flow](cmd/samples/pageflow/)
 * **Shows**: UI-driven workflows and web application integration.
@@ -378,51 +467,8 @@ docker-compose -f docker-compose-es.yml up
 * **Real-world use case**: Multi-step forms, wizard interfaces, approval workflows, user onboarding.
 * **Key concepts**: UI integration, signal handling, state management, frontend-backend coordination.
 
-**📖 [Detailed Guide](cmd/samples/pageflow/README.md)**
-
-```
-
-### 🔬 **Advanced Technical Examples**
-
-#### [Batch](cmd/samples/batch/)
-* **Shows**: Batch processing and concurrency control.
-* **What it does**: Processes large batches of tasks with controlled concurrency.
-* **Real-world use case**: Batch data processing, bulk operations, ETL jobs, report generation.
-* **Key concepts**: Batch processing, concurrency control, task distribution.
-
-```bash
-./bin/batch -m worker
-./bin/batch -m trigger
-```
-
-#### [PSO (Particle Swarm Optimization)](cmd/samples/pso/)
-* **Shows**: Complex mathematical workflows and long-running optimization workflows.
-* **What it does**: Implements particle swarm optimization with child workflows and ContinueAsNew.
-* **Real-world use case**: Mathematical optimization, machine learning training, complex calculations.
-* **Key concepts**: Long-running workflows, ContinueAsNew, child workflows, custom data converters.
-
-**📖 [Detailed Guide](cmd/samples/pso/README.md)**
-
-```bash
-./bin/pso -m worker
-./bin/pso -m trigger
-./bin/pso -m query -w <workflow_id> -r <run_id> -t state
-```
-
-#### [Recovery](cmd/samples/recovery/)
-* **Shows**: Workflow recovery and failure handling.
-* **What it does**: Shows how to restart failed workflows and replay signals.
-* **Real-world use case**: Disaster recovery, workflow repair, system restoration.
-* **Key concepts**: Workflow recovery, signal replay, failure handling.
-
-**📖 [Detailed Guide](cmd/samples/recovery/README.md)**
-
-```bash
-./bin/recovery -m worker
-./bin/recovery -m trigger -w UserA -wt main.TripWorkflow
-./bin/recovery -m signal -w UserA -s '{"ID": "Trip1", "Total": 10}'
-./bin/recovery -m trigger -w UserB -wt recoveryworkflow -i '{"Type": "TripWorkflow", "Concurrency": 2}'
-```
+##### How to run
+* Check **[Detailed Guide](cmd/samples/pageflow/README.md)** to run the sample
 
 ## 🛠 **Development & Testing**
 

From d4b460c6c7099ebff887190a52efbb19c57b7077 Mon Sep 17 00:00:00 2001
From: Seva Kaloshin <vsevolod.kaloshin@gmail.com>
Date: Tue, 8 Jul 2025 11:42:57 +0200
Subject: [PATCH 3/4] add table of contents

---
 README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 50 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index b90421c1..25701182 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ Learn more about Cadence at:
 git clone https://github.com/uber-common/cadence-samples.git && cd cadence-samples
 ```
 
-2. Start Cadence Server*
+2. **Start Cadence Server**
 ```bash
 curl -LO https://raw.githubusercontent.com/cadence-workflow/cadence/refs/heads/master/docker/docker-compose.yml && docker-compose up --wait
 ```
@@ -39,6 +39,44 @@ make
 
 ## 📚 Sample Categories
 
+### Table of Contents
+- [🎯 Basic Examples](#-basic-examples)
+  - [Hello World](#hello-world-cmdsamplesrecipeshelloworld)
+  - [Greetings](#greetings-cmdsamplesrecipesgreetings)
+  - [Cron](#cron-cmdsamplescron)
+  - [Timer](#timer-cmdsamplesrecipestimer)
+  - [Delay Start](#delay-start-cmdsamplesrecipesdelaystart)
+  - [Branch](#branch-cmdsamplesrecipesbranch)
+  - [Split-Merge](#split-merge-cmdsamplesrecipessplitmerge)
+  - [Pick First](#pick-first-cmdsamplesrecipespickfirst)
+
+- [🔧 Advanced Examples](#-advanced-examples)
+  - [Choice](#choice-cmdsamplesrecipeschoice)
+  - [Retry Activity](#retry-activity-cmdsamplesrecipesretryactivity)
+  - [Cancel Activity](#cancel-activity-cmdsamplesrecipescancelactivity)
+  - [Mutex](#mutex-cmdsamplesrecipesmutex)
+  - [Query](#query-cmdsamplesrecipesquery)
+  - [Consistent Query](#consistent-query-cmdsamplesrecipesconsistentquery)
+  - [Child Workflow](#child-workflow-cmdsamplesrecipeschildworkflow)
+  - [Dynamic](#dynamic-cmdsamplesrecipesdynamic)
+  - [Local Activity](#local-activity-cmdsamplesrecipeslocalactivity)
+  - [Versioning](#versioning-cmdsamplesrecipesversioning)
+  - [Search Attributes](#search-attributes-cmdsamplesrecipessearchattributes)
+  - [Context Propagation](#context-propagation-cmdsamplesrecipesctxpropagation)
+  - [Tracing](#tracing-cmdsamplesrecipestracing)
+  - [Side Effect](#side-effect-cmdsamplesrecipessideeffect)
+  - [Batch](#batch-cmdsamplesbatch)
+  - [Recovery](#recovery-cmdsamplesrecovery)
+
+- [🏢 Business Application Examples](#-business-application-examples)
+  - [Expense](#expense-cmdsamplesexpense)
+  - [File Processing](#file-processing-cmdsamplesfileprocessing)
+  - [DSL](#dsl-cmdsamplesdsl)
+  - [Page Flow](#page-flow-cmdsamplespageflow)
+  - [PSO (Particle Swarm Optimization)](#pso-particle-swarm-optimization-cmdsamplespso)
+
+---
+
 ### 🎯 **Basic Examples**
 
 #### [Hello World](cmd/samples/recipes/helloworld/)
@@ -184,7 +222,7 @@ Start Workflow:
 ./bin/pickfirst -m trigger
 ```
 
-### 🔍 **Advanced Examples**
+### 🔧 **Advanced Examples**
 
 #### [Choice](cmd/samples/recipes/choice/)
 * **Shows**: Conditional execution and decision-based activity routing.
@@ -406,15 +444,6 @@ Start Workflow:
 ./bin/batch -m trigger
 ```
 
-#### [PSO (Particle Swarm Optimization)](cmd/samples/pso/)
-* **Shows**: Complex mathematical workflows and long-running optimization workflows.
-* **What it does**: Implements particle swarm optimization with child workflows and ContinueAsNew.
-* **Real-world use case**: Mathematical optimization, machine learning training, complex calculations.
-* **Key concepts**: Long-running workflows, ContinueAsNew, child workflows, custom data converters.
-
-##### How to run
-* Check **[Detailed Guide](cmd/samples/pso/README.md)** to run the sample
-
 #### [Recovery](cmd/samples/recovery/)
 * **Shows**: Workflow recovery and failure handling.
 * **What it does**: Shows how to restart failed workflows and replay signals.
@@ -470,6 +499,16 @@ Start Workflow:
 ##### How to run
 * Check **[Detailed Guide](cmd/samples/pageflow/README.md)** to run the sample
 
+
+#### [PSO (Particle Swarm Optimization)](cmd/samples/pso/)
+* **Shows**: Complex mathematical workflows and long-running optimization workflows.
+* **What it does**: Implements particle swarm optimization with child workflows and ContinueAsNew.
+* **Real-world use case**: Mathematical optimization, machine learning training, complex calculations.
+* **Key concepts**: Long-running workflows, ContinueAsNew, child workflows, custom data converters.
+
+##### How to run
+* Check **[Detailed Guide](cmd/samples/pso/README.md)** to run the sample
+
 ## 🛠 **Development & Testing**
 
 ### Building Samples

From 26b7be12e1c27e9abd0372e47bb3851f77ddb889 Mon Sep 17 00:00:00 2001
From: Seva Kaloshin <vsevolod.kaloshin@gmail.com>
Date: Tue, 8 Jul 2025 11:52:27 +0200
Subject: [PATCH 4/4] remove extra guides

---
 README.md | 177 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 91 insertions(+), 86 deletions(-)

diff --git a/README.md b/README.md
index 25701182..92514446 100644
--- a/README.md
+++ b/README.md
@@ -41,49 +41,50 @@ make
 
 ### Table of Contents
 - [🎯 Basic Examples](#-basic-examples)
-  - [Hello World](#hello-world-cmdsamplesrecipeshelloworld)
-  - [Greetings](#greetings-cmdsamplesrecipesgreetings)
-  - [Cron](#cron-cmdsamplescron)
-  - [Timer](#timer-cmdsamplesrecipestimer)
-  - [Delay Start](#delay-start-cmdsamplesrecipesdelaystart)
-  - [Branch](#branch-cmdsamplesrecipesbranch)
-  - [Split-Merge](#split-merge-cmdsamplesrecipessplitmerge)
-  - [Pick First](#pick-first-cmdsamplesrecipespickfirst)
+  - [Hello World](#hello-world)
+  - [Greetings](#greetings)
+  - [Cron](#cron)
+  - [Timer](#timer)
+  - [Delay Start](#delay-start)
+  - [Branch](#branch)
+  - [Split-Merge](#split-merge)
+  - [Pick First](#pick-first)
 
 - [🔧 Advanced Examples](#-advanced-examples)
-  - [Choice](#choice-cmdsamplesrecipeschoice)
-  - [Retry Activity](#retry-activity-cmdsamplesrecipesretryactivity)
-  - [Cancel Activity](#cancel-activity-cmdsamplesrecipescancelactivity)
-  - [Mutex](#mutex-cmdsamplesrecipesmutex)
-  - [Query](#query-cmdsamplesrecipesquery)
-  - [Consistent Query](#consistent-query-cmdsamplesrecipesconsistentquery)
-  - [Child Workflow](#child-workflow-cmdsamplesrecipeschildworkflow)
-  - [Dynamic](#dynamic-cmdsamplesrecipesdynamic)
-  - [Local Activity](#local-activity-cmdsamplesrecipeslocalactivity)
-  - [Versioning](#versioning-cmdsamplesrecipesversioning)
-  - [Search Attributes](#search-attributes-cmdsamplesrecipessearchattributes)
-  - [Context Propagation](#context-propagation-cmdsamplesrecipesctxpropagation)
-  - [Tracing](#tracing-cmdsamplesrecipestracing)
-  - [Side Effect](#side-effect-cmdsamplesrecipessideeffect)
-  - [Batch](#batch-cmdsamplesbatch)
-  - [Recovery](#recovery-cmdsamplesrecovery)
+  - [Choice](#choice)
+  - [Retry Activity](#retry-activity)
+  - [Cancel Activity](#cancel-activity)
+  - [Mutex](#mutex)
+  - [Query](#query)
+  - [Consistent Query](#consistent-query)
+  - [Child Workflow](#child-workflow)
+  - [Dynamic](#dynamic)
+  - [Local Activity](#local-activity)
+  - [Versioning](#versioning)
+  - [Search Attributes](#search-attributes)
+  - [Context Propagation](#context-propagation)
+  - [Tracing](#tracing)
+  - [Side Effect](#side-effect)
+  - [Batch](#batch)
+  - [Recovery](#recovery)
 
 - [🏢 Business Application Examples](#-business-application-examples)
-  - [Expense](#expense-cmdsamplesexpense)
-  - [File Processing](#file-processing-cmdsamplesfileprocessing)
-  - [DSL](#dsl-cmdsamplesdsl)
-  - [Page Flow](#page-flow-cmdsamplespageflow)
-  - [PSO (Particle Swarm Optimization)](#pso-particle-swarm-optimization-cmdsamplespso)
+  - [Expense](#expense)
+  - [File Processing](#file-processing)
+  - [DSL](#dsl)
+  - [Page Flow](#page-flow)
+  - [PSO (Particle Swarm Optimization)](#pso-particle-swarm-optimization)
 
 ---
 
 ### 🎯 **Basic Examples**
 
-#### [Hello World](cmd/samples/recipes/helloworld/)
+#### Hello World
 * **Shows**: Basic Cadence workflow concepts and activity execution.
 * **What it does**: Executes a single activity that returns a greeting message.
 * **Real-world use case**: Foundation for understanding workflow structure, activity execution, and basic error handling.
 * **Key concepts**: Workflow definition, activity execution, error handling, worker setup.
+* **Source code**: [cmd/samples/recipes/helloworld/](cmd/samples/recipes/helloworld/)
 
 ##### How to run
 Start Worker:
@@ -96,11 +97,12 @@ Start Workflow:
 ./bin/helloworld -m trigger
 ```
 
-#### [Greetings](cmd/samples/recipes/greetings/)
+#### Greetings
 * **Shows**: Sequential activity execution and result passing between activities.
 * **What it does**: Executes three activities in sequence: get greeting, get name, then combine them.
 * **Real-world use case**: Multi-step processes like user registration, order processing, or data transformation pipelines.
 * **Key concepts**: Sequential execution, activity chaining, result passing between activities.
+* **Source code**: [cmd/samples/recipes/greetings/](cmd/samples/recipes/greetings/)
 
 ##### How to run
 Start Worker:
@@ -113,11 +115,12 @@ Start Workflow:
 ./bin/greetings -m trigger
 ```
 
-#### [Cron](cmd/samples/cron/)
+#### Cron
 * **Shows**: Automated recurring tasks and cron scheduling.
 * **What it does**: Executes a workflow based on cron expressions (e.g., every minute, daily at 2 AM).
 * **Real-world use case**: Data backups, report generation, system maintenance, periodic data synchronization.
 * **Key concepts**: Cron scheduling, workflow persistence, time-based execution.
+* **Source code**: [cmd/samples/cron/](cmd/samples/cron/)
 
 ##### How to run
 Start Worker:
@@ -130,11 +133,12 @@ Start Workflow:
 ./bin/cron -m trigger -cron "* * * * *"  # Run every minute
 ```
 
-#### [Timer](cmd/samples/recipes/timer/)
+#### Timer
 * **Shows**: Timeout and delay handling with parallel execution.
 * **What it does**: Starts a long-running process and sends a notification if it takes too long.
 * **Real-world use case**: Order processing with SLA monitoring, payment processing with timeout alerts, API calls with fallback mechanisms.
 * **Key concepts**: Timer creation, timeout handling, parallel execution with cancellation.
+* **Source code**: [cmd/samples/recipes/timer/](cmd/samples/recipes/timer/)
 
 ##### How to run
 Start Worker:
@@ -147,11 +151,12 @@ Start Workflow:
 ./bin/timer -m trigger
 ```
 
-#### [Delay Start](cmd/samples/recipes/delaystart/)
+#### Delay Start
 * **Shows**: Deferred execution and delayed workflow execution.
 * **What it does**: Waits for a specified duration before executing the main workflow logic.
 * **Real-world use case**: Scheduled maintenance windows, delayed notifications, batch processing at specific times.
 * **Key concepts**: Delayed execution, time-based workflow scheduling.
+* **Source code**: [cmd/samples/recipes/delaystart/](cmd/samples/recipes/delaystart/)
 
 ##### How to run
 Start Worker:
@@ -166,11 +171,12 @@ Start Workflow:
 
 ### 🔄 **Parallel Execution Examples**
 
-#### [Branch](cmd/samples/recipes/branch/)
+#### Branch
 * **Shows**: Parallel activity execution and concurrent activity management.
 * **What it does**: Executes multiple activities in parallel and waits for all to complete.
 * **Real-world use case**: Processing multiple orders simultaneously, calling multiple APIs in parallel, batch data processing.
 * **Key concepts**: Parallel execution, Future handling, concurrent activity management.
+* **Source code**: [cmd/samples/recipes/branch/](cmd/samples/recipes/branch/)
 
 ##### How to run
 Start Worker:
@@ -188,11 +194,12 @@ Start Parallel Branch Workflow:
 ./bin/branch -m trigger -c parallel
 ```
 
-#### [Split-Merge](cmd/samples/recipes/splitmerge/)
+#### Split-Merge
 * **Shows**: Divide and conquer pattern with parallel processing.
 * **What it does**: Splits a large task into chunks, processes them in parallel, then merges results.
 * **Real-world use case**: Large file processing, batch data analysis, image/video processing, ETL pipelines.
 * **Key concepts**: Work splitting, parallel processing, result aggregation, worker coordination.
+* **Source code**: [cmd/samples/recipes/splitmerge/](cmd/samples/recipes/splitmerge/)
 
 ##### How to run
 Start Worker:
@@ -205,11 +212,12 @@ Start Workflow:
 ./bin/splitmerge -m trigger
 ```
 
-#### [Pick First](cmd/samples/recipes/pickfirst/)
+#### Pick First
 * **Shows**: Race condition handling and activity cancellation.
 * **What it does**: Runs multiple activities in parallel and uses the result from whichever completes first.
 * **Real-world use case**: Multi-provider API calls, redundant service calls, failover mechanisms, load balancing.
 * **Key concepts**: Parallel execution, cancellation, race condition handling.
+* **Source code**: [cmd/samples/recipes/pickfirst/](cmd/samples/recipes/pickfirst/)
 
 ##### How to run
 Start Worker:
@@ -224,11 +232,12 @@ Start Workflow:
 
 ### 🔧 **Advanced Examples**
 
-#### [Choice](cmd/samples/recipes/choice/)
+#### Choice
 * **Shows**: Conditional execution and decision-based activity routing.
 * **What it does**: Executes different activities based on the result of a decision activity.
 * **Real-world use case**: Order routing based on type, user authentication flows, approval workflows, conditional processing.
 * **Key concepts**: Conditional logic, decision trees, workflow branching.
+* **Source code**: [cmd/samples/recipes/choice/](cmd/samples/recipes/choice/)
 
 ##### How to run
 Start Worker:
@@ -246,11 +255,12 @@ Start Multi-Choice Workflow:
 ./bin/choice -m trigger -c multi
 ```
 
-#### [Retry Activity](cmd/samples/recipes/retryactivity/)
+#### Retry Activity
 * **Shows**: Resilient processing with retry policies and heartbeat tracking.
 * **What it does**: Demonstrates activity retry policies with heartbeat progress tracking.
 * **Real-world use case**: API calls with intermittent failures, database operations, external service integration.
 * **Key concepts**: Retry policies, heartbeat mechanisms, progress tracking, failure recovery.
+* **Source code**: [cmd/samples/recipes/retryactivity/](cmd/samples/recipes/retryactivity/)
 
 ##### How to run
 Start Worker:
@@ -263,11 +273,12 @@ Start Workflow:
 ./bin/retryactivity -m trigger
 ```
 
-#### [Cancel Activity](cmd/samples/recipes/cancelactivity/)
+#### Cancel Activity
 * **Shows**: Graceful cancellation and cleanup operations.
 * **What it does**: Shows how to cancel running activities and perform cleanup operations.
 * **Real-world use case**: User-initiated cancellations, timeout handling, resource cleanup, emergency stops.
 * **Key concepts**: Cancellation handling, cleanup operations, graceful shutdown.
+* **Source code**: [cmd/samples/recipes/cancelactivity/](cmd/samples/recipes/cancelactivity/)
 
 ##### How to run
 Start Worker:
@@ -285,46 +296,42 @@ Start Workflow:
 ./bin/cancelactivity -m cancel -w <WorkflowID>
 ```
 
-#### [Mutex](cmd/samples/recipes/mutex/)
+#### Mutex
 * **Shows**: Resource locking and distributed locking patterns.
 * **What it does**: Ensures only one workflow can access a specific resource at a time.
 * **Real-world use case**: Database migrations, configuration updates, resource allocation, critical section protection.
 * **Key concepts**: Distributed locking, resource coordination, mutual exclusion.
+* **Source code**: [cmd/samples/recipes/mutex/](cmd/samples/recipes/mutex/)
 
 ##### How to run
-Start Worker:
-```bash
-./bin/mutex -m worker
-```
+* Check **[Detailed Guide](cmd/samples/recipes/mutex/README.md)** to run the sample
 
-Start Workflow:
-```bash
-./bin/mutex -m trigger
-```
-
-#### [Query](cmd/samples/recipes/query/)
+#### Query
 * **Shows**: Workflow state inspection and custom query handlers.
 * **What it does**: Demonstrates custom query handlers to inspect workflow state.
 * **Real-world use case**: Progress monitoring, status dashboards, debugging running workflows, user interfaces.
 * **Key concepts**: Query handlers, state inspection, workflow monitoring.
+* **Source code**: [cmd/samples/recipes/query/](cmd/samples/recipes/query/)
 
 ##### How to run
 * Check **[Detailed Guide](cmd/samples/recipes/query/README.md)** to run the sample
 
-#### [Consistent Query](cmd/samples/recipes/consistentquery/)
+#### Consistent Query
 * **Shows**: Consistent state queries and signal handling.
 * **What it does**: Shows how to query workflow state consistently while handling signals.
 * **Real-world use case**: Real-time dashboards, progress tracking, state synchronization.
 * **Key concepts**: Consistent queries, signal handling, state management.
+* **Source code**: [cmd/samples/recipes/consistentquery/](cmd/samples/recipes/consistentquery/)
 
 ##### How to run
 * Check **[Detailed Guide](cmd/samples/recipes/consistentquery/README.md)** to run the sample
 
-#### [Child Workflow](cmd/samples/recipes/childworkflow/)
+#### Child Workflow
 * **Shows**: Workflow composition and parent-child workflow relationships.
 * **What it does**: Demonstrates parent-child workflow relationships with ContinueAsNew pattern.
 * **Real-world use case**: Complex business processes, workflow decomposition, modular workflow design.
 * **Key concepts**: Child workflows, ContinueAsNew, workflow composition.
+* **Source code**: [cmd/samples/recipes/childworkflow/](cmd/samples/recipes/childworkflow/)
 
 ##### How to run
 Start Worker:
@@ -337,11 +344,12 @@ Start Workflow:
 ./bin/childworkflow -m trigger
 ```
 
-#### [Dynamic](cmd/samples/recipes/dynamic/)
+#### Dynamic
 * **Shows**: Dynamic activity invocation and string-based execution.
 * **What it does**: Demonstrates calling activities using string names for dynamic behavior.
 * **Real-world use case**: Plugin systems, dynamic workflow composition, configuration-driven workflows.
 * **Key concepts**: Dynamic activity invocation, string-based execution, flexible workflow design.
+* **Source code**: [cmd/samples/recipes/dynamic/](cmd/samples/recipes/dynamic/)
 
 ##### How to run
 Start Worker:
@@ -354,55 +362,52 @@ Start Workflow:
 ./bin/dynamic -m trigger
 ```
 
-#### [Local Activity](cmd/samples/recipes/localactivity/)
+#### Local Activity
 * **Shows**: High-performance local execution and lightweight operations.
 * **What it does**: Shows how to use local activities for quick operations that don't need external execution.
 * **Real-world use case**: Data validation, simple calculations, condition checking, fast decision making.
 * **Key concepts**: Local activities, performance optimization, lightweight operations.
+* **Source code**: [cmd/samples/recipes/localactivity/](cmd/samples/recipes/localactivity/)
 
 ##### How to run
 * Check **[Detailed Guide](cmd/samples/recipes/localactivity/README.md)** to run the sample
 
-#### [Versioning](cmd/samples/recipes/versioning/)
+#### Versioning
 * **Shows**: Safe workflow evolution and backward compatibility.
 * **What it does**: Shows workflow versioning with backward compatibility and safe rollbacks.
 * **Real-world use case**: Production deployments, feature rollouts, backward compatibility, safe migrations.
 * **Key concepts**: Workflow versioning, backward compatibility, safe deployments.
+* **Source code**: [cmd/samples/recipes/versioning/](cmd/samples/recipes/versioning/)
 
 ##### How to run
 * Check **[Detailed Guide](cmd/samples/recipes/versioning/README.md)** to run the sample
 
-#### [Search Attributes](cmd/samples/recipes/searchattributes/)
+#### Search Attributes
 * **Shows**: Workflow indexing and search for workflow discovery.
 * **What it does**: Shows how to add searchable attributes to workflows and query them.
 * **Real-world use case**: Workflow discovery, filtering, reporting, operational dashboards.
 * **Key concepts**: Search attributes, workflow indexing, ElasticSearch integration.
+* **Source code**: [cmd/samples/recipes/searchattributes/](cmd/samples/recipes/searchattributes/)
 
 ##### How to run
 * Check **[Detailed Guide](cmd/samples/recipes/searchattributes/README.md)** to run the sample
 
-#### [Context Propagation](cmd/samples/recipes/ctxpropagation/)
+#### Context Propagation
 * **Shows**: Cross-workflow context and context propagation.
 * **What it does**: Demonstrates passing context (like user info, trace IDs) through workflow execution.
 * **Real-world use case**: Distributed tracing, user context propagation, audit trails, debugging.
 * **Key concepts**: Context propagation, distributed tracing, cross-service context.
+* **Source code**: [cmd/samples/recipes/ctxpropagation/](cmd/samples/recipes/ctxpropagation/)
 
 ##### How to run
-Start Worker:
-```bash
-./bin/ctxpropagation -m worker
-```
-
-Start Workflow:
-```bash
-./bin/ctxpropagation -m trigger
-```
+* Check **[Detailed Guide](cmd/samples/recipes/ctxpropagation/README.md)** to run the sample
 
-#### [Tracing](cmd/samples/recipes/tracing/)
+#### Tracing
 * **Shows**: Distributed tracing and integration with tracing systems.
 * **What it does**: Shows how to add distributed tracing to Cadence workflows.
 * **Real-world use case**: Performance monitoring, debugging, observability, APM integration.
 * **Key concepts**: Distributed tracing, Jaeger integration, observability.
+* **Source code**: [cmd/samples/recipes/tracing/](cmd/samples/recipes/tracing/)
 
 ##### How to run
 Start Worker:
@@ -415,11 +420,12 @@ Start Workflow:
 ./bin/tracing -m trigger
 ```
 
-#### [Side Effect](cmd/samples/recipes/sideeffect/)
+#### Side Effect
 * **Shows**: Non-deterministic operations and replay safety.
 * **What it does**: Demonstrates the SideEffect API for handling non-deterministic operations.
 * **Real-world use case**: ID generation, random number generation, external state queries.
 * **Key concepts**: Side effects, non-deterministic operations, replay safety.
+* **Source code**: [cmd/samples/recipes/sideeffect/](cmd/samples/recipes/sideeffect/)
 
 ##### How to run
 Start Workflow:
@@ -427,11 +433,12 @@ Start Workflow:
 ./bin/sideeffect
 ```
 
-#### [Batch](cmd/samples/batch/)
+#### Batch
 * **Shows**: Batch processing and concurrency control.
 * **What it does**: Processes large batches of tasks with controlled concurrency.
 * **Real-world use case**: Batch data processing, bulk operations, ETL jobs, report generation.
 * **Key concepts**: Batch processing, concurrency control, task distribution.
+* **Source code**: [cmd/samples/batch/](cmd/samples/batch/)
 
 ##### How to run
 Start Worker:
@@ -444,67 +451,65 @@ Start Workflow:
 ./bin/batch -m trigger
 ```
 
-#### [Recovery](cmd/samples/recovery/)
+#### Recovery
 * **Shows**: Workflow recovery and failure handling.
 * **What it does**: Shows how to restart failed workflows and replay signals.
 * **Real-world use case**: Disaster recovery, workflow repair, system restoration.
 * **Key concepts**: Workflow recovery, signal replay, failure handling.
+* **Source code**: [cmd/samples/recovery/](cmd/samples/recovery/)
 
 ##### How to run
 * Check **[Detailed Guide](cmd/samples/recovery/README.md)** to run the sample
 
 ### 🏢 **Business Application Examples**
 
-#### [Expense](cmd/samples/expense/)
+#### Expense
 * **Shows**: Human-in-the-loop workflows and approval workflows.
 * **What it does**: Creates an expense report, waits for approval, then processes payment.
 * **Real-world use case**: Expense approval, purchase orders, document review, approval workflows.
 * **Key concepts**: Human-in-the-loop, async completion, approval workflows.
+* **Source code**: [cmd/samples/expense/](cmd/samples/expense/)
 
 ##### How to run
 * Check **[Detailed Guide](cmd/samples/expense/README.md)** to run the sample
 
-#### [File Processing](cmd/samples/fileprocessing/)
+#### File Processing
 * **Shows**: Distributed file processing across multiple hosts.
 * **What it does**: Downloads, processes, and uploads files with host-specific execution.
 * **Real-world use case**: Large file processing, ETL pipelines, media processing, data transformation.
 * **Key concepts**: File processing, host-specific execution, session management, retry policies.
+* **Source code**: [cmd/samples/fileprocessing/](cmd/samples/fileprocessing/)
 
-##### How to run:
-Start Worker:
-```bash
-./bin/fileprocessing -m worker
-```
-
-Start Workflow:
-```bash
-./bin/fileprocessing -m trigger
-```
+##### How to run
+* Check **[Detailed Guide](cmd/samples/fileprocessing/README.md)** to run the sample
 
-#### [DSL](cmd/samples/dsl/)
+#### DSL
 * **Shows**: Domain-specific language and custom workflow language creation.
 * **What it does**: Implements a simple DSL for defining workflows using YAML configuration.
 * **Real-world use case**: Business user workflow definition, configuration-driven workflows, workflow templates.
 * **Key concepts**: DSL implementation, YAML parsing, dynamic workflow creation.
+* **Source code**: [cmd/samples/dsl/](cmd/samples/dsl/)
 
 ##### How to run
 * Check **[Detailed Guide](cmd/samples/dsl/README.md)** to run the sample
 
-#### [Page Flow](cmd/samples/pageflow/)
+#### Page Flow
 * **Shows**: UI-driven workflows and web application integration.
 * **What it does**: Shows a React frontend that interacts with Cadence workflows through signals and queries.
 * **Real-world use case**: Multi-step forms, wizard interfaces, approval workflows, user onboarding.
 * **Key concepts**: UI integration, signal handling, state management, frontend-backend coordination.
+* **Source code**: [cmd/samples/pageflow/](cmd/samples/pageflow/)
 
 ##### How to run
 * Check **[Detailed Guide](cmd/samples/pageflow/README.md)** to run the sample
 
 
-#### [PSO (Particle Swarm Optimization)](cmd/samples/pso/)
+#### PSO (Particle Swarm Optimization)
 * **Shows**: Complex mathematical workflows and long-running optimization workflows.
 * **What it does**: Implements particle swarm optimization with child workflows and ContinueAsNew.
 * **Real-world use case**: Mathematical optimization, machine learning training, complex calculations.
 * **Key concepts**: Long-running workflows, ContinueAsNew, child workflows, custom data converters.
+* **Source code**: [cmd/samples/pso/](cmd/samples/pso/)
 
 ##### How to run
 * Check **[Detailed Guide](cmd/samples/pso/README.md)** to run the sample