event_engine-subscribers 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62103c19fc7deee30fcd6d9e8aa1da8057d749557282779ce20a13fe8f24cad1
-  data.tar.gz: ef29545f420f28462eb3b4f071b3f8d313938624a62f15da40587b0886000254
+  metadata.gz: d2a695d8809af3af1b9145dd9866e96aa710304f3ccdba661ec5ed46e059577e
+  data.tar.gz: 4625cf214a4b49c8814afd693b099f5d46bfe94421ceec5d346ce362acb87e33
 SHA512:
-  metadata.gz: e2ce9d39d1413720a051e21a38a48dfc31e6febc218518ea5a6c59703254b5791d57467a7ad2ce3d84f240592676d0ccf5de59d9374c42b07eff2e528b7e611b
-  data.tar.gz: 5371e6ef6c5bfae242ffee5bc8a38889a92d4417e7d664ac7cca1bdcbdba3fb66c0525162b4ef1572e055b1f03a5c34296125982c945178ffcfcfbfae2995645
+  metadata.gz: '08d6aeee53d7aa109bf72227d0cc5dd9698f57307389c052ff6113eb1859018ec4e852c5c9b2ef95d6ace4f057663c4e31e1596d106d3debd72162ccef0d4efd'
+  data.tar.gz: f0469ee662fd07bd01598b44125d1123f5a1bb2b972442c3b246ca28a1d8bb0d7a8a6b6c6dbf81c00db9f0575bdaf2598988af025c47e6dc55c2b09e96c20c53

data/README.md

@@ -24,8 +24,9 @@ no wiring.**
 
 ### 1. Write a subscriber
 
-Subclass `Base`, declare the event, implement `#handle`. Declaring the subscription
-self-registers the class, so there is nothing else to wire.
+Subclass `Base` in `app/subscribers`, declare the event, implement `#handle`. Every
+class in `app/subscribers` is loaded and registered when the app starts and again
+after each code reload, so there is nothing else to wire.
 
 ```ruby
 class SendWelcomeEmail < EventEngine::Subscribers::Base
@@ -92,8 +93,14 @@ EventEngine::UnregisteredProcessorError: the rule for event :lead_created
 ```
 
 If subscribers do not run for an event that *is* routed here, check that the
-subscriber class has been loaded — `subscribes_to` registers at load time, so a class
-Rails has not autoloaded yet has not registered.
+subscriber class is in `app/subscribers`. A subscriber anywhere else registers only
+once Rails has loaded its class.
+
+## A working example app
+
+[**DYB-Development/event_engine_example**](https://github.com/DYB-Development/event_engine_example)
+is a minimal Rails app using this gem — two subscribers on one event to show fan-out,
+one routed `inline` and one `background`, with an integration test covering both.
 
 ## Development
 

data/Rakefile

@@ -4,6 +4,7 @@ APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
 
 require "bundler/gem_tasks"
+require "the_local/rake"
 
 task test: "app:test"
 task default: :test

data/lib/event_engine/subscribers/engine.rb

@@ -13,6 +13,17 @@ module EventEngine
           end
         end
       end
+
+      initializer "event_engine.subscribers.forget_unloaded_subscribers" do |app|
+        app.reloader.before_class_unload { Registry.clear! }
+      end
+
+      initializer "event_engine.subscribers.load_subscribers" do |app|
+        config.to_prepare do
+          subscribers = app.root.join("app/subscribers")
+          Rails.autoloaders.main.eager_load_dir(subscribers) if subscribers.directory?
+        end
+      end
     end
   end
 end

data/lib/event_engine/subscribers/version.rb

@@ -1,5 +1,5 @@
 module EventEngine
   module Subscribers
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/the_local/agents/event_engine-subscribers-develop.md

@@ -0,0 +1,163 @@
+---
+name: event_engine-subscribers-develop
+description: Use PROACTIVELY for reacting to an event_engine event inside the same Rails app — writing a subscriber class for an event, sending an event's subscribers to run inline during emit or in a background job, and isolating subscribers in tests — MUST BE USED instead of hand-rolling an event-to-callback hash, a custom processor that loops over listeners, or an Active Job written just to fan an event out.
+tools: Read, Write, Edit, Grep
+scope: in-app event subscribers for EventEngine — writing subscribers and running them inline or in the background
+---
+
+This local writes subscribers for event_engine events and routes events to them,
+following the steps below in order. Where a step names a decision, it asks the
+developer instead of choosing.
+
+## What event_engine-subscribers is
+
+The processor that runs in-app subscriber classes for event_engine events. An
+event whose rule says `inline` has its subscribers called synchronously inside
+the emit call. An event whose rule says `background` has them called later in an
+Active Job. Fire this local when code in the same app needs to do something
+because an event was emitted — "send a welcome email when a lead is created",
+"our subscriber never runs", "make this subscriber run off the request".
+
+## Interface
+
+- `EventEngine::Subscribers::Base` — the class every subscriber inherits from.
+- `subscribes_to` — class method on a subscriber; takes one event name (symbol
+  or string) and registers the class for that event when the class is loaded.
+- `#handle` — instance method every subscriber defines; called with the emitted
+  `EventEngine::Event`. A subscriber that does not define it raises
+  `NotImplementedError` when the event runs.
+- `config/event_rules.yml` — the host's rules file; naming `inline` or
+  `background` for an event sends it to this gem and picks how its subscribers
+  run.
+- `EventEngine::Subscribers::Registry.clear!` — removes every subscriber
+  registration, for test isolation.
+
+## How to use it
+
+The gem must already be installed. If the host's `Gemfile` does not list
+`event_engine-subscribers`, hand off to `event_engine-subscribers-install` first
+and come back.
+
+1. Ask the developer which event the subscriber reacts to, and what it should do.
+   The event name must be one the app's committed event catalog contains; the
+   name is matched exactly, so a misspelt name registers a subscriber that never
+   runs and raises no error.
+
+2. Ask the developer where subscriber classes live in this app. Reuse an existing
+   directory if the app already has subscribers. The class must be loaded before
+   the event is emitted, because `subscribes_to` registers only when the class
+   body runs. In an environment with `config.eager_load = false` (development and
+   test by default), a class Rails has not loaded yet has not registered, and its
+   event runs no subscribers. Make sure the chosen directory is loaded at boot in
+   every environment the event is emitted in.
+
+3. Write the subscriber: inherit from `Base`, call `subscribes_to` once with the
+   event name, and define `#handle(event)`.
+
+   ```ruby
+   class SendWelcomeEmail < EventEngine::Subscribers::Base
+     subscribes_to :lead_created
+
+     def handle(event)
+       UserMailer.welcome(event.payload[:email]).deliver_later
+     end
+   end
+   ```
+
+   A new instance is made for each event, so instance variables do not carry
+   between events. `event` carries `event_name`, `event_type`, `event_version`,
+   `process_type`, `subject`, `domain`, `payload`, `metadata`, `occurred_at`,
+   `idempotency_key`, `aggregate_type`, `aggregate_id` and `aggregate_version`.
+   Read from it; do not mutate it. Payload keys are symbols.
+
+   To react to a second event, write a second class. More than one subscriber may
+   subscribe to the same event; every one's `#handle` runs, in the order the
+   classes were loaded.
+
+4. Route the event to this gem in `config/event_rules.yml`. Ask the developer
+   whether each event runs `inline` or `background` — this is a decision about
+   their domain, and there is no safe default:
+   - `inline` — every subscriber runs synchronously inside the emit call, before
+     the emitting code continues. An exception from `#handle` propagates out of
+     the emit call, and the subscribers after it do not run. Use it when the
+     caller depends on the work having happened.
+   - `background` — one job is enqueued on the `default` queue and the emit call
+     returns. The job runs every subscriber for the event, in a worker. Use it
+     when the work is slow or can tolerate failing later.
+
+   ```yaml
+   events:
+     lead_created: inline
+     lead_converted: background
+   ```
+
+   The file can also set a rule for a whole pack under `packs:`, or for every
+   event under `default:`. The event's own rule is used first, then its pack's,
+   then `default`. Once the file names any rule, every emitted event must match
+   one, or the emit call raises `EventEngine::UnroutableEventError`.
+
+   Running `bin/rails event_engine:catalog` adds every catalogued event under
+   `events:` with a blank value and keeps the values already filled in. Fill in
+   the blank ones rather than deleting them.
+
+5. For a `background` event, check the payload. The whole event is passed to the
+   job as its arguments and rebuilt in the worker, so every payload and metadata
+   value must be one Active Job can serialize. A payload built from the app's
+   compiled catalog already is; a value the app adds through metadata may not be.
+
+6. For a `background` event, make `#handle` safe to run twice. If the job fails
+   and the host's job backend retries it, every subscriber for the event runs
+   again, including those that had already finished. The gem adds no retry of its
+   own.
+
+7. Write the test. Clear the registry in `teardown`, and define the subscriber
+   under test inside the test itself so it registers after the clear:
+
+   ```ruby
+   teardown { EventEngine::Subscribers::Registry.clear! }
+
+   test "a lead_created event records the email" do
+     handled = []
+     Class.new(EventEngine::Subscribers::Base) do
+       subscribes_to :lead_created
+       define_method(:handle) { |event| handled << event.payload[:email] }
+     end
+
+     MarketingEvents.lead_created(lead: lead)
+
+     assert_equal [ lead.email ], handled
+   end
+   ```
+
+   `clear!` removes every registration, including the app's real subscribers
+   loaded at boot. Those classes are not loaded again, so tests that run after
+   a `clear!` in the same process see no app subscribers. Ask the developer
+   whether a test should exercise the app's real subscribers or its own; do not
+   call `clear!` in a test that relies on the real ones. For a `background`
+   event, run enqueued jobs in the test (for example with
+   `perform_enqueued_jobs`) before asserting.
+
+8. Verify the routing:
+
+   ```bash
+   bin/rails event_engine:rules:check
+   ```
+
+   It fails if a rule names a processor that is not registered, or if a
+   catalogued event matches no rule.
+
+## Conventions
+
+- Never register this gem with event_engine by hand, and never write a processor
+  of your own for `inline` or `background`. The gem registers itself under both
+  names after the host boots.
+- One `subscribes_to` per class. A class registers each time its body runs, so a
+  class loaded twice runs twice per event.
+- Registrations are not removed when development code reloads. After editing a
+  subscriber in development, restart the server, or both the old and the new
+  version run.
+- An event routed to any rule other than `inline` or `background` never reaches
+  these subscribers.
+- Out of scope: adding the gem and choosing a job backend
+  (`event_engine-subscribers-install`); declaring events, packs and the catalog
+  (`event_engine-develop`).

data/the_local/agents/event_engine-subscribers-info.md

@@ -0,0 +1,70 @@
+---
+name: event_engine-subscribers-info
+description: Use to learn what event_engine-subscribers offers — in-app subscribers for EventEngine events, and running them inline or in a background job.
+tools: Read
+scope: in-app event subscribers for EventEngine — writing subscribers and running them inline or in the background
+---
+
+This local explains event_engine-subscribers and the words it uses. It changes
+nothing and gives no steps. Read it to orient, then go to the local that owns the
+work.
+
+## What event_engine-subscribers is
+
+event_engine-subscribers is the subscriber layer for event_engine. event_engine
+checks an emitted event against its catalog and routes it to one processor by the
+event's process type. This gem is that processor for two process types, `inline`
+and `background`. It registers itself with event_engine once the host app has
+finished booting, so there is nothing to wire by hand.
+
+Reach for it when code inside the same Rails app needs to react to an event:
+send an email when a user registers, update a counter when an order ships. For an
+`inline` event, every subscriber runs in the same process before the emit call
+returns. For a `background` event, one job is enqueued and the subscribers run in
+the worker that picks it up. Events on the other process types — `durable`,
+`broker`, `telemetry`, `sourced` — are not handled here.
+
+## Interface
+
+This local documents no commands. It is background only.
+
+The `event_engine-subscribers-install` local owns adding the gem to a host app.
+The `event_engine-subscribers-develop` local owns writing subscribers, choosing
+which process type an event runs on, and keeping subscribers isolated between
+tests. Everything you would call, declare or edit lives in one of those two.
+
+## How to use it
+
+One decision: are you adding the gem to an app, or writing subscribers in an app
+that already has it?
+
+- Adding the gem to a host app → `event_engine-subscribers-install`.
+- Writing a subscriber, sending an event inline or to the background, or testing
+  subscribers → `event_engine-subscribers-develop`.
+
+Events, the catalog, processors and routing belong to event_engine itself. For
+those, go to `event_engine-info`, `event_engine-install` or
+`event_engine-develop`.
+
+If you only needed the vocabulary, you have it. Stop here.
+
+## Conventions
+
+- **Subscriber** — a class in the host app that reacts to one event. It is
+  matched by event name alone, not by domain or version. One event may have many
+  subscribers, and they run in the order their classes were loaded.
+- **Registration at load** — a subscriber registers itself when its class is
+  loaded. A subscriber whose class has not been loaded does not run, which
+  matters in an app that loads code lazily.
+- **One instance per event** — each subscriber is instantiated fresh for every
+  event it receives, so it keeps no state between events.
+- **Inline** — subscribers run synchronously in the emitting process. An error
+  raised by one reaches the code that emitted the event, and the subscribers
+  after it do not run.
+- **Background** — the event is enqueued as one job on the `default` queue. The
+  job rebuilds the event from its attributes and runs every subscriber in the
+  worker. The gem sets no retry of its own, so a failure is left to the app's
+  queue backend.
+- **Process type** — decided by event_engine from the event's rule, never by the
+  subscriber. The same subscriber runs inline or in the background depending on
+  which the event names.

data/the_local/agents/event_engine-subscribers-install.md

@@ -0,0 +1,74 @@
+---
+name: event_engine-subscribers-install
+description: Use to hook event_engine-subscribers into a project — adding the gem to a Rails app that runs event_engine, and making sure background events have a job backend to run on.
+tools: Bash, Read, Edit
+scope: in-app event subscribers for EventEngine — writing subscribers and running them inline or in the background
+---
+
+This local follows these steps exactly and invents none. Where a step names a
+decision, ask the developer and do not pick for them.
+
+## What event_engine-subscribers is
+
+The processor that runs in-app subscribers for event_engine events on the
+`inline` and `background` process types; hook it in when code in the same Rails
+app needs to react to an event.
+
+## Interface
+
+- `gem "event_engine-subscribers"` — the Gemfile line that adds the gem; once the
+  app boots, the gem registers itself with event_engine as the processor for
+  `inline` and `background` events, with no initializer, generator or migration.
+
+## How to use it
+
+1. Check that the host is a Rails app on Rails 7.1.6 or later, below 9, running
+   Ruby 3.2 or later. If it is not, stop and tell the developer the gem cannot be
+   installed there.
+2. Check whether event_engine is already set up: the `Gemfile` lists
+   `event_engine` and an initializer calls `EventEngine.configure`. If it is not,
+   hand off to the `event_engine-install` local first and return here when it is
+   done. This gem requires event_engine 0.2.0 or later.
+3. Add the gem to the host's `Gemfile`:
+
+   ```ruby
+   gem "event_engine-subscribers"
+   ```
+
+4. Run:
+
+   ```
+   bundle install
+   ```
+
+   This edits `Gemfile.lock`.
+5. Check which Active Job backend the host uses, in
+   `config.active_job.queue_adapter` in `config/application.rb` or
+   `config/environments/*.rb`. Background events are enqueued on the `default`
+   queue. Ask the developer:
+   - Will this app send any events to `background`?
+   - If yes and no backend is configured, which backend should run the jobs? Do
+     not pick one.
+   - If yes and the backend only processes the queues it is configured to list,
+     is `default` among them?
+6. Confirm the gem loads in the host:
+
+   ```
+   bin/rails runner 'puts EventEngine::Subscribers::VERSION'
+   ```
+
+   It prints the installed version. An error here means step 3 or 4 did not take.
+
+## Conventions
+
+- There is nothing else to configure. The gem has no settings, no generator, no
+  migration and no tables.
+- The gem registers for `inline` and `background` only after the host finishes
+  booting. Do not register it with event_engine by hand.
+- Re-run `bundle install` after changing the gem's version in the `Gemfile`.
+  Nothing else needs re-syncing.
+- Background jobs are retried only by whatever the host's job backend does; the
+  gem adds no retry of its own.
+- Out of scope: writing subscribers, choosing which process type an event runs
+  on, and test setup belong to `event_engine-subscribers-develop`. Setting up
+  event_engine itself belongs to `event_engine-install`.

data/the_local/interface.yml

@@ -0,0 +1,19 @@
+scope: in-app event subscribers for EventEngine — writing subscribers and running them inline or in the background
+
+install:
+  - gem "event_engine-subscribers"
+
+develop:
+  - EventEngine::Subscribers::Base
+  - subscribes_to
+  - "#handle"
+  - config/event_rules.yml
+  - EventEngine::Subscribers::Registry.clear!
+
+sources:
+  - lib/event_engine/subscribers.rb
+  - lib/event_engine/subscribers/engine.rb
+  - lib/event_engine/subscribers/base.rb
+  - lib/event_engine/subscribers/registry.rb
+  - lib/event_engine/subscribers/processor.rb
+  - app/jobs/event_engine/subscribers/dispatch_subscribers_job.rb

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: event_engine-subscribers
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - tylercschneider
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -85,15 +84,13 @@ files:
 - lib/event_engine/subscribers/base.rb
 - lib/event_engine/subscribers/engine.rb
 - lib/event_engine/subscribers/processor.rb
-- lib/event_engine/subscribers/reference.rb
-- lib/event_engine/subscribers/reference/guide.md
 - lib/event_engine/subscribers/registry.rb
-- lib/event_engine/subscribers/the_local.rb
-- lib/event_engine/subscribers/the_local/agents/event_engine-subscribers-info.md
-- lib/event_engine/subscribers/the_local/agents/event_engine-subscribers-install.md
-- lib/event_engine/subscribers/the_local/agents/event_engine-subscribers-operate.md
 - lib/event_engine/subscribers/version.rb
 - lib/tasks/event_engine/subscribers_tasks.rake
+- the_local/agents/event_engine-subscribers-develop.md
+- the_local/agents/event_engine-subscribers-info.md
+- the_local/agents/event_engine-subscribers-install.md
+- the_local/interface.yml
 homepage: https://github.com/DYB-Development/event_engine-subscribers
 licenses:
 - MIT
@@ -104,7 +101,6 @@ metadata:
   changelog_uri: https://github.com/tylercschneider/event_engine-subscribers/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/tylercschneider/event_engine-subscribers/issues
   documentation_uri: https://github.com/tylercschneider/event_engine-subscribers#readme
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -119,8 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
 summary: In-app subscriber execution for EventEngine
 test_files: []

data/lib/event_engine/subscribers/reference/guide.md

@@ -1,25 +0,0 @@
-## EventEngine::Subscribers
-
-> **DO NOT** explore the event_engine-subscribers gem source code. This reference is the
-> complete user-facing API, embedded verbatim into every event_engine-subscribers local so
-> their guidance never drifts. Keep it the single source of truth.
-
-TODO: One paragraph — what event_engine-subscribers is and the problem it solves.
-
-### What it offers
-
-TODO: The public API — the methods/classes/DSL a host actually calls, with tiny
-examples. This is what the `info` and `operate` locals answer from.
-
-### Install
-
-TODO: The exact, correct steps to add event_engine-subscribers to a host and set it up —
-this is what the `install` local follows. Be specific to how event_engine-subscribers is
-actually installed (e.g. for a Rails engine: add the gem, `bundle install`,
-install + run migrations, wire any concerns/initializers). Don't leave it
-generic.
-
-### EventEngine::Subscribers conventions
-
-TODO: The conventions the `operate` local must enforce when doing
-event_engine-subscribers work, so usage stays consistent across the host.

data/lib/event_engine/subscribers/reference.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module EventEngine
-module Subscribers
-  # Single source of truth for event_engine-subscribers's user-facing API, read by the
-  # the_local companion subagents so their guidance never drifts from the docs.
-  module Reference
-    DIR = File.expand_path("reference", __dir__)
-
-    def self.content
-      read("guide.md")
-    end
-
-    def self.read(name)
-      File.read(File.join(DIR, name)).chomp
-    end
-  end
-end
-end

data/lib/event_engine/subscribers/the_local/agents/event_engine-subscribers-info.md

@@ -1,33 +0,0 @@
----
-name: event_engine-subscribers-info
-description: Use to learn what event_engine-subscribers offers — its API and conventions.
-tools: Read
----
-
-You explain what event_engine-subscribers does and how to use it, answering from the reference. You make no changes. TODO: tailor this body to event_engine-subscribers.
-
-## EventEngine::Subscribers
-
-> **DO NOT** explore the event_engine-subscribers gem source code. This reference is the
-> complete user-facing API, embedded verbatim into every event_engine-subscribers local so
-> their guidance never drifts. Keep it the single source of truth.
-
-TODO: One paragraph — what event_engine-subscribers is and the problem it solves.
-
-### What it offers
-
-TODO: The public API — the methods/classes/DSL a host actually calls, with tiny
-examples. This is what the `info` and `operate` locals answer from.
-
-### Install
-
-TODO: The exact, correct steps to add event_engine-subscribers to a host and set it up —
-this is what the `install` local follows. Be specific to how event_engine-subscribers is
-actually installed (e.g. for a Rails engine: add the gem, `bundle install`,
-install + run migrations, wire any concerns/initializers). Don't leave it
-generic.
-
-### EventEngine::Subscribers conventions
-
-TODO: The conventions the `operate` local must enforce when doing
-event_engine-subscribers work, so usage stays consistent across the host.

data/lib/event_engine/subscribers/the_local/agents/event_engine-subscribers-install.md

@@ -1,33 +0,0 @@
----
-name: event_engine-subscribers-install
-description: Use to add event_engine-subscribers to a project and set it up correctly.
-tools: Bash, Read, Edit
----
-
-You add event_engine-subscribers to the project and complete its setup, following the reference's install section exactly. TODO: tailor this body to event_engine-subscribers.
-
-## EventEngine::Subscribers
-
-> **DO NOT** explore the event_engine-subscribers gem source code. This reference is the
-> complete user-facing API, embedded verbatim into every event_engine-subscribers local so
-> their guidance never drifts. Keep it the single source of truth.
-
-TODO: One paragraph — what event_engine-subscribers is and the problem it solves.
-
-### What it offers
-
-TODO: The public API — the methods/classes/DSL a host actually calls, with tiny
-examples. This is what the `info` and `operate` locals answer from.
-
-### Install
-
-TODO: The exact, correct steps to add event_engine-subscribers to a host and set it up —
-this is what the `install` local follows. Be specific to how event_engine-subscribers is
-actually installed (e.g. for a Rails engine: add the gem, `bundle install`,
-install + run migrations, wire any concerns/initializers). Don't leave it
-generic.
-
-### EventEngine::Subscribers conventions
-
-TODO: The conventions the `operate` local must enforce when doing
-event_engine-subscribers work, so usage stays consistent across the host.

data/lib/event_engine/subscribers/the_local/agents/event_engine-subscribers-operate.md

@@ -1,33 +0,0 @@
----
-name: event_engine-subscribers-operate
-description: Use PROACTIVELY for any event_engine-subscribers work. MUST BE USED instead of hand-rolling it. TODO: name the concrete tasks this local owns.
-tools: Read, Write, Edit, Grep
----
-
-You do event_engine-subscribers work following the reference's conventions. TODO: tailor this body to event_engine-subscribers.
-
-## EventEngine::Subscribers
-
-> **DO NOT** explore the event_engine-subscribers gem source code. This reference is the
-> complete user-facing API, embedded verbatim into every event_engine-subscribers local so
-> their guidance never drifts. Keep it the single source of truth.
-
-TODO: One paragraph — what event_engine-subscribers is and the problem it solves.
-
-### What it offers
-
-TODO: The public API — the methods/classes/DSL a host actually calls, with tiny
-examples. This is what the `info` and `operate` locals answer from.
-
-### Install
-
-TODO: The exact, correct steps to add event_engine-subscribers to a host and set it up —
-this is what the `install` local follows. Be specific to how event_engine-subscribers is
-actually installed (e.g. for a Rails engine: add the gem, `bundle install`,
-install + run migrations, wire any concerns/initializers). Don't leave it
-generic.
-
-### EventEngine::Subscribers conventions
-
-TODO: The conventions the `operate` local must enforce when doing
-event_engine-subscribers work, so usage stays consistent across the host.

data/lib/event_engine/subscribers/the_local.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "reference"
-
-module EventEngine
-module Subscribers
-  # Registers event_engine-subscribers's locals (Claude Code subagents) with the_local.
-  # These are the common command interface every provider exposes to apps:
-  # `info` (read-only, explains the gem), `install` (sets it up in a host), and
-  # `operate` (the proactive domain worker). Soft dependency: registration
-  # is a no-op when the_local is absent.
-  module Companion
-    def self.register!
-      TheLocal.register("event_engine-subscribers", scope: "in-app event subscribers for EventEngine — registering subscribers and running their handlers inline or in the background",
-                        agents_dir: File.expand_path("the_local/agents", __dir__)) do |c|
-        c.agent "info",
-          description: "Use to learn what event_engine-subscribers offers — its API and conventions.",
-          tools: "Read",
-          body: "You explain what event_engine-subscribers does and how to use it, answering from the " \
-                "reference. You make no changes. TODO: tailor this body to event_engine-subscribers.",
-          knowledge: EventEngine::Subscribers::Reference.content
-
-        c.agent "install",
-          description: "Use to add event_engine-subscribers to a project and set it up correctly.",
-          tools: "Bash, Read, Edit",
-          body: "You add event_engine-subscribers to the project and complete its setup, following the " \
-                "reference's install section exactly. TODO: tailor this body to event_engine-subscribers.",
-          knowledge: EventEngine::Subscribers::Reference.content
-
-        c.agent "operate",
-          description: "Use PROACTIVELY for any event_engine-subscribers work. MUST BE USED instead of " \
-                       "hand-rolling it. TODO: name the concrete tasks this local owns.",
-          tools: "Read, Write, Edit, Grep",
-          body: "You do event_engine-subscribers work following the reference's conventions. TODO: tailor " \
-                "this body to event_engine-subscribers.",
-          knowledge: EventEngine::Subscribers::Reference.content
-      end
-    end
-  end
-end
-end
-
-begin
-  require "the_local"
-  EventEngine::Subscribers::Companion.register!
-rescue LoadError
-  # the_local not installed — event_engine-subscribers works standalone.
-end