Documentation + agent context.

Author: ioquatix

context/getting-started.md

@@ -0,0 +1,190 @@
+# Getting Started
+
+This guide explains how to get started with `async-service` to create and run services in Ruby.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+$ bundle add async-service
+```
+
+## Core Concepts
+
+`async-service` has several core concepts:
+
+- A {ruby Async::Service::Generic} which represents the base class for implementing services.
+- A {ruby Async::Service::Configuration} which manages service configurations and environments.
+- A {ruby Async::Service::Controller} which handles starting, stopping, and managing services.
+
+## Usage
+
+Services are long-running processes that can be managed as a group. Each service extends `Async::Service::Generic` and implements a `setup` method that defines how the service runs.
+
+### Basic Service
+
+Create a simple service that runs continuously:
+
+```ruby
+#!/usr/bin/env async-service
+
+require 'async/service'
+
+class HelloService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(count: 1, restart: true) do |instance|
+			instance.ready!
+			
+			while true
+				puts "Hello World!"
+				sleep 1
+			end
+		end
+	end
+end
+
+service "hello" do
+	service_class HelloService
+end
+```
+
+Make the file executable and run it:
+
+```bash
+$ chmod +x hello_service.rb
+$ ./hello_service.rb
+```
+
+### Service Configuration
+
+Services can be configured with custom properties:
+
+```ruby
+service "web-server" do
+	service_class WebServerService
+	port 3000
+	host "localhost"
+end
+```
+
+In your service implementation, you can access these values through the environment and evaluator:
+
+```ruby
+class WebServerService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(count: 1, restart: true) do |instance|
+			# Access the configuration for the service:
+			evaluator = self.environment.evaluator
+			port = evaluator.port
+			host = evaluator.host
+			
+			puts "Starting web server on #{host}:#{port}"
+			instance.ready!
+			
+			# Your web server implementation here
+		end
+	end
+end
+```
+
+### Multiple Services
+
+You can define multiple services in a single configuration file:
+
+```ruby
+#!/usr/bin/env async-service
+
+require 'async/service'
+
+class WebService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(count: 1, restart: true) do |instance|
+			instance.ready!
+			puts "Web service starting..."
+			# Web server implementation
+		end
+	end
+end
+
+class WorkerService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(count: 2, restart: true) do |instance|
+			instance.ready!
+			puts "Worker #{instance.name} starting..."
+			# Background job processing
+		end
+	end
+end
+
+service "web" do
+	service_class WebService
+	port 3000
+	host "localhost"
+end
+
+service "worker" do
+	service_class WorkerService
+end
+```
+
+### Programmatic Usage
+
+You can also create and run services programmatically:
+
+```ruby
+require 'async/service'
+
+configuration = Async::Service::Configuration.build do
+	service "my-service" do
+		service_class MyService
+	end
+end
+
+Async::Service::Controller.run(configuration)
+```
+
+### Accessing Configuration Values
+
+Services have access to their configuration through the environment and evaluator:
+
+```ruby
+class ConfigurableService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(count: 1, restart: true) do |instance|
+			# Clone the evaluator for thread safety
+			evaluator = self.environment.evaluator
+			database_url = evaluator.database_url
+			max_connections = evaluator.max_connections
+			debug_mode = evaluator.debug_mode
+			
+			puts "Database URL: #{database_url}"
+			puts "Max connections: #{max_connections}"
+			puts "Debug mode: #{debug_mode}"
+			
+			instance.ready!
+			
+			# Your service implementation using these values
+		end
+	end
+end
+
+service "configurable" do
+	service_class ConfigurableService
+	database_url "postgresql://localhost/myapp"
+	max_connections 10
+	debug_mode true
+end
+```
+
+The evaluator is a memoized instance of the service's configuration, allowing for efficient access to configuration values throughout the service's lifecycle.

context/index.yaml

@@ -0,0 +1,12 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A service layer for Async.
+metadata:
+  documentation_uri: https://socketry.github.io/async-service/
+  source_code_uri: https://github.com/socketry/async-service.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to get started with `async-service` to create
+    and run services in Ruby.

examples/hello/readme.md

@@ -0,0 +1,71 @@
+# Hello Service Example
+
+This example demonstrates the most basic usage of Async::Service - creating a simple service that prints "Hello World!" every second.
+
+## Running the Example
+
+Make the file executable and run it:
+
+~~~ bash
+$ chmod +x hello.rb
+$ ./hello.rb
+~~~
+
+You should see output like this:
+
+```
+Hello World!
+Hello World!
+Hello World!
+...
+```
+
+Press `Ctrl+C` to stop the service.
+
+## How it Works
+
+The example defines a simple service class:
+
+~~~ ruby
+class SleepService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(count: 1, restart: true) do |instance|
+			instance.ready!
+			
+			while true
+				puts "Hello World!"
+				sleep 1
+			end
+		end
+	end
+end
+~~~
+
+Key points:
+
+- **Inherits from `Async::Service::Generic`**: Provides the basic service interface
+- **Implements `setup(container)`**: Defines how the service runs
+- **Uses `container.run`**: Creates one instance with automatic restart
+- **Calls `instance.ready!`**: Signals the service is ready
+- **Contains the main loop**: The actual service logic
+
+The service is then configured and made available for execution:
+
+~~~ ruby
+service "sleep" do
+	service_class SleepService
+end
+~~~
+
+## What's Next?
+
+Try modifying the example:
+
+- Change the message that gets printed
+- Adjust the sleep interval
+- Add multiple instances by changing `count: 1` to `count: 3`
+- Add environment variables or configuration
+
+For more complex examples, check out the [Getting Started Guide](../../guides/getting-started/).