setup telescopium

.env-example

@@ -1,8 +1,13 @@
 ENVIRONMENT='development'
 MODE='dynamic'
+
 NATS_URL='nats://localhost:4222'
 AQUILA_URL='http://localhost:8080'
+AQUILA_TOKEN='token'
+
 WITH_HEALTH_SERVICE=false
 GRPC_HOST='127.0.0.1'
 GRPC_PORT=50051
-DEFINITIONS='./definitions'
+
+DEFINITIONS='./definitions'
+RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS=30

README.md

@@ -0,0 +1,13 @@
+# Taurus
+The heart of the execution block - the runtime itself
+
+- Execute Flows & handles test executions
+- Requests single node executions from Actions
+- Serves the standard CodeZero library
+
+## Used Technologies
+
+[Rust](https://www.rust-lang.org/) x [Tonic](https://docs.rs/tonic/latest/tonic/)
+
+## Contribute / Setup
+Read the [Installation Guide](https://docs.code0.tech/taurus/installation/) if you want to deploy a Taurus instance or see the [Development Guide](https://docs.code0.tech/taurus/dev/) if you want to contribute.

crates/taurus/src/app/mod.rs

@@ -135,12 +135,12 @@ async fn setup_dynamic_services_if_needed(
             .await;
     }
 
-    let runtime_status_heartbeat_task = if config.adapter_status_update_interval_seconds > 0 {
+    let runtime_status_heartbeat_task = if config.runtime_status_update_interval_seconds > 0 {
         let status_service = runtime_status_service
             .as_ref()
             .expect("runtime status service should exist in dynamic mode")
             .clone();
-        let update_interval_seconds = config.adapter_status_update_interval_seconds;
+        let update_interval_seconds = config.runtime_status_update_interval_seconds;
 
         let handle = tokio::spawn(async move {
             let mut interval = tokio::time::interval(Duration::from_secs(update_interval_seconds));

crates/taurus/src/config/mod.rs

@@ -1,15 +1,18 @@
 use code0_flow::flow_config::env_with_default;
+use code0_flow::flow_config::environment::Environment;
 use code0_flow::flow_config::mode::Mode;
 
 /// Struct for all relevant `Taurus` startup configurations
 pub struct Config {
-    /// Aquila mode
+    pub environment: Environment,
+    /// Taurus mode
     ///
     /// Options:
     /// `static` (default)
     /// `hybrid`
     pub mode: Mode,
 
+    /// URL to the NATS service
     pub nats_url: String,
 
     pub aquila_url: String,
@@ -26,7 +29,7 @@ pub struct Config {
 
     /// Runtime status heartbeat interval in seconds while Taurus is running.
     /// Set to 0 to disable periodic heartbeat updates.
-    pub adapter_status_update_interval_seconds: u64,
+    pub runtime_status_update_interval_seconds: u64,
 }
 
 /// Implementation for all relevant `Aquila` startup configurations
@@ -36,6 +39,7 @@ pub struct Config {
 impl Config {
     pub fn new() -> Self {
         Config {
+            environment: env_with_default("ENVIRONMENT", Environment::Development),
             mode: env_with_default("MODE", Mode::DYNAMIC),
             nats_url: env_with_default("NATS_URL", String::from("nats://localhost:4222")),
             aquila_url: env_with_default("AQUILA_URL", String::from("http://localhost:50051")),
@@ -44,8 +48,8 @@ impl Config {
             grpc_host: env_with_default("GRPC_HOST", "127.0.0.1".to_string()),
             grpc_port: env_with_default("GRPC_PORT", 50051),
             definitions: env_with_default("DEFINITIONS", String::from("./definitions")),
-            adapter_status_update_interval_seconds: env_with_default(
-                "ADAPTER_STATUS_UPDATE_INTERVAL_SECONDS",
+            runtime_status_update_interval_seconds: env_with_default(
+                "RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS",
                 30_u64,
             ),
         }

docs/dev.md

@@ -0,0 +1,160 @@
+---
+title: Taurus Development Guide
+---
+
+This guide is for contributors working on Taurus itself.
+It documents how Taurus is structured, how execution flows through the runtime, and how to run and test changes locally.
+
+## What Taurus Does
+
+Taurus is the execution runtime in the CodeZero execution block.
+
+- Consumes flow execution requests from NATS (`execution.*`)
+- Executes flow graphs via `taurus-core::runtime::engine::ExecutionEngine`
+- Emits lifecycle events to NATS (`runtime.emitter.<execution_id>`)
+- Delegates remote nodes to external services over NATS (`action.<service>.<execution_id>`)
+- Reports runtime status and usage to Aquila in dynamic mode
+
+## Workspace Layout
+
+| Path | Purpose |
+| --- | --- |
+| `crates/taurus` | Main runtime binary (startup, config, NATS worker, dynamic integrations) |
+| `crates/taurus-core` | Execution engine, compiler, runtime functions, errors, tracing |
+| `crates/taurus-provider` | Transport adapters (NATS emitter + NATS remote runtime) |
+| `crates/taurus-manual` | Manual CLI executor for running a single validation flow file |
+| `crates/taurus-tests` | Local execution-suite runner for JSON flow fixtures under `flows/` |
+| `flows/` | Example/validation flow cases used by `taurus-tests` |
+
+## Runtime Flow
+
+```mermaid
+graph TD
+  NATS[NATS]
+  Taurus[Taurus Runtime\ncrates/taurus]
+  Core[ExecutionEngine\ncrates/taurus-core]
+  Emitter[Runtime Emitter\ncrates/taurus-provider]
+  Remote[Remote Runtime Adapter\ncrates/taurus-provider]
+  Service[Remote Service / Action Runtime]
+  Aquila[Aquila gRPC APIs\n(dynamic mode only)]
+
+  NATS -->|execution.*| Taurus
+  Taurus --> Core
+  Core --> Emitter
+  Emitter -->|runtime.emitter.<execution_id>| NATS
+  Core --> Remote
+  Remote -->|action.<service>.<execution_id>| NATS
+  NATS --> Service
+  Taurus -->|runtime status + usage| Aquila
+```
+
+### Execution details
+
+1. Taurus subscribes to queue subject `execution.*` with queue group `taurus`.
+2. Incoming payload is decoded as `tucana::shared::ExecutionFlow`.
+3. `ExecutionEngine::execute_flow_with_execution_id(...)` compiles and executes nodes.
+4. Local nodes run handlers from the built-in function registry.
+5. Non-local `definition_source` values are executed remotely via `RemoteRuntime`.
+6. Lifecycle events are emitted as `starting`, `ongoing`, `finished`, or `failed`.
+
+## Runtime Modes
+
+Taurus mode is controlled by `MODE`.
+
+### `dynamic`
+
+`dynamic` enables control-plane integrations:
+
+- Sends definitions to Aquila (retry loop until success)
+- Starts runtime status reporting (including heartbeat)
+- Sends runtime usage updates after each flow run
+
+### `static`
+
+`static` disables those control-plane interactions.
+
+- Taurus still executes flows from NATS
+- No definition push
+- No runtime status updates
+- No runtime usage updates
+
+## Environment Variables
+
+Defaults are defined in `crates/taurus/src/config/mod.rs`.
+
+| Name | Description | Default |
+| --- | --- | --- |
+| `ENVIRONMENT` | Running env | `development` |
+| `MODE` | Runtime mode (`dynamic` or `static`) | `dynamic` |
+| `NATS_URL` | NATS connection URL | `nats://localhost:4222` |
+| `AQUILA_URL` | Aquila gRPC endpoint (used in dynamic mode) | `http://localhost:50051` |
+| `AQUILA_TOKEN` | Auth token for Aquila runtime APIs | `token` |
+| `WITH_HEALTH_SERVICE` | Enables gRPC health server | `false` |
+| `GRPC_HOST` | Health server host | `127.0.0.1` |
+| `GRPC_PORT` | Health server port | `50051` |
+| `DEFINITIONS` | Path sent to `FlowUpdateService` for definition sync | `./definitions` |
+| `RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS` | Heartbeat interval in dynamic mode (`0` disables heartbeat) | `30` |
+
+## Local Development
+
+### 1. Start dependencies
+
+At minimum, start a reachable NATS instance at `NATS_URL`.
+
+### 2. Configure environment
+
+Create `.env` in the repository root (you can copy from `.env-example` and extend it).
+
+### 3. Run Taurus
+
+```bash
+cargo run -p taurus
+```
+
+### 4. Run the execution suite
+
+```bash
+cargo run -p tests
+```
+
+This executes all JSON files in `./flows` and compares runtime outputs.
+
+### 5. Run one flow manually
+
+```bash
+cargo run -p manual -- --path ./flows/01_return_object.json --index 0 --nats-url nats://127.0.0.1:4222
+```
+
+This is useful when debugging one case or remote-execution behavior.
+
+## Testing
+
+- Core unit/integration tests:
+
+```bash
+cargo test -p taurus-core
+```
+
+- Full workspace checks (recommended before merge):
+
+```bash
+cargo test
+```
+
+## Extending Taurus
+
+### Add or modify built-in functions
+
+- Implement handler logic in `crates/taurus-core/src/runtime/functions/*`
+- Register function IDs via the `FUNCTIONS` arrays
+- Registration is aggregated through `ALL_FUNCTION_SETS` in `runtime/functions/mod.rs`
+
+### Remote execution routing rule
+
+In the compiler, a node is treated as local when `definition_source` is:
+
+- empty
+- `taurus`
+- prefixed with `draco`
+
+Any other source is routed as remote execution to that service name.

docs/index.mdx

@@ -1,7 +1,17 @@
 ---
-title: Welcome to the Documentation for Taurus
-description: Find out how the execution works
+title: Welcome to Taurus Documentation
+description: Learn how Taurus works and how to build with it
 template: splash
 ---
 
-Taurus executes Flows.
+## What is Taurus?
+
+Taurus runs inside the execution block and serves as the runtime itself.
+It handles flow execution requests and requests single node executions from Actions.
+
+---
+
+If you want to work on or with Taurus, start here:
+
+- **[Setup Guide](installation.mdx)**: install and configure Aquila for local or containerized use.
+- **[Development Guide](dev.md)**: runtime architecture

docs/installation.mdx

@@ -0,0 +1,105 @@
+---
+title: Taurus Installation Guide
+---
+
+import {Step, Steps} from 'fumadocs-ui/components/steps';
+
+Use this guide to install and configure Taurus.
+
+## Setup Options
+
+### Using Docker Compose
+
+Use Docker Compose to run Taurus and related services.
+If you are developing Taurus locally, make sure the Taurus container is stopped to avoid port conflicts.
+If your compose setup supports profiles, you can set `COMPOSE_PROFILES=ide` to run only
+IDE-related services and start Taurus manually.
+
+### Virtual Development Environment (Preferred)
+
+Use the shared environment setup from the main platform docs:
+
+- [Visit Setup Guide](https://docs.code0.tech/general/install/)
+
+### Manual Installation
+
+<Steps>
+
+<Step>
+
+#### **Clone Taurus**
+
+Clone this repository to your local machine.
+
+</Step>
+
+<Step>
+
+#### **Set up environment variables**
+
+Configure `.env` in the project root with the required settings.
+You can use `.env-example` as a starting point.
+
+</Step>
+
+<Step>
+
+#### **Ensure required services are running**
+
+**NATS**:
+
+- Ensure a NATS instance is reachable
+- Enable JetStream
+- See [NATS installation docs](https://docs.nats.io/running-a-nats-service/introduction/installation)
+
+**Aquila**:
+
+- Required for dynamic mode (`MODE=dynamic`)
+- Ensure the configured endpoint is reachable
+
+</Step>
+
+<Step>
+
+#### **Start Taurus**
+
+Run:
+
+```bash
+cargo run -p taurus
+```
+
+</Step>
+
+</Steps>
+---
+
+## Environment Variables
+
+Taurus configuration is split into shared variables and mode-specific variables.
+
+### Common (Static + Dynamic)
+
+| Name                  | Description                                                                                                  | Default                         |
+|-----------------------|--------------------------------------------------------------------------------------------------------------|---------------------------------|
+| `MODE`                | Runtime mode. `static` loads local flows. `dynamic` enables dynamic synchronization with Sagittarius.        | `static`                        |
+| `ENVIRONMENT`         | Runtime environment (`development`, `staging`, `production`).                                                | `development`                   |
+| `NATS_URL`            | URL of the NATS instance Aquila connects to.                                                                 | `nats://localhost:4222`         |
+| `AQUILA_URL`          | URL of the Aquila instance .                                                                                 | `nats://localhost:4222`         |
+| `AQUILA_TOKEN`        | Token to authenticate agains Aquila.                                                                 | `nats://localhost:4222`         |
+| `GRPC_HOST`           | Hostname for the Taurus gRPC server.                                                                         | `127.0.0.1`                     |
+| `GRPC_PORT`           | Port for the Taurus gRPC server.                                                                             | `50051`                          |
+| `WITH_HEALTH_SERVICE` | Enables the gRPC health service when set to `true`.                                                          | `false`                         |
+
+### Dynamic Mode
+
+Set `MODE=dynamic` when the IDE is required/needed.
+
+| Name              | Description                                                                       | Default                  |
+|-------------------|-----------------------------------------------------------------------------------|--------------------------|
+| `AQUILA_URL` | URL of the Aquila instance. | `http://localhost:50051` |
+| `AQUILA_TOKEN`   | Token used by Taurus to authenticate with Aquila.                            | `token`  |
+| `DEFINITIONS` | Path to the runtime definition modules. | `./definitions` |
+| `RUNTIME_STATUS_UPDATE_INTERVAL_SECONDS` | Interval (in seconds) of updating the current runtime status. | `30s` |
+
+