robot_lab-cyborg 0.2.7

data/docs/api_reference.md

@@ -0,0 +1,301 @@
+# API Reference
+
+Every public class and method in `robot_lab-cyborg`, grouped by concern. See [How It Works](how_it_works.md) for the concepts behind each one.
+
+## `RobotLab::Cyborg`
+
+### Constructor
+
+#### `new(name:, bus: nil, channel: nil, interviewer: nil, auto_reply: true, memory: nil, ask_timeout: nil)`
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `name` | `String` | *(required)* | unique peer name — also the bus channel name |
+| `bus` | `TypedBus::MessageBus`, `nil` | `nil` | shared bus to join immediately |
+| `channel` | `Channel`, `nil` | `Channel::Terminal.new(name: name)` | means of reaching the human |
+| `interviewer` | `Interviewer`, `nil` | `Interviewer.new(channel:, default_timeout: ask_timeout)` | the interaction process (inject `channel:` instead, in almost all cases) |
+| `auto_reply` | `Boolean` | `true` | reply to inbound bus tasks automatically once the human answers |
+| `memory` | `RobotLab::Memory`, `nil` | a fresh `Memory.new` | standalone memory used outside a network |
+| `ask_timeout` | `Numeric`, `nil` | `nil` (wait indefinitely) | seconds to wait for the human before falling back to a default |
+
+```ruby
+dewayne = RobotLab::Cyborg.new(name: "dewayne")
+dewayne = RobotLab::Cyborg.new(name: "dewayne", bus: bus, ask_timeout: 30)
+```
+
+### Attributes
+
+| Reader | Type | Description |
+|---|---|---|
+| `name` | `String` | peer name / bus channel name |
+| `bus` | `TypedBus::MessageBus`, `nil` | the shared bus, if any |
+| `outbox` | `Hash` | messages this peer has sent, keyed by message key — `{status:, message:, replies:}` |
+| `channel` | `Channel` | the injected means of reaching the human |
+| `interviewer` | `Interviewer` | the process conducting this peer's human interaction |
+| `memory` | `RobotLab::Memory` | this peer's own standalone memory |
+| `presence` | `Symbol` | `:online`, `:away`, or `:offline` |
+
+### Network Member Interface
+
+#### `call(result) → SimpleFlow::Result`
+
+The `SimpleFlow` step contract — invoked by the network when a pipeline reaches this peer's task. Extracts the message and shared memory from `result`, calls `#run`, and threads the resulting `RobotResult` back into the pipeline. Exceptions are caught and turned into an error-shaped `RobotResult` rather than raised.
+
+#### `run(message = nil, network_memory: nil, memory: nil, **) → RobotResult`
+
+Asks the human `message` and wraps the answer in a `RobotResult` — the contract that makes a `Cyborg` a valid `delegate`/pipeline target anywhere a `Robot` is. Attaches `network_memory` automatically when given.
+
+### Asking the Human
+
+#### `ask(question, choices: nil, default: nil, timeout: @ask_timeout, validate: nil, retries: 2) → Object, nil`
+
+Blocks for the human's answer (or `default`/`nil` on timeout). `validate:` is called with the raw answer; return a coerced value to accept it, or `nil` to reject and re-ask (up to `retries` extra attempts, then fall back to `default`).
+
+```ruby
+cyborg.ask("Deploy now?")
+cyborg.ask("Pick one", choices: %w[a b c])
+cyborg.ask("Env?", validate: ->(a) { %w[dev prod].include?(a) ? a : nil })
+```
+
+#### `ask_int(question, **) → Integer, nil`
+
+`ask` with a validator that re-asks until the human gives a parseable integer (`Integer(str, exception: false)`).
+
+#### `ask_confirm(question, **) → Boolean, nil`
+
+`ask` with `choices: %w[yes no]` and a validator mapping `y`/`yes`/`true`/`1` → `true`, `n`/`no`/`false`/`0` → `false` (case-insensitive).
+
+#### `ask_async(question, choices: nil, default: nil) → Question`
+
+Delivers the question and returns immediately with the pending `Question`, instead of blocking.
+
+### Callbacks
+
+#### `on_task(&block) → self`
+
+Fires `block.call(message, answer)` after the human answers an inbound bus task.
+
+#### `on_human(&block) → self`
+
+Fires `block.call(channel_message)` when the human sends something unprompted — a channel message answering no outstanding question.
+
+### Talking to the Human
+
+#### `tell(text, kind: :notice) → self`
+
+Pushes `text` out to the human over the channel, unprompted — the network → human half of the duplex.
+
+#### `converse(peers: []) → Conversation`
+
+Starts (`Conversation.new(cyborg: self, peers:).start`) and returns an interactive `Conversation`: the human addresses peers by `@mention`, replies return automatically.
+
+#### `listen → self`
+
+Keeps the interviewer's consumer alive with no question outstanding, so unprompted human input is captured as initiative. Idempotent.
+
+#### `unlisten → self`
+
+Stops always-on listening.
+
+### Presence
+
+#### `available? → Boolean`
+
+`true` unless `presence == :offline`.
+
+#### `online! → self`
+
+Sets presence to `:online` (default) — taking work now.
+
+#### `away! → self`
+
+Sets presence to `:away` — still asked, but callers should use a bounded timeout.
+
+#### `offline! → self`
+
+Sets presence to `:offline` — inbound bus tasks are declined immediately instead of waiting on an absent human.
+
+### Issuing Work to Other Members
+
+#### `assign(to:, task:) → RobotMessage`
+
+Fire-and-forget bus send — alias for `BusMessaging#send_message`. Correlate any reply later via `outbox[message.key]`.
+
+#### `delegate(to:, task:, async: false, **) → RobotResult, DelegationFuture`
+
+`to` may be a `Robot` or another `Cyborg` — anything responding to `#run`. Synchronous by default (blocks, returns a `RobotResult` stamped with `delegated_by`); `async: true` spawns a thread and returns a `RobotLab::DelegationFuture` immediately (`future.value` / `future.value(timeout:)` blocks later; raises `DelegationFuture::DelegationTimeout` on expiry).
+
+### Shared Memory
+
+#### `remember(key, value) → value`
+
+Writes to the active memory (network shared memory when attached, else this peer's own).
+
+#### `recall(key, wait: false) → Object, nil`
+
+Reads from the active memory. `wait:` may be `false`, `true` (block indefinitely), or a `Numeric` numbers of seconds.
+
+#### `attach_memory(mem) → self`
+
+Points `remember`/`recall` at `mem` — a network run does this automatically when it starts.
+
+#### `detach_memory → self`
+
+Returns to this peer's own standalone memory.
+
+### Inspection
+
+#### `inbox → Array<RobotMessage>`
+
+Inbound bus messages received so far, oldest first (a defensive copy).
+
+#### `to_h → Hash`
+
+`{name:, kind: :cyborg, bus: true|nil, channel: "Channel::ClassName"}.compact`
+
+### Bus Methods (via `RobotLab::Robot::BusMessaging`)
+
+`Cyborg` includes `RobotLab::Robot::BusMessaging` verbatim, gaining `send_message`, `send_reply`, `spawn`, `with_bus`, and `assign_bus_poller`. **Do not call `on_message`, `respond_to_tasks`, or `serve` on a `Cyborg`** — all three replace the inbound message handler wholesale, which disables the built-in ask/auto-reply flow. See [How It Works](how_it_works.md#network-member-and-bus-contracts).
+
+### Errors
+
+#### `Cyborg::Error`
+
+Raised for `Cyborg`-specific misuse. Not currently raised by any code path in this gem's own methods — reserved for future use and for extensions built on top of `Cyborg`.
+
+---
+
+## `RobotLab::Cyborg::Channel`
+
+The abstract base class for the *means* of reaching a human. Subclass and implement `#deliver`/`#receive` to bridge to a new transport — see [Building Custom Channels](custom_channels.md).
+
+| Method | Signature | Description |
+|---|---|---|
+| `deliver` | `deliver(message) → ChannelMessage` | send a message out to the human (network → human). Must be implemented by subclasses. |
+| `receive` | `receive(timeout: nil) → ChannelMessage, nil` | return the next message from the human, waiting up to `timeout` seconds; `nil` on timeout (transient — not "closed"). Must be implemented by subclasses. |
+| `correlates?` | `→ Boolean` | whether inbound answers are tagged with the question they reply to. Default `false`. |
+| `close` | `→ void` | release resources. Default no-op. |
+
+### `Channel::Terminal`
+
+`Terminal.new(input: $stdin, output: $stdout, name: "cyborg")` — the human at a keyboard; the default channel when none is injected. `deliver` prints `[sender] content`, followed by `> ` for questions. `receive(timeout:)` honors the timeout via `IO#wait_readable` on a real IO (a `StringIO` in tests responds immediately). `correlates?` is `false`.
+
+### `Channel::Scripted`
+
+`Scripted.new(answers = [])` — canned answers consumed in order; `correlates?` is `true`. `#asked` (`Array<String>`) records every question shown, in order — useful for asserting what the human saw in tests.
+
+```ruby
+scripted = RobotLab::Cyborg::Channel::Scripted.new(["yes", "ship it"])
+bot = RobotLab::Cyborg.new(name: "dewayne", channel: scripted)
+# ... run something that asks two questions ...
+scripted.asked   # => ["first question text", "second question text"]
+```
+
+---
+
+## `RobotLab::Cyborg::ChannelMessage`
+
+```ruby
+ChannelMessage = Data.define(:id, :content, :in_reply_to, :sender, :kind, :at)
+```
+
+Constructed as `ChannelMessage.new(content:, id: nil, in_reply_to: nil, sender: nil, kind: :message, at: nil)` — `at` defaults to `Time.now`. `#question?` returns `true` when `kind == :question`.
+
+---
+
+## `RobotLab::Cyborg::Interviewer`
+
+The process that conducts a human interaction over an injected `Channel`. See [How It Works](how_it_works.md#asking-asynchronously) for the full asking/correlation/timeout model.
+
+#### `new(channel:, default_timeout: nil)`
+
+#### `ask(content, choices: nil, default: nil) → Question`
+
+Delivers the question (immediately on a correlating channel, or queued behind a serialized one) and returns a pending `Question` without blocking.
+
+#### `ask_and_wait(content, timeout: @default_timeout, **) → String, nil`
+
+`ask(**).answer(timeout:)` — the synchronous form.
+
+#### `on_initiative(&block) → self`
+
+Registers the handler for inbound messages that answer no outstanding question.
+
+#### `listen → self` / `unlisten → self`
+
+Keep the consumer alive with nothing outstanding (or let it wind down again).
+
+#### `close → void`
+
+Stops the consumer and closes the channel.
+
+#### `expire(question) → void`
+
+Removes `question` from the outstanding set and advances a serialized queue. Called by `Question#answer` on timeout — not normally called directly.
+
+#### `last_error → StandardError, nil`
+
+The last error a handler or channel raised inside the consumer loop (caught, not re-raised, so the consumer keeps running).
+
+---
+
+## `RobotLab::Cyborg::Question`
+
+A pending question handed to the human; a one-shot future for its answer.
+
+| Reader | Type | Description |
+|---|---|---|
+| `id` | `Integer` | correlation id, unique within an `Interviewer` |
+| `content` | `String` | the question text |
+| `choices` | `Array<String>`, `nil` | multiple-choice options, if any |
+| `default` | `String`, `nil` | value used on an empty answer or a timeout |
+
+#### `answer(timeout: nil) → String, nil`
+
+Blocks up to `timeout` seconds for the human's (already-interpreted) answer. On timeout, expires the question via its `Interviewer` and returns `default` (`nil` if none).
+
+#### `resolve(answer) → void`
+
+Delivers the answer — called by the `Interviewer`'s consumer, not normally called directly.
+
+---
+
+## `RobotLab::Cyborg::Conversation`
+
+Turns a listening `Cyborg` into a multi-peer, `@mention`-addressed chat participant. See [How It Works](how_it_works.md#conversation-multi-peer-chat-by-mention).
+
+#### `new(cyborg:, peers: [])`
+
+#### `peers → Array<String>`
+
+The addressable roster.
+
+#### `add_peer(name) → self`
+
+Adds an addressable peer.
+
+#### `start → self`
+
+Registers `on_human` routing and calls `cyborg.listen`. Idempotent.
+
+#### `stop → self`
+
+Calls `cyborg.unlisten`.
+
+#### `route(line) → Array<String>`
+
+Routes one line of human input by `@mention` (fan-out to every mentioned peer; no mention → broadcast to all known peers) and returns the names it was actually sent to. Unknown mentions are reported back to the human and excluded; a line with no resolvable recipient sends nothing.
+
+---
+
+## Related Core Classes (from `robot_lab`, not this gem)
+
+Used throughout this gem's public API but defined in core `robot_lab` — see that gem's docs for full detail:
+
+| Class | Relevance here |
+|---|---|
+| `RobotLab::RobotResult` | what `Cyborg#run`/`#call` return; `#reply` is the human's answer text |
+| `RobotLab::DelegationFuture` | returned by `delegate(async: true)`; `DelegationFuture::DelegationTimeout` on a `value(timeout:)` expiry |
+| `RobotLab::Robot::BusMessaging` | mixed into `Cyborg` for bus send/receive; see the caveat above about `on_message`/`respond_to_tasks`/`serve` |
+| `RobotLab::Memory` | `remember`/`recall`'s backing store; `#current_writer=` is what `with_writer` toggles around a memory write |
+| `RobotLab::RobotMessage` | the bus message type `assign`/`send_message` produce and `#inbox` holds |

data/docs/custom_channels.md

@@ -0,0 +1,123 @@
+# Building Custom Channels
+
+`Channel::Terminal` and `Channel::Scripted` are the only channels this gem ships, but the whole point of the `Channel` abstraction is that a Slack, email, SMS, or web-form transport is *just another subclass* — nothing in `Cyborg`, `Interviewer`, or `Conversation` assumes a terminal. This page covers what a custom channel needs to get right.
+
+## The Contract
+
+Subclass `RobotLab::Cyborg::Channel` and implement two methods:
+
+```ruby
+class MyChannel < RobotLab::Cyborg::Channel
+  def deliver(message)   # ChannelMessage -> ChannelMessage
+    # send `message.content` out to the human, over whatever transport this is.
+    # Return the message (or a copy of it) once sent.
+  end
+
+  def receive(timeout: nil)   # -> ChannelMessage, nil
+    # Wait up to `timeout` seconds for the human's next message.
+    # Return nil if nothing arrives in that window — nil means "not yet",
+    # not "closed"; the Interviewer will call #receive again.
+  end
+end
+```
+
+Override two more only if they apply:
+
+```ruby
+def correlates? = true   # default: false — see "Correlation" below
+def close                # default: no-op — release sockets, files, etc. here
+end
+```
+
+## `#receive` Must Honor `timeout:`
+
+This is the one requirement that's easy to get wrong. The `Interviewer`'s background consumer calls `channel.receive(timeout: 0.05)` in a tight loop (`Interviewer::POLL_INTERVAL`), and relies on that call actually returning within roughly that window — every 50ms — so it can notice `Question` timeouts, respond to `#close`, and stay responsive. A `#receive` that blocks indefinitely regardless of `timeout:` will make questions never expire and `#close` hang.
+
+For a polling-style transport (an HTTP API you poll, a database table), implement this literally: poll, and if nothing new has arrived within `timeout` seconds, return `nil`. For a push-style transport (a webhook, a queue with blocking pop), buffer inbound messages into a `Thread::Queue` from your webhook handler and let `receive` do `@inbox.pop(timeout: timeout)` — exactly what `Channel::Scripted` and the `Autobot` example below do.
+
+## Correlation
+
+Whether `correlates?` should be `true` or `false` depends on whether your transport can tie an inbound answer back to the specific question it answers:
+
+- **Slack threads** — reply in the same thread as the question; the thread's parent message id becomes `in_reply_to`. `correlates? = true`.
+- **Email** — the `In-Reply-To` header names the message id being answered. `correlates? = true`.
+- **A bare terminal, or an SMS number with no threading** — there's no way to tell which question an inbound text answers except "whichever one is outstanding." `correlates? = false` — the `Interviewer` will serialize (one question on the wire at a time) so an answer is never mis-attributed. See [How It Works — Correlation vs. Serialization](how_it_works.md#correlation-vs-serialization).
+
+Get this wrong in the `true` direction (claiming correlation your transport doesn't actually have) and answers can resolve the wrong question when more than one is outstanding. Getting it wrong in the `false` direction just costs you unnecessary serialization — safe, but limits concurrent questions on a channel that could actually support them.
+
+## A Worked Example: an Automated Peer
+
+Every peer on the bus — human or otherwise — is reached through a `Channel`, which means a scripted or programmatic "human" is just a `Channel` whose deliver/receive are backed by a block instead of a person. This is exactly how `examples/02_terminal_mentions.rb` builds key-free canned peers that still go through the real `Cyborg`/`Interviewer` machinery:
+
+```ruby
+class Autobot < RobotLab::Cyborg::Channel
+  def initialize(&reply)
+    @reply = reply
+    @inbox = Thread::Queue.new
+    super()
+  end
+
+  def correlates? = true
+  def deliver(message) = message.question? ? @inbox.push(reply_to(message)) : message
+  def receive(timeout: nil) = timeout ? @inbox.pop(timeout: timeout) : @inbox.pop
+  def close = @inbox.close
+
+  private
+
+  def reply_to(message)
+    RobotLab::Cyborg::ChannelMessage.new(content: @reply.call(message.content), in_reply_to: message.id, kind: :answer)
+  end
+end
+
+analyst = RobotLab::Cyborg.new(name: "analyst", bus: bus,
+                                channel: Autobot.new { |_question| "error rate is 0.2% over the last hour." })
+```
+
+Notice what `Autobot` does *not* need to know about: bus wiring, reply correlation logic beyond stamping `in_reply_to`, or anything about questions vs. answers as concepts — that's the `Interviewer`'s job. It only has to answer "how do I move a `ChannelMessage` across this boundary."
+
+## Sketch: a Slack Channel
+
+A real Slack channel is push-style (events arrive via the Events API or Socket Mode) and does correlate (thread replies):
+
+```ruby
+class SlackChannel < RobotLab::Cyborg::Channel
+  def initialize(slack_client:, channel_id:)
+    @slack   = slack_client
+    @channel_id = channel_id
+    @inbox   = Thread::Queue.new
+    super()
+  end
+
+  def correlates? = true
+
+  def deliver(message)
+    response = @slack.chat_postMessage(channel: @channel_id, text: message.content,
+                                        thread_ts: message.in_reply_to)
+    message   # or a copy carrying response["ts"] if you need the posted id later
+  end
+
+  def receive(timeout: nil)
+    timeout ? @inbox.pop(timeout: timeout) : @inbox.pop
+  end
+
+  def close
+    @inbox.close
+  end
+
+  # Called from your Slack event handler / webhook controller, on whatever
+  # thread that framework hands events to you on:
+  def handle_slack_event(event)
+    @inbox.push(RobotLab::Cyborg::ChannelMessage.new(
+      content: event["text"],
+      in_reply_to: event["thread_ts"],   # nil for a top-level message
+      sender: event["user"]
+    ))
+  end
+end
+```
+
+The pattern generalizes directly to email (`In-Reply-To`/`Message-Id` headers instead of Slack thread timestamps), a web form (poll a table of submitted answers, or push from a controller action the same way), or an SMS/queue transport.
+
+## Testing a Custom Channel
+
+Give it the same treatment `test/robot_lab/test_interviewer.rb`'s `Probe` channel gets: a hand-driven channel whose `receive` you control from the test, so you can push messages (correlated or not) in whatever order you want and assert on what the `Interviewer`/`Cyborg` did with them, without depending on real network/IO timing.

data/docs/getting_started.md

@@ -0,0 +1,156 @@
+# Getting Started
+
+## Prerequisites
+
+- Ruby 3.2+ (per the gemspec's `required_ruby_version`)
+- `robot_lab` `~> 0.2`, `>= 0.2.6` — `robot_lab-cyborg` needs the `respond_to_tasks`/`serve` and shared bus-mutex additions to `RobotLab::Robot::BusMessaging` that landed at that version, and `RobotLab::Memory#current_writer=`.
+- `robot_lab` must be `require`d before `robot_lab/cyborg` (`Cyborg` includes `RobotLab::Robot::BusMessaging` and calls `RobotLab.register_extension`, both of which must already be defined).
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "robot_lab"
+gem "robot_lab-cyborg"
+```
+
+Then:
+
+```sh
+bundle install
+```
+
+Or install directly:
+
+```sh
+gem install robot_lab-cyborg
+```
+
+## Creating a Human Peer
+
+```ruby
+require "robot_lab"
+require "robot_lab/cyborg"
+
+# By default, talks to a terminal on $stdin/$stdout.
+dewayne = RobotLab::Cyborg.new(name: "dewayne")
+```
+
+`Cyborg.new` accepts:
+
+| Keyword | Default | Purpose |
+|---|---|---|
+| `name:` | *(required)* | unique peer name — also the bus channel name |
+| `bus:` | `nil` | a `TypedBus::MessageBus` to join immediately |
+| `channel:` | a `Channel::Terminal` on `$stdin`/`$stdout` | the means of reaching the human |
+| `interviewer:` | a fresh `Interviewer` over `channel:` | the process conducting the ask (rarely overridden directly — inject `channel:` instead) |
+| `auto_reply:` | `true` | reply to inbound bus tasks automatically once the human answers |
+| `memory:` | a fresh `RobotLab::Memory` | this peer's own (standalone) memory, used outside a network |
+| `ask_timeout:` | `nil` (wait indefinitely) | seconds to wait for the human before falling back to a default |
+
+## A Human as a Pipeline Step
+
+The human is interchangeable with a robot anywhere a network member is expected — it satisfies the same `call`/`run` contract a `Robot` does:
+
+```ruby
+writer = RobotLab.build(name: "writer", template: :writer)
+
+network = RobotLab.create_network(name: "release") do
+  task :draft,   writer,  depends_on: :none
+  task :approve, dewayne, depends_on: [:draft]   # the human signs off
+end
+
+result = network.run(message: "Draft the release notes")
+result.value.reply   # => the human's answer, same shape as a robot's RobotResult#reply
+```
+
+When the pipeline reaches the human's task, the network calls `dewayne.call(pipeline_result)`, which extracts the incoming message, calls `dewayne.ask(message)`, and wraps the answer in a `RobotResult` so downstream steps can't tell a human answered instead of a robot.
+
+## Peers Messaging Over a Shared Bus
+
+Robots and cyborgs talk to each other by name over one shared bus — the same `TypedBus::MessageBus` a `Robot` would join via `RobotLab.build(bus:)`:
+
+```ruby
+bus     = TypedBus::MessageBus.new
+analyst = RobotLab.build(name: "analyst", bus: bus)
+dewayne = RobotLab::Cyborg.new(name: "dewayne", bus: bus)
+
+# The robot asks the human a question; the human's answer comes back as a reply.
+analyst.send_message(to: :dewayne, content: "Approve the deploy? (yes/no)")
+
+# The human issues work to the robot, too.
+dewayne.assign(to: :analyst, task: "Summarize today's error budget.")
+```
+
+`send_message`/`send_reply`/`on_message` all come from `RobotLab::Robot::BusMessaging`, which `Cyborg` includes — see [How It Works](how_it_works.md#network-member-and-bus-contracts) for the one important caveat about overriding `on_message` on a `Cyborg`.
+
+## Shared Memory
+
+```ruby
+dewayne.remember(:decision, "ship it")   # visible to every member
+dewayne.recall(:sentiment, wait: 30)     # block until a robot writes it
+```
+
+Inside a network run, `remember`/`recall` target the network's shared memory automatically (`attach_memory` is called for you); outside a network, they fall back to the peer's own standalone `memory:`.
+
+## A Minimal, Key-Free Example
+
+Inject a `Channel::Scripted` to run the human side end-to-end with no live terminal and no API keys:
+
+```ruby
+require "robot_lab"
+require "robot_lab/cyborg"
+
+Scripted = RobotLab::Cyborg::Channel::Scripted
+
+approver = RobotLab::Cyborg.new(name: "approver", channel: Scripted.new(["approved: ship it"]))
+
+network = RobotLab.create_network(name: "release") do
+  task :approve, approver, depends_on: :none
+end
+
+result = network.run(message: "Approve the v1.0 release notes?")
+puts result.value.reply                # => "approved: ship it"
+puts approver.channel.asked.first       # => "Approve the v1.0 release notes?"
+```
+
+## Bundled Examples
+
+The gem ships five runnable demos, one feature area each — see the [examples/](https://github.com/MadBomber/robot_lab-cyborg/tree/main/examples) directory:
+
+| Example | Demonstrates | Needs a live human? | Needs an LLM? |
+|---|---|---|---|
+| `01_human_in_the_network.rb` | Pipeline step, bus messaging between two humans, shared memory | No (scripted) | No |
+| `02_terminal_mentions.rb` | Live `@mention` addressing via `Conversation`, a real Ollama robot cooperating via `#serve` | Yes | Optional (canned peers work without it) |
+| `03_robot_interviews_cyborg.rb` | The interview run the *other* way — an LLM robot interviews the human via `delegate`, typed intake (`ask_confirm`/`ask_int`) | Yes | Yes (Ollama) |
+| `04_presence_and_availability.rb` | `online!`/`away!`/`offline!`, an offline human declining immediately, bounded-timeout escalation | No (scripted) | No |
+| `05_listening_and_duplex.rb` | Always-on `listen`: the human speaks unprompted, replies come back on the channel | No (scripted) | No |
+
+```sh
+ruby examples/01_human_in_the_network.rb
+ruby examples/04_presence_and_availability.rb
+ruby examples/05_listening_and_duplex.rb
+
+# Examples 2 and 3 use a real robot on Ollama (ollama pull qwen3.6; override with
+# OLLAMA_MODEL / OLLAMA_API_BASE). In example 2 the canned peers still work
+# without it — only @assistant needs Ollama.
+ruby examples/02_terminal_mentions.rb        # then type: @analyst and @scribe: status?
+ruby examples/03_robot_interviews_cyborg.rb  # the robot asks you the questions
+```
+
+## Development
+
+```sh
+bin/setup                    # install dependencies
+bundle exec rake test        # run tests
+bundle exec rake quality     # tests + RuboCop + Flog + Flay
+bin/console                  # IRB with the gem loaded
+```
+
+## Key Constraints
+
+- `robot_lab` must be `require`d before `robot_lab/cyborg` — see Prerequisites above.
+- `$stdin`/`$stdout` are only ever touched inside `Channel::Terminal`; every other part of the gem is transport-agnostic.
+- A human step holds a thread while it waits for an answer (`ask`/`ask_and_wait` block the calling thread; `ask_async` does not — see [How It Works](how_it_works.md#asking-asynchronously)). There is currently no way to persist a pending question across a process restart — see the [Durable Human Steps](how_it_works.md#roadmap-durable-human-steps) roadmap note.
+- Calling `on_message`, `respond_to_tasks`, or `serve` (all inherited from `BusMessaging`) on a `Cyborg` replaces its built-in inbound-task handling — see [How It Works](how_it_works.md#network-member-and-bus-contracts).