the_local 0.1.0

data/lib/the_local/disk_providers.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module TheLocal
+  # Discovers providers by reading their committed agent files straight from each
+  # bundled gem's path on disk — no gem code is loaded and no register block runs.
+  # The committed .md (the build-and-commit artifact) is the declarative contract;
+  # a provider contributes simply by shipping those files. Populates the same
+  # registry the install pipeline already reads, so Installer/TriggerWriter/Sync
+  # are unchanged.
+  module DiskProviders
+    AGENTS_GLOB = File.join("lib", "**", "the_local", "agents", "*.md")
+
+    def self.load(registry:, specs:)
+      specs.each { |spec| register(registry, spec) }
+    end
+
+    def self.register(registry, spec)
+      files = Dir.glob(File.join(spec[:path], AGENTS_GLOB))
+      return if files.empty?
+
+      agents = files.map { |file| agent_from(spec[:name], file) }
+      registry.add_provider(Provider.new(gem_name: spec[:name], prefix: agents.first.prefix, scope: nil))
+      agents.each { |agent| registry.add(agent) }
+    end
+
+    def self.agent_from(gem_name, file)
+      prefix, _, name = File.basename(file, ".md").rpartition("-")
+      Agent.new(gem_name: gem_name, prefix: prefix, name: name,
+                description: nil, tools: nil, body: nil, knowledge: nil, source_path: file)
+    end
+  end
+end

data/lib/the_local/installer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module TheLocal
+  # Copies each allowed provider's committed agent file into a destination's
+  # .claude/agents/ directory, verbatim. Plain Ruby so the Rails generator is a
+  # thin wrapper over it.
+  class Installer
+    AGENTS_DIR = ".claude/agents"
+
+    def initialize(registry:, destination:, allowed_gems:)
+      @registry = registry
+      @destination = destination
+      @allowed_gems = allowed_gems
+    end
+
+    def call
+      agents_dir = File.join(@destination, AGENTS_DIR)
+      FileUtils.mkdir_p(agents_dir)
+
+      installed_agents.each do |agent|
+        ensure_committed!(agent)
+        FileUtils.cp(agent.source_path, File.join(agents_dir, agent.filename))
+      end
+    end
+
+    private
+
+    def installed_agents
+      @registry.agents.select { |agent| @allowed_gems.include?(agent.gem_name) }
+    end
+
+    def ensure_committed!(agent)
+      return if agent.source_path && File.exist?(agent.source_path)
+
+      raise Error, "the_local: #{agent.gem_name} registered #{agent.qualified_name} without a committed " \
+                   "agent file. Run `rake the_local:build` in #{agent.gem_name} and commit its the_local/agents/."
+    end
+  end
+end

data/lib/the_local/process_doc_writer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "process_rules"
+
+module TheLocal
+  # Writes the canonical develop-process rules into a host's CLAUDE.md as a
+  # managed block, read at the start of every session so the host agent always
+  # follows one source of truth. Re-propagated on every install/refresh. Uses
+  # its own markers so it coexists with the delegation trigger in the same file.
+  class ProcessDocWriter
+    BEGIN_MARKER = "<!-- the_local:process:begin -->"
+    END_MARKER = "<!-- the_local:process:end -->"
+    RULES_FILENAME = "develop_process_rules.md"
+
+    def initialize(destination:, filename: "CLAUDE.md")
+      @destination = destination
+      @filename = filename
+    end
+
+    def call
+      File.write(File.join(@destination, RULES_FILENAME), "#{ProcessRules.content}\n")
+      path = File.join(@destination, @filename)
+      existing = File.exist?(path) ? File.read(path) : ""
+      File.write(path, "#{merge(existing)}\n")
+    end
+
+    def block
+      <<~MARKDOWN.chomp
+        #{BEGIN_MARKER}
+        Read and follow this develop process for all work in this project. It is
+        also written verbatim to `#{RULES_FILENAME}` — reference that file directly.
+
+        #{ProcessRules.content}
+        #{END_MARKER}
+      MARKDOWN
+    end
+
+    private
+
+    def merge(existing)
+      section = /#{Regexp.escape(BEGIN_MARKER)}.*?#{Regexp.escape(END_MARKER)}/m
+      return existing.sub(section, block) if existing.match?(section)
+      return block if existing.strip.empty?
+
+      "#{existing.chomp}\n\n#{block}"
+    end
+  end
+end

data/lib/the_local/process_rules/develop_process_rules.md

@@ -0,0 +1,97 @@
+# Develop Process
+
+The standard process for writing code across all projects. Default to these rules
+unless a project explicitly overrides them.
+
+---
+
+## Diverging from this process
+
+Read this process before starting work and follow it — it is the default for
+every session. If a task genuinely calls for breaking one of these rules, do not
+silently deviate: **PAUSE and ask for a one-time exception**, naming the rule and
+why it should be set aside here. An exception is granted for that instance only —
+it needs no doc or notes update — and then you continue. Do not treat a granted
+exception as a standing change to the process.
+
+---
+
+## Test-Driven Development
+
+TDD is the default for everything. Work one tiny cycle at a time:
+
+1. **Write one test that asserts one thing.**
+2. **Run it and watch it fail** — for the right reason. A test you never saw fail
+   proves nothing.
+3. **Write the minimum code to make it pass.**
+4. **Run the test and watch it pass.**
+5. **Commit.**
+6. Repeat with the next test.
+
+One assertion per test. One test per commit cycle. No batching multiple behaviors
+into a single test or a single commit.
+
+---
+
+## Commits
+
+- A commit is normally **two files: the test file and the code file.**
+- When implementing or updating an interface (e.g. a new controller endpoint) a
+  commit may touch more files (route + controller + view) — that is the minimal
+  coherent unit for that interface, and it is allowed.
+- Keep each commit focused on the one behavior the test describes.
+
+---
+
+## What to Test
+
+- **Test our own code only.**
+- **Never test third-party code** — not a gem, not an API, not a framework. The
+  only test that may reference a dependency is one that asserts *our system is
+  correctly wired to it* (the integration seam), never the dependency's own
+  behavior.
+- **Never test another interface inside a unit test.** A test covers one interface.
+  The single exception is the smoke integration test described below.
+
+---
+
+## Smoke Integration Test
+
+When implementing an interface, write **one smoke integration test** that exercises
+the interface end to end and proves the pieces are connected. This is the one place
+where touching more than the unit under test is expected and correct.
+
+---
+
+## Pull Requests
+
+- **Always work on a feature branch and open a PR.** Confirm the target branch
+  before any git operation (`git branch --show-current`).
+- **Keep PRs small and manageable** — typically **no more than 8–10 files.**
+- Keep the focus of a PR narrow. One concern per PR.
+- **All tests pass before opening the PR.**
+- **The linter and every other CI check pass before opening the PR.**
+- Never start a new PR until the previous one is merged.
+
+---
+
+## Code Quality
+
+- Follow Clean Code principles: small functions, clear names, no surprises.
+- Follow SOLID principles. Readable by a human first.
+- Keep it simple — no abstraction until a real need calls for it.
+- Explicitly require libraries rather than assuming autoload.
+
+## Comments
+
+- **Write self-documenting code, not comments.** Code should be clean and readable
+  on its own. Names — of classes, methods, variables, and partials — carry the intent.
+- **A comment is a smell.** If you feel a comment is needed, the code is either built
+  wrong or needs refactoring (a clearer name, a smaller method, an extracted object or
+  partial) so the intent is obvious without prose. Follow SOLID and this resolves itself.
+- Do not leave explanatory headers on classes/methods, inline "what this does" notes,
+  or section banners. Delete them and let the structure speak.
+- Narrow exceptions, kept rare: a genuinely non-obvious *why* (a workaround for an
+  external bug, a legal/security constraint) and machine-readable annotations the
+  tooling requires (e.g. `rubocop:disable`). Prefer refactoring over a "why" comment
+  whenever you can.

data/lib/the_local/process_rules.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module TheLocal
+  # Loads the canonical develop-process rules the_local propagates into every
+  # host, so a host agent reads and follows one source of truth.
+  module ProcessRules
+    DIR = File.expand_path("process_rules", __dir__)
+
+    def self.content
+      read("develop_process_rules.md")
+    end
+
+    def self.read(name)
+      File.read(File.join(DIR, name)).chomp
+    end
+  end
+end

data/lib/the_local/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require "the_local"
+
+module TheLocal
+  # Minimal Railtie whose only job is to expose the `the_local:refresh` rake task
+  # to the host app. Registration deliberately does NOT use a Railtie (it happens
+  # at gem load — see the design plan); this is purely task exposure.
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("tasks/the_local.rake", __dir__)
+    end
+  end
+end

data/lib/the_local/rake.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rake"
+require "the_local"
+require "the_local/builder"
+
+# Gem-side build task. A provider adds `require "the_local/rake"` to its Rakefile
+# (after loading the gem, so its locals are registered) and runs
+# `rake the_local:build` to (re)render its committed .claude agent files from the
+# registered definitions. Host apps don't use this — they install/refresh.
+namespace :the_local do
+  desc "Render this provider's committed agent files from its registered definitions"
+  task :build do
+    written = TheLocal::Builder.new(registry: TheLocal.registry).call
+    puts "the_local: built #{written.length} agent file(s)"
+  end
+
+  desc "Install/refresh this project's locals from the current bundle into .claude/agents/"
+  task :install do
+    allowed = TheLocal::Refresh.call(destination: Dir.pwd)
+    puts "the_local: installed locals for #{allowed.join(", ")}"
+  end
+end

data/lib/the_local/reference/guide.md

@@ -0,0 +1,103 @@
+## TheLocal
+
+> **DO NOT** explore the the_local gem source code. This reference is the
+> complete user-facing API, embedded verbatim into every the_local local so
+> their guidance never drifts. Keep it the single source of truth.
+
+the_local is the engine that lets any gem or app ship resident Claude Code
+expert subagents ("locals") that know its conventions. A provider gem registers
+its locals once; the_local renders them to committed `.md` files and installs
+the aggregated set from every directly-depended provider into a consuming app's
+`.claude/agents/`, plus a delegation rule so the host's agent actually uses them.
+
+### The model
+
+- **Providers define locals.** A gem (or the app) calls `TheLocal.register` to
+  declare its locals; each `c.agent` becomes one local. The register block runs
+  only at build time, behind a soft `require "the_local"` guard so the gem still
+  works standalone.
+- **`the_local:build` renders committed `.md`.** The provider runs
+  `rake the_local:build`; `TheLocal::Builder` writes each agent to its
+  `source_path` under `lib/<gem>/the_local/agents/<prefix>-<name>.md`. The
+  rendered files are committed to the provider's repo. **These committed files
+  are the contract** — they are what a host reads. The register block + `guide.md`
+  are the source of truth they're built from.
+- **Install discovers committed `.md` on disk.** In a host, install reads each
+  direct dependency's committed `lib/**/the_local/agents/*.md` straight from its
+  gem path and copies them into `.claude/agents/` byte-for-byte — no provider
+  code is loaded and no register block runs in the host. Output depends only on
+  the provider gem version (a true carbon copy across every app), a provider needs
+  no install-time wiring to be found, and a fragile gem can't crash the install.
+- **The delegation trigger.** Install also writes a registry-generated block into
+  the host's `CLAUDE.md`/`AGENTS.md` telling the host agent to delegate to these
+  locals. This is what makes delegation actually happen.
+- **Direct-dependency scope.** Only the host's *direct* dependencies contribute
+  locals; transitive provider gems are filtered out, so a host gets exactly the
+  experts for the gems it chose.
+
+### Install (in any gem or app)
+
+1. Add the gem to the host's `Gemfile` (until it is on RubyGems, use a git
+   source: `gem "the_local", github: "DYB-Development/the_local"`), then
+   `bundle install`.
+2. Run `bundle exec the_local install`. This syncs every direct provider's
+   committed locals into `.claude/agents/` and writes the delegation trigger
+   into `CLAUDE.md`/`AGENTS.md`. It needs no Rails — a plain gem installs the
+   same way an app does.
+3. Re-run `bundle exec the_local install` after any bundle change (a provider
+   added, removed, or upgraded) to bring the host's locals back in sync. The
+   shell can automate this; the gem only exposes the command.
+
+Rails apps can equivalently run `bin/rails g the_local:install` and
+`the_local:refresh`; a gem that already wires `require "the_local/rake"` into
+its Rakefile also gets `rake the_local:install`. All three share one engine.
+
+### Author a provider (turn a gem into a provider)
+
+1. Run `bin/rails g the_local:provider <gem_name>` (pass `--scope`,
+   `--prefix`, `--worker` as needed). It scaffolds `lib/<gem>/reference.rb`, a
+   `lib/<gem>/reference/guide.md`, and a `lib/<gem>/the_local.rb` companion that
+   registers the standard interface; hooks `the_local:build` into the `Rakefile`;
+   requires the companion from the gem entrypoint; and builds the committed
+   `.md` for review.
+2. Write `guide.md` in this format — it is the single source of truth and is
+   embedded verbatim into every local. Document *your own* gem only: what it
+   does, how to install it, the conventions to enforce. Name companion gems but
+   do not explain their internals.
+3. Tailor the register block bodies and `scope` to your gem; the standard
+   interface is `info` (read-only explainer), `install` (sets the gem up in a
+   host), and a domain worker (`develop` for libraries, `operate` for CLIs).
+4. Run `rake the_local:build`, then **commit and ship**
+   `lib/<gem>/the_local/agents/*.md` (they must be in the gemspec's `files`).
+   This is the whole contract: a host discovers your locals by reading these
+   committed files from your gem on disk — it never loads your gem or runs your
+   register block — so if they aren't committed and shipped, you contribute
+   nothing, and if they are, you contribute everything. A drift test asserting
+   each committed file equals its `agent.to_markdown` keeps the artifact honest.
+
+### TheLocal.register
+
+```ruby
+TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
+                  agents_dir: File.expand_path("the_local/agents", __dir__)) do |c|
+  c.agent "info",
+    description: "Use to learn what my_gem offers.",
+    tools: "Read",
+    body: "You explain my_gem, answering only from the reference. You make no changes.",
+    knowledge: MyGem::Reference.content
+end
+```
+
+- `gem_name` (first arg) filters to a host's direct dependencies.
+- `prefix` is the agent filename namespace; defaults to the gem name.
+- `scope` is a one-line domain phrase used to generate the delegation trigger.
+- `agents_dir` is the absolute path to the committed `.md` files; each agent
+  records its `source_path` there so the installer can copy it verbatim.
+
+### Conventions
+
+- The register block lives behind `begin require "the_local" … rescue LoadError`
+  so the gem still works when the_local is absent.
+- `guide.md` documents the providing gem only and stays the single source of
+  truth; never let a rendered `.md` drift from `agent.to_markdown`.
+- Commit the rendered `.md`; never render in the host at install time.

data/lib/the_local/reference.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TheLocal
+  # Loads the_local's own knowledge guide, embedded verbatim into its locals.
+  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

data/lib/the_local/refresh.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TheLocal
+  # Re-syncs a host's locals from its current bundle. Discovers providers by
+  # reading their committed agent files from each bundled gem's path on disk
+  # (see DiskProviders) — no gem code is loaded, so a fragile gem can't crash the
+  # install and a provider needs no register/require wiring at install time to
+  # contribute. Then gathers the direct and bundled gem names from a Bundler
+  # definition and runs a Sync. Both the provider discovery and the definition
+  # are injectable so the logic stays testable without a real bundle.
+  module Refresh
+    def self.call(destination:, definition: Bundler.definition,
+                  load_providers: -> { DiskProviders.load(registry: TheLocal.registry, specs: specs_from(definition)) })
+      TheLocal.reset!
+      load_providers.call
+      Sync.new(
+        registry: TheLocal.registry,
+        destination: destination,
+        direct_dependencies: definition.dependencies.map(&:name),
+        bundled_gems: definition.specs.map(&:name)
+      ).call
+    end
+
+    def self.specs_from(definition)
+      definition.specs.map { |spec| { name: spec.name, path: spec.full_gem_path } }
+    end
+  end
+end

data/lib/the_local/registry.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module TheLocal
+  # A registered provider (gem or app): its gem name, filename prefix, and a
+  # one-line scope used to generate the delegation trigger.
+  Provider = Data.define(:gem_name, :prefix, :scope)
+
+  # Accumulates the providers and agents contributed by everything that calls
+  # TheLocal.register. The install generator reads this to write .claude/agents/
+  # and the delegation trigger.
+  class Registry
+    def initialize
+      @agents = []
+      @providers = []
+    end
+
+    attr_reader :agents, :providers
+
+    def add(agent)
+      @agents << agent
+    end
+
+    def add_provider(provider)
+      @providers << provider
+    end
+
+    def clear
+      @agents.clear
+      @providers.clear
+    end
+  end
+
+  # Yielded to a provider's register block. Turns each `agent` call into an
+  # Agent tagged with the providing gem and namespaced under its prefix.
+  class Collector
+    def initialize(gem_name, prefix, registry, agents_dir: nil)
+      @gem_name = gem_name
+      @prefix = prefix
+      @registry = registry
+      @agents_dir = agents_dir
+    end
+
+    def agent(name, description:, tools:, body:, knowledge: nil)
+      @registry.add(
+        Agent.new(gem_name: @gem_name, prefix: @prefix, name: name,
+                  description: description, tools: tools, body: body, knowledge: knowledge,
+                  source_path: source_path_for(name))
+      )
+    end
+
+    private
+
+    def source_path_for(name)
+      return nil unless @agents_dir
+
+      File.join(@agents_dir, "#{@prefix}-#{name}.md")
+    end
+  end
+end

data/lib/the_local/scope.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module TheLocal
+  # Decides which providers' locals a host installs: its DIRECT dependencies plus
+  # the host project itself — never transitive dependencies. A registered
+  # provider is included when it is a direct dependency, or when it is not a
+  # bundled gem at all (which means it is the app registering its own locals).
+  module Scope
+    def self.allowed_gems(provider_gem_names:, direct_dependencies:, bundled_gems:)
+      provider_gem_names.uniq.select do |name|
+        direct_dependencies.include?(name) || !bundled_gems.include?(name)
+      end
+    end
+  end
+end

data/lib/the_local/sync.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TheLocal
+  # Orchestrates a full sync: resolves which gems are in scope (direct deps + the
+  # app), writes their agents, and writes the delegation trigger. Plain Ruby so
+  # both the install generator and the refresh rake task share one path. Returns
+  # the allowed gem names (for reporting).
+  class Sync
+    def initialize(registry:, destination:, direct_dependencies:, bundled_gems:)
+      @registry = registry
+      @destination = destination
+      @direct_dependencies = direct_dependencies
+      @bundled_gems = bundled_gems
+    end
+
+    def call
+      allowed = Scope.allowed_gems(
+        provider_gem_names: @registry.providers.map(&:gem_name),
+        direct_dependencies: @direct_dependencies,
+        bundled_gems: @bundled_gems
+      )
+      Installer.new(registry: @registry, destination: @destination, allowed_gems: allowed).call
+      TriggerWriter.new(registry: @registry, destination: @destination, allowed_gems: allowed).call
+      ProcessDocWriter.new(destination: @destination).call
+      allowed
+    end
+  end
+end

data/lib/the_local/tasks/the_local.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+namespace :the_local do
+  desc "Re-sync installed locals from the current bundle"
+  task refresh: :environment do
+    allowed = TheLocal::Refresh.call(destination: Rails.root.to_s)
+    puts "the_local: refreshed locals for #{allowed.join(", ")}"
+  end
+end

data/lib/the_local/the_local/agents/the_local-develop.md

@@ -0,0 +1,111 @@
+---
+name: the_local-develop
+description: Use PROACTIVELY to turn a gem into a the_local provider — scaffolding the companion, authoring the guide, and committing the rendered locals. MUST BE USED instead of wiring a provider by hand.
+tools: Read, Write, Edit, Grep
+---
+
+You turn a gem into a the_local provider following the reference's provider-author workflow: run `the_local:provider`, write guide.md as the single source of truth (your own gem only), tailor the register block, and hook the_local:build into the Rakefile. The deliverable is the committed, shipped lib/<gem>/the_local/agents/*.md — that is the whole contract a host reads from disk; a host never loads the gem, so unless those files are built, committed, and in the gemspec, the gem contributes nothing. You keep them in sync with agent.to_markdown.
+
+## TheLocal
+
+> **DO NOT** explore the the_local gem source code. This reference is the
+> complete user-facing API, embedded verbatim into every the_local local so
+> their guidance never drifts. Keep it the single source of truth.
+
+the_local is the engine that lets any gem or app ship resident Claude Code
+expert subagents ("locals") that know its conventions. A provider gem registers
+its locals once; the_local renders them to committed `.md` files and installs
+the aggregated set from every directly-depended provider into a consuming app's
+`.claude/agents/`, plus a delegation rule so the host's agent actually uses them.
+
+### The model
+
+- **Providers define locals.** A gem (or the app) calls `TheLocal.register` to
+  declare its locals; each `c.agent` becomes one local. The register block runs
+  only at build time, behind a soft `require "the_local"` guard so the gem still
+  works standalone.
+- **`the_local:build` renders committed `.md`.** The provider runs
+  `rake the_local:build`; `TheLocal::Builder` writes each agent to its
+  `source_path` under `lib/<gem>/the_local/agents/<prefix>-<name>.md`. The
+  rendered files are committed to the provider's repo. **These committed files
+  are the contract** — they are what a host reads. The register block + `guide.md`
+  are the source of truth they're built from.
+- **Install discovers committed `.md` on disk.** In a host, install reads each
+  direct dependency's committed `lib/**/the_local/agents/*.md` straight from its
+  gem path and copies them into `.claude/agents/` byte-for-byte — no provider
+  code is loaded and no register block runs in the host. Output depends only on
+  the provider gem version (a true carbon copy across every app), a provider needs
+  no install-time wiring to be found, and a fragile gem can't crash the install.
+- **The delegation trigger.** Install also writes a registry-generated block into
+  the host's `CLAUDE.md`/`AGENTS.md` telling the host agent to delegate to these
+  locals. This is what makes delegation actually happen.
+- **Direct-dependency scope.** Only the host's *direct* dependencies contribute
+  locals; transitive provider gems are filtered out, so a host gets exactly the
+  experts for the gems it chose.
+
+### Install (in any gem or app)
+
+1. Add the gem to the host's `Gemfile` (until it is on RubyGems, use a git
+   source: `gem "the_local", github: "DYB-Development/the_local"`), then
+   `bundle install`.
+2. Run `bundle exec the_local install`. This syncs every direct provider's
+   committed locals into `.claude/agents/` and writes the delegation trigger
+   into `CLAUDE.md`/`AGENTS.md`. It needs no Rails — a plain gem installs the
+   same way an app does.
+3. Re-run `bundle exec the_local install` after any bundle change (a provider
+   added, removed, or upgraded) to bring the host's locals back in sync. The
+   shell can automate this; the gem only exposes the command.
+
+Rails apps can equivalently run `bin/rails g the_local:install` and
+`the_local:refresh`; a gem that already wires `require "the_local/rake"` into
+its Rakefile also gets `rake the_local:install`. All three share one engine.
+
+### Author a provider (turn a gem into a provider)
+
+1. Run `bin/rails g the_local:provider <gem_name>` (pass `--scope`,
+   `--prefix`, `--worker` as needed). It scaffolds `lib/<gem>/reference.rb`, a
+   `lib/<gem>/reference/guide.md`, and a `lib/<gem>/the_local.rb` companion that
+   registers the standard interface; hooks `the_local:build` into the `Rakefile`;
+   requires the companion from the gem entrypoint; and builds the committed
+   `.md` for review.
+2. Write `guide.md` in this format — it is the single source of truth and is
+   embedded verbatim into every local. Document *your own* gem only: what it
+   does, how to install it, the conventions to enforce. Name companion gems but
+   do not explain their internals.
+3. Tailor the register block bodies and `scope` to your gem; the standard
+   interface is `info` (read-only explainer), `install` (sets the gem up in a
+   host), and a domain worker (`develop` for libraries, `operate` for CLIs).
+4. Run `rake the_local:build`, then **commit and ship**
+   `lib/<gem>/the_local/agents/*.md` (they must be in the gemspec's `files`).
+   This is the whole contract: a host discovers your locals by reading these
+   committed files from your gem on disk — it never loads your gem or runs your
+   register block — so if they aren't committed and shipped, you contribute
+   nothing, and if they are, you contribute everything. A drift test asserting
+   each committed file equals its `agent.to_markdown` keeps the artifact honest.
+
+### TheLocal.register
+
+```ruby
+TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
+                  agents_dir: File.expand_path("the_local/agents", __dir__)) do |c|
+  c.agent "info",
+    description: "Use to learn what my_gem offers.",
+    tools: "Read",
+    body: "You explain my_gem, answering only from the reference. You make no changes.",
+    knowledge: MyGem::Reference.content
+end
+```
+
+- `gem_name` (first arg) filters to a host's direct dependencies.
+- `prefix` is the agent filename namespace; defaults to the gem name.
+- `scope` is a one-line domain phrase used to generate the delegation trigger.
+- `agents_dir` is the absolute path to the committed `.md` files; each agent
+  records its `source_path` there so the installer can copy it verbatim.
+
+### Conventions
+
+- The register block lives behind `begin require "the_local" … rescue LoadError`
+  so the gem still works when the_local is absent.
+- `guide.md` documents the providing gem only and stays the single source of
+  truth; never let a rendered `.md` drift from `agent.to_markdown`.
+- Commit the rendered `.md`; never render in the host at install time.