setup telescopium

.env-example

@@ -1,8 +1,13 @@
 ENVIRONMENT='development'
 MODE='dynamic'
+
 NATS_URL='nats://localhost:4222'
-AQUILA_URL='http://localhost:8080'
+AQUILA_URL='http://localhost:50051'
+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
+
+- Executes flows and 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`
+    /// `dynamic`
     pub mode: Mode,
 
+    /// URL to the NATS service
     pub nats_url: String,
 
     pub aquila_url: String,
@@ -26,16 +29,17 @@ 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
+/// Implementation for all relevant `Taurus` startup configurations
 ///
 /// Behavior:
 /// Searches for the env. file at root level. Filename: `.env`
 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,165 @@
+---
+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
+  crates/taurus]
+  Core[ExecutionEngine
+  crates/taurus-core]
+  Emitter[Runtime Emitter
+  crates/taurus-provider]
+  Remote[Remote Runtime Adapter
+  crates/taurus-provider]
+  Service[Remote Service / Action Runtime]
+  Aquila[Aquila gRPC APIs
+  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.

crates/taurus-core/src/ERROR_CODES.md → docs/errors.md

@@ -1,11 +1,15 @@
-# Taurus Runtime Error Codes
+---
+title: Taurus Error Table
+---
+
+## Taurus Runtime Error Codes
 
 This document is the canonical catalog for runtime error codes emitted by Taurus runtime crates (`taurus-core` and `taurus-provider`).
 
 ## Code Format
 
 - `T-STD-XXXXX`: Errors originating inside standard function implementations under `runtime/functions/*`.
-- `T-CORE-XXXXXX`: Errors originating from core runtime infrastructure (`engine`, `handler`, type conversion, app-layer mapping).
+- `T-CORE-XXXXXX`: Errors originating from core runtime infrastructure.
 - `T-PROV-XXXXXX`: Errors originating from provider integrations (transport adapters, remote runtime connectors).
 
 ## Code Table
@@ -37,4 +41,6 @@ This document is the canonical catalog for runtime error codes emitted by Taurus
 
 ## Provider Note
 
-`taurus-provider` can also forward remote service errors with service-owned codes (for example codes returned inside Aquila `ExecutionResult::Error`). Those are intentionally preserved instead of remapped, so they are not enumerated as static Taurus provider codes here.
+`taurus-provider` can also forward remote service errors with service-owned codes (for example
+codes returned inside Aquila `ExecutionResult::Error`). Those are intentionally preserved instead of remapped,
+so they are not enumerated as static Taurus provider codes here.

docs/index.mdx

@@ -1,7 +1,18 @@
 ---
-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 Taurus for local or containerized use, with Aquila required for dynamic mode.
+- **[Development Guide](dev.md)**: runtime architecture.
+- **[Error Table](errors.md)**: table of possible runtime errors.