robot_lab-discovery 0.2.6

data/docs/api_reference.md

@@ -0,0 +1,164 @@
+# API Reference
+
+Every public class, module, and method in `robot_lab-discovery`. See [How It Works](how_it_works.md) for the concepts and wire-level detail behind each one.
+
+## `RobotLab::Discovery` (module)
+
+Top-level convenience methods — thin delegators to `Browser`, plus the one standalone utility method.
+
+### `browse(timeout: 3) → Array<Result>`
+
+All robots currently visible on the LAN, deduplicated by name. Delegates to `Browser.browse`.
+
+```ruby
+RobotLab::Discovery.browse(timeout: 3).each { |r| puts r.url }
+```
+
+### `find(name, timeout: 5) → Result, nil`
+
+Polls (see [How It Works](how_it_works.md#findname-timeout)) until a robot named `name` appears or `timeout` elapses. Returns `nil` if it never appears. Delegates to `Browser.find`.
+
+### `find_by_capability(cap, timeout: 3) → Array<Result>`
+
+Robots advertising capability `cap`, found by browsing that capability's DNS-SD subtype directly (a real network-level filter, not client-side). Delegates to `Browser.find_by_capability`.
+
+### `list_capabilities(timeout: 3) → Array<String>`
+
+Every capability string currently advertised by any robot on the LAN, deduplicated and sorted alphabetically. Delegates to `Browser.list_capabilities`.
+
+### `dns_label(capability) → String`
+
+Normalizes a free-form capability string into a valid DNS label: downcased, non-alphanumeric runs collapsed to a single hyphen, no leading/trailing hyphen.
+
+```ruby
+RobotLab::Discovery.dns_label("Web Search")        # => "web-search"
+RobotLab::Discovery.dns_label("NLP/Analysis")      # => "nlp-analysis"
+RobotLab::Discovery.dns_label("Web Search / NLP")  # => "web-search-nlp"
+```
+
+### `Error`
+
+`RobotLab::Discovery::Error < StandardError` — raised only by `TxtRecord.validate!` (see below) when a TXT record exceeds its size limits.
+
+---
+
+## `RobotLab::Discovery::Advertiser`
+
+Announces one robot over mDNS.
+
+### `new(name:, port:, path:, hostname: Socket.gethostname, capabilities: [])`
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `name` | `String` | *(required)* | mDNS instance name. Must not contain dots. |
+| `port` | `Integer` | *(required)* | port the robot's server listens on |
+| `path` | `String` | *(required)* | HTTP path to the robot; stored in the TXT record, not validated by this gem |
+| `hostname` | `String` | `Socket.gethostname` | the host to advertise; override on a multi-homed machine |
+| `capabilities` | `Array<String>`, `String` | `[]` | free-form taxonomy terms; coerced to an array of strings |
+
+Only assigns instance variables — no network activity happens until `#start` is called.
+
+### `start → self`
+
+Builds a `ZeroConf::Service` for `Constants::SERVICE_TYPE`, encoding `path:`/`capabilities:` into the TXT record via `TxtRecord.encode` (raises `RobotLab::Discovery::Error` here if the record is too large — see [How It Works](how_it_works.md#size-limits-and-why-they-exist)) and registering one DNS-SD subtype per capability. Spawns the actual service on a background `Thread` and returns `self` immediately — does not block.
+
+### `stop → self`
+
+Stops the `ZeroConf::Service` (sends an mDNS goodbye packet, TTL=0) and joins the background thread before returning — by the time `stop` returns, advertising has fully ended.
+
+### `started? → Boolean`
+
+`true` while the background thread is alive; `false` before `start` or after `stop`.
+
+### Attributes
+
+`name`, `port`, `path`, `hostname`, `capabilities` — all readers, reflecting the values passed to `new`.
+
+---
+
+## `RobotLab::Discovery::Browser` (module)
+
+Stateless class methods that do the actual mDNS browsing and response parsing. `RobotLab::Discovery.browse`/`find`/`find_by_capability`/`list_capabilities` are thin delegators to these.
+
+### `browse(timeout: 3) → Array<Result>`
+
+`ZeroConf.browse(SERVICE_TYPE, timeout:)`, parsed into `Result`s, deduplicated by `name`.
+
+### `find(name, timeout: 5) → Result, nil`
+
+Polls `browse` in ≤1-second increments until `name` matches or `timeout` elapses; `nil` on timeout. See [How It Works](how_it_works.md#findname-timeout) for why this is a real loop, not a single call.
+
+### `find_by_capability(capability, timeout: 3) → Array<Result>`
+
+Browses `"_#{dns_label(capability)}._sub.#{SERVICE_TYPE}"` instead of the base service type.
+
+### `list_capabilities(timeout: 3) → Array<String>`
+
+`browse(timeout:).flat_map(&:capabilities).uniq.sort`.
+
+### `parse_response(response)` *(private — not part of the public API)*
+
+Extracts SRV (`port`, `hostname`, instance name) and TXT (`path`, `capabilities`) data from a raw mDNS response and builds a `Result`. Returns `nil` for a malformed/partial response (missing SRV or missing `path`) rather than raising — this is why callers use `filter_map`, not `map`. Documented here only because `CLAUDE.md` calls it out explicitly: **do not call this directly**; it's an implementation detail of `browse`/`find_by_capability`.
+
+---
+
+## `RobotLab::Discovery::Result`
+
+```ruby
+Result = Data.define(:name, :hostname, :port, :path, :capabilities)
+```
+
+An immutable value object — every field below is a plain reader; there are no writers.
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `String` | mDNS instance name |
+| `hostname` | `String` | fully-qualified `.local` hostname (trailing DNS root dot already stripped) |
+| `port` | `Integer` | port the robot's server listens on |
+| `path` | `String` | HTTP path to the robot |
+| `capabilities` | `Array<String>` | capability taxonomy terms this robot advertises (`[]` if none) |
+
+#### `url → String`
+
+`"http://#{hostname}:#{port}#{path}"`. Always plain HTTP — this gem has no notion of a scheme beyond that; build the URL yourself if a robot serves over HTTPS.
+
+---
+
+## `RobotLab::Discovery::TxtRecord` (module)
+
+Encodes/decodes the DNS TXT record payload. Normally used internally by `Advertiser`/`Browser`; documented publicly because the wire format and size limits are useful to understand when debugging a discovery issue or building a compatible advertiser in another language.
+
+### Constants
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `PATH_KEY` | `"p"` | wire key for the HTTP path |
+| `VERSION_KEY` | `"v"` | wire key for the gem's version at encode time |
+| `CAPABILITIES_KEY` | `"c"` | wire key for the comma-joined capability list |
+| `MAX_STRING_BYTES` | `255` | RFC 1035 §3.3.14 per-string limit — not configurable |
+| `MAX_TOTAL_BYTES` | `1300` | wire-size budget kept under the UDP/Ethernet MTU to avoid fragmentation |
+| `MAX_CAPABILITIES_CONTENT` | `253` | bytes available for the capabilities string's content (`255 - "c".bytesize - "=".bytesize`) |
+
+### `encode(path:, capabilities: []) → Array<String>`
+
+Builds `["p=#{path}", "v=#{VERSION}"]`, appending `"c=#{capabilities.join(',')}"` only when `capabilities` is non-empty, then validates the result via `validate!` (raising `RobotLab::Discovery::Error` on a size violation) before returning it.
+
+### `decode(strings) → Hash`
+
+Parses an array of `"key=value"` strings (splitting on the *first* `=` only, so a value itself containing `=` round-trips correctly) into `{path:, rl_version:, capabilities:}`. Unknown keys are silently ignored. `:capabilities` is only present in the returned hash when a `c=` entry existed — absent, not `[]`, when there wasn't one.
+
+### `validate!(strings) → Array<String>`
+
+Raises `RobotLab::Discovery::Error` if any single string exceeds `MAX_STRING_BYTES`, or if the total wire size (`sum of (1 + bytesize)` across all strings, accounting for each string's length-prefix byte) exceeds `MAX_TOTAL_BYTES`. Returns `strings` unchanged when valid. Called internally by `encode`; exposed publicly for callers who build TXT string arrays some other way.
+
+---
+
+## `RobotLab::Discovery::Constants` (module)
+
+### `SERVICE_TYPE`
+
+```ruby
+RobotLab::Discovery::Constants::SERVICE_TYPE  # => "_robot-lab._tcp.local."
+```
+
+The one DNS-SD service type every robot registers under, regardless of name or capabilities.

data/docs/getting_started.md

@@ -0,0 +1,114 @@
+# Getting Started
+
+## Prerequisites
+
+- Ruby 3.2+ (per the gemspec's `required_ruby_version`)
+- A multicast-capable network interface — standard on any LAN. `zeroconf` is pure Ruby and implements mDNS itself over standard UDP multicast sockets; it does not wrap Bonjour, Avahi, or any system mDNS daemon, so there is nothing else to install.
+- No dependency on core `robot_lab` — this gem works completely standalone. If `RobotLab` (core) happens to be loaded, `robot_lab-discovery` self-registers as an extension via `RobotLab.register_extension(:discovery, ...)`; if it isn't, nothing changes.
+
+## Installation
+
+```sh
+bundle add robot_lab-discovery
+```
+
+Or add to your `Gemfile` directly:
+
+```ruby
+gem "robot_lab-discovery"
+```
+
+Then:
+
+```sh
+bundle install
+```
+
+## Advertising a Robot
+
+```ruby
+require "robot_lab/discovery"
+
+adv = RobotLab::Discovery::Advertiser.new(
+  name:         "headline",              # mDNS instance name — no dots allowed
+  port:         9292,
+  path:         "/headline",             # stored in the TXT record
+  hostname:     Socket.gethostname,      # default; override for multi-homed hosts
+  capabilities: ["writing", "research"]  # free-form taxonomy terms
+)
+
+adv.start   # begins advertising in a background thread
+# ... your server runs ...
+adv.stop    # sends an mDNS goodbye packet (TTL=0); removes it from peers' caches
+```
+
+`start` spawns the actual `ZeroConf::Service` on a background `Thread` and returns `self` immediately — it does not block your server's main thread. `stop` joins that thread before returning, so it's safe to assume the service is fully torn down once `stop` returns.
+
+Capability strings are free-form — see [How It Works — Capability Taxonomy](how_it_works.md#capability-taxonomy) for the (light) conventions worth following. Each one is normalized into a valid DNS label (`"Web Search"` → `"web-search"`) and registered as a DNS-SD subtype, so peers can browse for it directly without scanning every robot on the network.
+
+## Discovering Robots
+
+```ruby
+require "robot_lab/discovery"
+
+# All robots on the LAN
+results = RobotLab::Discovery.browse(timeout: 3)
+results.each { |r| puts "#{r.name}: #{r.url}  caps=#{r.capabilities.join(', ')}" }
+
+# Find one robot by name (polls until found or timeout)
+result = RobotLab::Discovery.find("headline", timeout: 5)
+result.url            # => "http://my-server.local:9292/headline"
+result.capabilities   # => ["writing", "research"]
+
+# Find all robots offering a specific capability
+researchers = RobotLab::Discovery.find_by_capability("research", timeout: 3)
+
+# List every capability type currently advertised on the LAN
+RobotLab::Discovery.list_capabilities(timeout: 3)
+# => ["analysis", "coding", "research", "writing"]
+```
+
+All four are blocking calls — each one waits (up to `timeout` seconds) for mDNS responses to arrive over the network before returning. None of them should be called from a request thread that needs to stay responsive; see [Key Constraints](#key-constraints) below.
+
+## Connecting After Discovery
+
+`Result#url` is a plain URL string — wire it to whatever client you use:
+
+```ruby
+result = RobotLab::Discovery.find("headline")
+
+# With robot_lab-a2a:
+client = A2A.client(url: result.url)
+client.send_task(message: A2A::Models::Message.user("Summarise today's news"))
+
+# With Net::HTTP directly:
+Net::HTTP.get(URI(result.url))
+```
+
+## Running the Bundled Example
+
+`examples/01_basic_usage.rb` walks through the complete lifecycle end to end — registering three robots with different capabilities, browsing all of them, finding one by name, finding by capability, listing the capability inventory, then unregistering:
+
+```sh
+bundle exec ruby examples/01_basic_usage.rb
+```
+
+Both the advertisers and the browser run in the same process in that example purely for demo convenience — in production, each robot's own server process runs its own `Advertiser`, and any separate process (a dashboard, an orchestrator, another robot) does the browsing.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test     # run the test suite (Minitest::Reporters::SpecReporter output)
+bin/console                # IRB with the gem loaded
+```
+
+Tests mock the `zeroconf` interactions (`ZeroConf.stub(:browse, ...)`) — no actual mDNS traffic is sent while running the suite.
+
+## Key Constraints
+
+- **mDNS is LAN-only.** It works within a single multicast subnet — it does not cross routers, VPN tunnels, or cloud network boundaries. There is no equivalent of this gem for discovery across separate networks.
+- **`find` and `browse` can return stale results.** If a robot's process crashes without calling `Advertiser#stop`, its mDNS records are only removed once their TTL expires on peers' caches — there's no guaranteed instant removal in that failure path (only the graceful-shutdown goodbye packet from `stop` is instant).
+- **`find` polls in a blocking loop.** It repeatedly calls `browse` internally until the named robot appears or `timeout` elapses — see [How It Works — `find(name, timeout:)`](how_it_works.md#findname-timeout). Don't call it from a thread (a web request handler, an event loop) that needs to stay responsive.
+- **Capability content is capped.** All capabilities for one robot are joined into a single comma-separated TXT string capped at 253 bytes of content (`TxtRecord::MAX_CAPABILITIES_CONTENT`). Many short capability names comfortably fit; very long strings or a huge number of them will raise `RobotLab::Discovery::Error` at `Advertiser#start` (via `TxtRecord.encode`/`validate!`) — see [How It Works](how_it_works.md#the-txt-record-wire-format) for the exact limits.
+- **Instance names may not contain dots.** `name:` becomes the mDNS instance name; DNS-SD instance names are dot-separated internally (`name._robot-lab._tcp.local.`), so a `name:` containing a literal `.` will produce a malformed or ambiguous service name.

data/docs/how_it_works.md

@@ -0,0 +1,131 @@
+# How It Works
+
+## The mDNS/DNS-SD Model
+
+This gem is a thin, purpose-built layer over two RFCs:
+
+- **mDNS** ([RFC 6762](https://www.rfc-editor.org/rfc/rfc6762)) — DNS queries and responses sent over UDP multicast on the local subnet (`224.0.0.251:5353`), instead of to a unicast DNS server. Any host on the same LAN segment hears every query and response.
+- **DNS-SD** ([RFC 6763](https://www.rfc-editor.org/rfc/rfc6763)) — a convention for naming *services* within DNS: a service type (`_robot-lab._tcp.local.`), an instance name, and a TXT record carrying arbitrary key/value metadata alongside the usual SRV record (which carries the target host and port).
+
+`RobotLab::Discovery::Constants::SERVICE_TYPE` is `"_robot-lab._tcp.local."` — every robot advertised by this gem, regardless of name or capabilities, registers under that one DNS-SD service type. A browser listening for that type hears every robot on the LAN; capability-specific browsing (below) narrows that with DNS-SD *subtypes* instead of a second protocol.
+
+The `zeroconf` gem (this gem's only runtime dependency) implements both RFCs itself in pure Ruby over a raw UDP socket — there is no Bonjour/Avahi/system daemon involved and nothing to install beyond the gem itself.
+
+## Advertising: `Advertiser`
+
+```ruby
+adv = RobotLab::Discovery::Advertiser.new(name:, port:, path:, hostname: Socket.gethostname, capabilities: [])
+adv.start
+```
+
+`start` builds a `ZeroConf::Service` for `SERVICE_TYPE` with:
+
+- `instance_name:` — the `name:` you gave (becomes the DNS-SD instance name)
+- `text:` — the TXT record, built by `TxtRecord.encode(path:, capabilities:)` (see below)
+- `subtypes:` — one `"_#{dns_label(capability)}"` string per capability
+
+...then spawns `@service.start` on a background `Thread` and returns `self` immediately, so `start` never blocks the caller. `stop` calls `@service.stop` (which sends the mDNS *goodbye* packet — a response with TTL=0 telling every listening peer to drop this record from its cache right away) and then `@thread.join`, so by the time `stop` returns, the advertising thread has fully exited. `started?` reports `@thread&.alive? || false`.
+
+### Subtypes: How Capability Browsing Actually Works
+
+DNS-SD subtypes are a real part of the spec, not something this gem invents: a service can register as belonging to `_robot-lab._tcp.local.` **and** to any number of `_<subtype>._sub._robot-lab._tcp.local.` names simultaneously. `Advertiser#start` registers one subtype per capability — a robot advertising `["writing", "research"]` shows up under:
+
+```
+_robot-lab._tcp.local.                          (always)
+_writing._sub._robot-lab._tcp.local.
+_research._sub._robot-lab._tcp.local.
+```
+
+`Discovery.find_by_capability("research")` browses `_research._sub._robot-lab._tcp.local.` directly — the mDNS query itself only reaches robots registered under that subtype, so this is a real network-level filter, not a client-side filter over every robot's TXT record. `Discovery.browse`/`list_capabilities`, by contrast, browse the base `_robot-lab._tcp.local.` type and see every robot regardless of capability.
+
+## The TXT Record Wire Format
+
+`TxtRecord` encodes three possible fields into the DNS TXT record, using single-character keys to conserve UDP packet space:
+
+| Wire key | Meaning | Long-form equivalent avoided |
+|---|---|---|
+| `p` | `path` | `path=` (saves 3 bytes) |
+| `v` | `rl_version` (the gem's `VERSION` at encode time) | `rl_version=` (saves 9 bytes) |
+| `c` | `capabilities`, comma-joined | `capabilities=` (saves 11 bytes) |
+
+`encode(path:, capabilities: [])` always includes `p=` and `v=`; `c=` is omitted entirely when `capabilities` is empty (not encoded as `c=`). `decode(strings)` reverses this, splitting each `"key=value"` string on the *first* `=` only (so a path containing `=` round-trips correctly — `"p=/foo=bar"` decodes to `path: "/foo=bar"`), and silently ignores any key it doesn't recognize (forward-compatible with future fields). `capabilities` is only present in the decoded hash when a `c=` entry existed at all — `decode(["p=/x"])` returns a hash with no `:capabilities` key, not `capabilities: []`; `Browser#parse_response` is what supplies the `[]` default via `txt.fetch(:capabilities, [])` when building a `Result`.
+
+### Size Limits, and Why They Exist
+
+Two limits are enforced by `TxtRecord.validate!`, called from inside `encode`:
+
+1. **Per-string: 255 bytes** (`MAX_STRING_BYTES`). This isn't a design choice — it's RFC 1035 §3.3.14: every string inside a TXT record is length-prefixed with a single byte, so no individual string can exceed 255 bytes no matter what. Since capabilities all share one `c=...` string, `MAX_CAPABILITIES_CONTENT` (`255 - "c".bytesize - "=".bytesize` = **253** bytes) is the real budget for however many comma-separated capability names you pack in.
+2. **Total wire size: 1300 bytes** (`MAX_TOTAL_BYTES`). This one *is* a design choice, derived from the physical network: mDNS runs over UDP, and a standard Ethernet MTU (1500 bytes) minus IP/UDP/DNS header overhead leaves roughly 1472 bytes for the whole DNS payload. After the SRV and A/AAAA records that accompany every service announcement also claim space in that same packet, keeping the TXT record itself under 1300 bytes (wire size = 1 length-prefix byte + content bytes, summed across every string) leaves enough headroom that the whole announcement stays inside a single unfragmented UDP packet. `encode` alone can never actually reach this second limit — three strings, each capped at 255 bytes, tops out well under 1300 — so this check exists to protect callers who build TXT string arrays some other way and hand them to `validate!` directly, not a realistic failure mode of `encode` itself.
+
+Both violations raise `RobotLab::Discovery::Error` with a message naming the exact byte count, at `Advertiser#start` time (since that's when `TxtRecord.encode` runs) — not at `Advertiser.new` time, since `capabilities:` is only assigned, not encoded, in the constructor.
+
+## Discovering: `Browser`
+
+`Browser` is a module of class methods — there's no instance to hold, since browsing is stateless per call.
+
+#### `browse(timeout:)`
+
+Calls `ZeroConf.browse(SERVICE_TYPE, timeout:)`, which blocks for up to `timeout` seconds collecting raw mDNS responses, then maps each one through the private `parse_response` and drops any that come back `nil` (`filter_map`), then deduplicates by `name` (`uniq(&:name)` — a robot that responds more than once during the browse window, which is normal for mDNS, only appears once in the result).
+
+#### `find(name, timeout:)`
+
+```ruby
+deadline = Time.now + timeout
+loop do
+  remaining = deadline - Time.now
+  return nil if remaining <= 0
+  result = browse(timeout: [remaining, 1].min).find { |r| r.name == name }
+  return result if result
+end
+```
+
+This is a **polling loop**, not a single `browse` call with a longer timeout: it repeatedly calls `browse` in increments of at most 1 second (`[remaining, 1].min`), checking after each one whether the named robot showed up, until either it's found or the overall `timeout` has elapsed. The 1-second cap keeps each individual `browse` responsive rather than committing the whole remaining budget to one blocking call; the practical effect is that `find` can return as soon as the target robot answers, rather than always waiting out the full `timeout`.
+
+#### `find_by_capability(capability, timeout:)`
+
+Normalizes `capability` via `RobotLab::Discovery.dns_label`, browses `"_#{label}._sub.#{SERVICE_TYPE}"` — the DNS-SD subtype, not the base service type — and otherwise behaves exactly like `browse` (parse, filter, dedupe by name).
+
+#### `list_capabilities(timeout:)`
+
+`browse(timeout:).flat_map(&:capabilities).uniq.sort` — every capability string across every currently-visible robot, deduplicated and alphabetically sorted.
+
+#### `parse_response(response)` *(private)*
+
+Given a raw `Resolv::DNS::Message`-like response, walks `response.answer + response.additional` looking for an `SRV` record (supplies `port`, `hostname` — with the trailing `.` FQDN dot stripped — and the instance name, taken from the first label of the resource name) and a `TXT` record (decoded via `TxtRecord.decode`). If either the SRV data or a `path` from the TXT data is missing, it returns `nil` rather than raising — a malformed or partial mDNS response is simply skipped, not an error condition, which is why `browse` uses `filter_map` rather than `map`.
+
+## `RobotLab::Discovery::Result`
+
+```ruby
+Result = Data.define(:name, :hostname, :port, :path, :capabilities) do
+  def url = "http://#{hostname}:#{port}#{path}"
+end
+```
+
+An immutable value object (Ruby's `Data.define`, not a mutable `Struct` or hash) — every `Result` a `browse`/`find`/`find_by_capability` call returns is a fresh, frozen snapshot; there's no way to accidentally mutate one and have it silently affect a cache. `url` always assumes plain `http://` — this gem has no notion of TLS and doesn't encode a scheme in the TXT record; if a robot actually serves over HTTPS, build the URL yourself from the other fields rather than using `#url` directly.
+
+## `dns_label`
+
+```ruby
+def self.dns_label(capability)
+  capability.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+end
+```
+
+Downcases, collapses every run of non-alphanumeric characters to a single hyphen, then strips any leading/trailing hyphen left over. `"Web Search"` → `"web-search"`; `"NLP/Analysis"` → `"nlp-analysis"`; `"Web Search / NLP"` → `"web-search-nlp"` (the `/` and surrounding spaces all collapse into the hyphens already produced by the spaces around them). This is what turns a free-form capability string into something legal to use as a DNS label component in a subtype name — DNS labels can't contain arbitrary punctuation, spaces, or mixed case in a way every resolver treats consistently.
+
+## Capability Taxonomy
+
+Capabilities are entirely free-form strings — there is no enforced registry or fixed vocabulary anywhere in this gem. The convention (not an enforced rule) is short, lowercase, hyphen-separated terms describing *what* a robot does, not *how* it works internally — e.g. `research`, `analysis`, `writing`, `coding`, `vision`, `memory`, `tool-use`, `orchestration`, `web-search`, `summarisation`, `classification`. A robot can advertise any number of them; each becomes its own DNS-SD subtype (see above), so clients browsing by capability only ever hear from robots that actually advertise it — no client-side filtering of the full robot list is needed.
+
+## Errors
+
+`RobotLab::Discovery::Error` (a plain `StandardError` subclass) is raised in exactly one place in this gem: `TxtRecord.validate!`, when either the per-string or total wire-size limit is exceeded (see above). There's no other error class in the gem — `Advertiser`/`Browser` let any underlying `zeroconf`/`Resolv`/socket error propagate as-is rather than wrapping it.
+
+## Key Constraints (and Why)
+
+These follow directly from the mechanics above, not from arbitrary gem-level restrictions:
+
+- **LAN-only, by protocol, not by choice.** mDNS multicast packets don't cross routers (that's what makes them "local" — RFC 6762 explicitly scopes them to the local link). There is no configuration in this gem that extends reach beyond a single multicast subnet; a VPN, a different VLAN, or a cloud network boundary will not see these announcements at all.
+- **Stale results after an ungraceful crash.** `Advertiser#stop` sends an explicit goodbye packet that tells peers to evict the record immediately. A process that dies without calling `stop` (a kill -9, a crash) never sends that packet — its record simply sits in every peer's cache until that record's normal mDNS TTL expires on its own. `browse`/`find` have no way to distinguish "still running" from "crashed, TTL not yet expired" — a caller that needs liveness guarantees beyond "recently advertised" needs a mechanism this gem doesn't provide (e.g. an application-level heartbeat over whatever transport the discovered URL leads to).
+- **`find` blocks the calling thread.** It's a real polling loop (see above), not instant — even a successful lookup can take up to ~1 second (one polling increment) after the robot actually answers, and an unsuccessful one blocks for the *entire* `timeout`. Never call it from a thread that has to stay responsive (a web request handler, an event loop's main thread) without moving it to a background thread or job yourself.
+- **Capability content is capped by the RFC 1035 per-string limit**, not an arbitrary choice this gem made — see [Size Limits](#size-limits-and-why-they-exist) above for the exact numbers and where they come from.

data/docs/index.md

@@ -0,0 +1,58 @@
+# robot_lab-discovery
+
+Zero-configuration mDNS/DNS-SD robot discovery for [RobotLab](https://github.com/MadBomber/robot_lab) on local networks.
+
+Robots advertise themselves via multicast DNS ([mDNS, RFC 6762](https://www.rfc-editor.org/rfc/rfc6762)) and find each other without any central registry, hardcoded URL, or configuration file. Each robot announces a name, an HTTP path, and a free-form set of *capability* tags; other robots (or any process on the LAN) can browse for all of them, look one up by name, or filter by capability.
+
+```ruby
+require "robot_lab/discovery"
+
+# A robot announces itself:
+adv = RobotLab::Discovery::Advertiser.new(
+  name: "headline", port: 9292, path: "/headline",
+  capabilities: ["writing", "research"]
+)
+adv.start
+
+# Anyone on the LAN can find it:
+result = RobotLab::Discovery.find("headline", timeout: 5)
+result.url   # => "http://my-server.local:9292/headline"
+```
+
+This gem augments `robot_lab-a2a` but has **no dependency on it, and no dependency on core `robot_lab` either** — its only runtime dependency is the pure-Ruby [`zeroconf`](https://rubygems.org/gems/zeroconf) gem. Discovery finds you a URL; you decide what protocol to speak to it (A2A, plain HTTP, anything else).
+
+## Navigation
+
+- [Getting Started](getting_started.md) — installation, advertising a robot, discovering robots, the bundled example
+- [How It Works](how_it_works.md) — the mDNS/DNS-SD model this gem builds on, the TXT record wire format, capability subtypes, and the constraints that follow from all of it
+- [API Reference](api_reference.md) — every public class and method
+
+## At a Glance
+
+| | |
+|---|---|
+| **Protocol** | Multicast DNS / DNS-SD (RFC 6762 / RFC 6763), pure Ruby — no Bonjour/Avahi/system daemon |
+| **Service type** | `_robot-lab._tcp.local.` |
+| **Advertise** | `RobotLab::Discovery::Advertiser.new(name:, port:, path:, capabilities:).start` |
+| **Discover** | `RobotLab::Discovery.browse` / `.find` / `.find_by_capability` / `.list_capabilities` |
+| **Result** | `RobotLab::Discovery::Result` — `name`, `hostname`, `port`, `path`, `capabilities`, `#url` |
+| **Scope** | LAN-only — a single multicast subnet, not routable across the internet |
+| **Runtime dependency** | `zeroconf ~> 1.0` only |
+| **Optional integration** | Self-registers via `RobotLab.register_extension(:discovery, ...)` when core `robot_lab` is loaded — otherwise usable completely standalone |
+
+## Relationship to Other RobotLab Gems
+
+| Gem | Concern |
+|---|---|
+| `robot_lab` | Core robots, networks, memory |
+| `robot_lab-a2a` | The A2A HTTP+SSE transport protocol *between* robots |
+| `robot_lab-discovery` | **Where** the robots are and **what they can do** — addressing and capability taxonomy, not transport |
+
+A typical pairing: use `robot_lab-discovery` to find a robot's URL on the LAN, then hand that URL to `robot_lab-a2a` (or plain `Net::HTTP`, or anything else) to actually talk to it.
+
+## Links
+
+- [RobotLab Core](https://github.com/MadBomber/robot_lab)
+- [RubyGems](https://rubygems.org/gems/robot_lab-discovery)
+- [GitHub](https://github.com/MadBomber/robot_lab-discovery)
+- [Changelog](https://github.com/MadBomber/robot_lab-discovery/blob/main/CHANGELOG.md)

data/examples/01_basic_usage.rb

@@ -0,0 +1,154 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/01_basic_usage.rb
+#
+# Demonstrates the complete lifecycle of robot service discovery on a local
+# network using multicast DNS (mDNS / RFC 6762):
+#
+#   Register  — Advertiser announces robots under _robot-lab._tcp.local.,
+#               encoding each robot's HTTP path and capability taxonomy in its
+#               TXT record and as DNS-SD subtypes.
+#
+#   Browse    — Discovery.browse() returns every robot on the LAN, with its
+#               name, hostname, port, path, capabilities, and url.
+#
+#   By name   — Discovery.find() targets a single robot by instance name.
+#
+#   By capability — Discovery.find_by_capability() browses a DNS-SD subtype
+#               (e.g. _research._sub._robot-lab._tcp.local.) and returns only
+#               robots that advertise that capability.
+#
+#   Inventory — Discovery.list_capabilities() collects every capability term
+#               advertised on the LAN and returns them sorted and deduped.
+#
+#   Unregister — Stopping an Advertiser sends an mDNS goodbye packet (TTL=0),
+#                removing the service from peers' caches immediately.
+#
+# Prerequisites:
+#   A multicast-capable network interface (standard on any LAN).
+#   The zeroconf gem is pure Ruby — no Bonjour, Avahi, or system daemon needed.
+#
+# Note: both advertisers and browser run in the same process here for demo
+# purposes. In production each robot's server process runs its own Advertiser.
+
+require_relative "common"
+
+ROBOT_PORT     = 9292
+BROWSE_TIMEOUT = 3  # seconds to listen for mDNS responses
+
+# ---------------------------------------------------------------------------
+# 1. Register robots on the local network
+# ---------------------------------------------------------------------------
+puts "=== Registering robots ==="
+
+robots = [
+  { name: "headline",      path: "/headline",      capabilities: ["writing", "research"]  },
+  { name: "tags",          path: "/tags",           capabilities: ["analysis"]             },
+  { name: "market-analyst",path: "/market-analyst", capabilities: ["research", "analysis"] },
+]
+
+advertisers = robots.map do |r|
+  adv = RobotLab::Discovery::Advertiser.new(
+    name:         r[:name],
+    port:         ROBOT_PORT,
+    path:         r[:path],
+    hostname:     Socket.gethostname,
+    capabilities: r[:capabilities]
+  )
+  adv.start
+  puts "  [+] #{r[:name]} (#{r[:capabilities].join(", ")}) → #{adv.hostname}.local:#{ROBOT_PORT}#{r[:path]}"
+  adv
+end
+
+puts
+
+# Allow mDNS announcements to propagate across the multicast group before
+# browsing. The zeroconf Service sends its announcement immediately on start,
+# but peers may need a moment to process it.
+sleep 1
+
+# ---------------------------------------------------------------------------
+# 2. Browse all robots on the local network
+# ---------------------------------------------------------------------------
+puts "=== Browsing local network (timeout: #{BROWSE_TIMEOUT}s) ==="
+
+results = RobotLab::Discovery.browse(timeout: BROWSE_TIMEOUT)
+
+if results.empty?
+  puts "  No robots found."
+else
+  puts "  Found #{results.size} robot(s):\n\n"
+  results.each do |r|
+    caps = r.capabilities.empty? ? "(none)" : r.capabilities.join(", ")
+    puts <<~RESULT
+        Name         : #{r.name}
+        Hostname     : #{r.hostname}
+        Port         : #{r.port}
+        Path         : #{r.path}
+        Capabilities : #{caps}
+        URL          : #{r.url}
+
+    RESULT
+  end
+end
+
+# ---------------------------------------------------------------------------
+# 3. Find a specific robot by name
+# ---------------------------------------------------------------------------
+puts "=== Finding 'headline' by name ==="
+
+result = RobotLab::Discovery.find("headline", timeout: BROWSE_TIMEOUT)
+
+if result
+  puts "  Found: #{result.url}"
+  puts "  Capabilities: #{result.capabilities.join(", ")}"
+else
+  puts "  'headline' not found within #{BROWSE_TIMEOUT}s."
+end
+
+puts
+
+# ---------------------------------------------------------------------------
+# 4. Find robots by capability
+# ---------------------------------------------------------------------------
+puts "=== Finding all 'research' robots ==="
+
+researchers = RobotLab::Discovery.find_by_capability("research", timeout: BROWSE_TIMEOUT)
+
+if researchers.empty?
+  puts "  No research robots found."
+else
+  puts "  Found #{researchers.size} research robot(s):"
+  researchers.each { |r| puts "    #{r.name} — #{r.url}" }
+end
+
+puts
+
+# ---------------------------------------------------------------------------
+# 5. List all capability types available on the LAN
+# ---------------------------------------------------------------------------
+puts "=== Available capability types ==="
+
+caps = RobotLab::Discovery.list_capabilities(timeout: BROWSE_TIMEOUT)
+
+if caps.empty?
+  puts "  None advertised."
+else
+  caps.each { |c| puts "    #{c}" }
+end
+
+puts
+
+# ---------------------------------------------------------------------------
+# 6. Unregister — send mDNS goodbye packets
+# ---------------------------------------------------------------------------
+puts "=== Unregistering robots ==="
+
+advertisers.each do |adv|
+  adv.stop
+  puts "  [-] #{adv.name} unregistered"
+end
+
+puts
+puts "Done."

data/examples/common.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# robot_lab-discovery/examples/common.rb
+#
+# Loaded by every example. Puts the gem's lib/ on the path so examples run
+# from a checkout without a gem install.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "robot_lab/discovery"