the_local 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 16b120e16f6b7ca6130882854eaafb3d7d5c70ae35e2fbab17e094f4cb365056
+  data.tar.gz: 32ef6ba59eac385d577fc5d068477ffd465e14130dadf09b47b7b9166bf07b89
+SHA512:
+  metadata.gz: e4fb273d9d3646d17a47f76b6c21048c38d62c2bf40ad491d609b9873e759e9063a47bdfc0f1eb1ccbf7cd33acea2757411b862aa5ec19ad5659d0fbbf3ba69f
+  data.tar.gz: 3fa1ff5e3989868bd713e7b21b1b253d866e9bc060b02294b1ea09f37b4056b8c0a2b4df9c009fcfa8198041ab301feab9985a1368daff5c6c561a1c072bf3b5

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-02
+
+- Initial release.
+- `TheLocal.register` API for gems and apps to contribute Claude Code locals,
+  behind a soft `require "the_local"` guard so providers work standalone.
+- Provider build model: `TheLocal::Builder` + `rake the_local:build` render each
+  agent to a committed `.md`; the installer copies those files verbatim.
+- `the_local:install` and `the_local:provider` Rails generators, plus a
+  rake-only `the_local:refresh` to re-sync a host after bundle changes.
+- Direct-dependency install scope and a registry-generated delegation trigger
+  written into the host's `CLAUDE.md`/`AGENTS.md`.
+- the_local dogfoods itself as a provider (`the_local-info`/`-install`/`-develop`)
+  and propagates a canonical develop-process doc into every host.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 tylercschneider
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/PROVIDERS.md

@@ -0,0 +1,135 @@
+# Becoming a provider
+
+`the_local` has two sides. The **consuming-app** side (`bundle exec the_local
+install`, or `bin/rails g the_local:install` in a Rails app) installs the locals
+of a project's direct dependencies into `.claude/agents/` — by reading each
+dependency's committed `.md` straight from its gem path on disk. This document
+covers the **provider** side: how a gem contributes those locals.
+
+A provider registers its agents with `TheLocal.register` behind a soft
+`require "the_local"` guard, so the gem keeps working when `the_local` is absent.
+
+## Build at home, copy verbatim
+
+The agent *definition* (`the_local.rb` + `guide.md`) is the single source of
+truth. The provider **renders it to committed `.md` files** with a gem-side
+`the_local:build` task and commits those files to its own repo; the host install
+then **reads them straight from your gem's path on disk and copies them verbatim**
+into `.claude/agents/`. No provider code is loaded in the host and no register
+block runs there — the committed, shipped `.md` is the entire contract. If those
+files aren't committed and in the gemspec's `files`, the gem contributes nothing;
+if they are, it contributes everything, with no install-time wiring.
+
+So the rendered output depends only on the provider gem version — every app that
+installs the same version gets a byte-identical local, instead of the host
+re-rendering (and possibly drifting) from an in-memory definition. The committed
+`.md` is a reviewable build artifact: it lands in the gem's own PR. Keep it in
+sync with the definition by re-running `the_local:build` and committing the
+result whenever you change the guide or an agent's `body:`/`description:`.
+
+## The common command interface
+
+`the_local` exists to give every gem the **same command interface to apps**, so
+a host agent always finds the same shape no matter which gem it's delegating to.
+A provider exposes three lifecycle facets:
+
+| Facet | Purpose | Typical tools |
+|---|---|---|
+| **`info`** | Read-only. Explains what the gem offers — its API and conventions. Makes no changes. | `Read` |
+| **`install`** | Adds the gem to a host and sets it up **correctly** — the exact, gem-specific steps. | `Bash, Read, Edit` |
+| **worker** | The proactive domain worker the host routes real work to. Named `develop` for libraries you build against, `operate` for CLIs you run. | per domain |
+
+`info` and `install` are universal; the worker's name varies by the gem's
+nature. Every agent embeds the provider's knowledge (`Reference.content`)
+verbatim — that knowledge is the single source of truth, so the locals never
+drift from the docs.
+
+## Adopting it — Rails-engine gems (generator)
+
+If the gem has Rails available in development (e.g. a mountable engine), scaffold
+the wiring with the generator:
+
+```bash
+bin/rails g the_local:provider <gem_name> \
+  --scope "one-line phrase describing the gem's domain" \
+  [--prefix <filename-namespace>] \
+  [--worker develop|operate]
+```
+
+It creates, and wires up:
+
+```
+lib/<gem>/reference.rb           # the Reference loader (single source of truth)
+lib/<gem>/reference/guide.md     # the knowledge, with TODO markers to fill in
+lib/<gem>/the_local.rb           # Companion.register! — info / install / <worker>
+lib/<gem>/the_local/agents/*.md  # the rendered locals, built + committed
+Gemfile                          # + gem "the_local", github: …  (soft, dev/test)
+lib/<gem>.rb                     # + require_relative "<gem>/the_local"
+Rakefile                         # + require "the_local/rake"  (rake the_local:build)
+```
+
+The generator builds the `.md` once on scaffold so they land in the diff for
+review. They are rendered from the TODO placeholder definition, so you rebuild
+them after filling in the real content (below).
+
+Then **fill in the scaffold** — this is the real work the generator can't do:
+
+1. Write `reference/guide.md` as the complete user-facing API. Its **Install**
+   section must be the exact, correct steps for *this* gem (for an engine:
+   add the gem → `bundle install` → install + run migrations → wire concerns /
+   initializers), not a generic placeholder.
+2. Tailor the three agent `body:` strings in `the_local.rb` to the gem.
+3. **Rebuild and commit the locals.** The scaffold built `.md` from the TODO
+   placeholders, so regenerate them from your real definition and commit them:
+
+   ```bash
+   rake the_local:build
+   git add lib/<gem>/the_local/agents
+   ```
+
+   Rebuild whenever the guide or an agent's `body:`/`description:` changes — the
+   host copies these bytes verbatim, so a stale commit ships stale locals.
+4. Add a `companion_test` asserting the facets register and each embeds
+   `Reference.content`, plus a **drift test** asserting each committed file
+   equals its `agent.to_markdown` (so a forgotten rebuild fails CI). See
+   `test/the_local/companion_test.rb` — the_local is its own provider and uses
+   exactly this wiring.
+
+## Adopting it — non-Rails gems (manual)
+
+A plain gem has no `bin/rails`, so do the same things by hand. `the_local` is
+itself a non-Rails provider built this way — mirror its own wiring
+(`lib/the_local/the_local.rb`, `lib/the_local/reference.rb`, the committed
+`lib/the_local/the_local/agents/`, and the `Rakefile`):
+
+1. `lib/<gem>/reference.rb` — a `Reference` module with `DIR`, `content`, and
+   `read(name)` reading from `lib/<gem>/reference/`.
+2. `lib/<gem>/reference/guide.md` — the knowledge (single source of truth).
+3. `lib/<gem>/the_local.rb` — a `Companion.register!` that calls `TheLocal.register`
+   with an `agents_dir` (where the committed `.md` live) and declares the
+   `info` / `install` / worker agents, followed by the guard:
+
+   ```ruby
+   TheLocal.register("<gem>", scope: "…",
+                     agents_dir: File.expand_path("the_local/agents", __dir__)) do |c|
+     # c.agent "info", …
+   end
+   ```
+
+   ```ruby
+   begin
+     require "the_local"
+     <Gem>::Companion.register!
+   rescue LoadError
+     # the_local not installed — <gem> works standalone.
+   end
+   ```
+4. `require_relative "<gem>/the_local"` from the gem's entrypoint (so your own
+   `the_local:build` and standalone use load the register block — a host never
+   needs it), and add `gem "the_local", github: "DYB-Development/the_local"` to
+   the Gemfile (dev/test — an optional companion, not a hard dependency).
+5. Add `require "the_local/rake"` to the `Rakefile`, then build, commit, and
+   **ship** the rendered locals — `rake the_local:build && git add
+   lib/<gem>/the_local/agents`, and make sure they're in the gemspec's `files`.
+   These committed bytes are the whole contract — what the host reads from disk;
+   rebuild and recommit on every change.

data/README.md

@@ -0,0 +1,72 @@
+# TheLocal
+
+Resident Claude Code expert subagents ("locals"), contributed by the gems an app
+uses. Any gem or app declares the locals that know its conventions; `the_local`
+aggregates the locals of an app's installed providers into its
+`.claude/agents/`, plus a delegation rule so the app's agent actually uses them.
+
+A "local" is a Claude Code subagent that knows one gem's conventions cold. The
+host's orchestrating agent delegates that gem's work to it, so usage stays
+consistent instead of drifting.
+
+## Installation
+
+Add it to your Gemfile:
+
+```ruby
+gem "the_local"
+```
+
+or install it directly with `gem install the_local`. To track an unreleased
+change, point at the repo instead:
+
+```ruby
+gem "the_local", github: "DYB-Development/the_local"
+```
+
+The gem's core is Rails-free, but the primary documented workflow uses the
+`bin/rails g the_local:install` / `the_local:provider` generators, so those steps
+assume a Rails host. The `the_local:refresh` rake task and the register API work
+without Rails.
+
+## Usage
+
+There are two sides.
+
+**Consuming app** — install the locals of the app's direct dependencies (and the
+app's own) into `.claude/agents/`, and write the delegation trigger:
+
+```bash
+bin/rails g the_local:install
+```
+
+Install **copies each provider's committed `.md` verbatim** — the rendering
+happens in the provider gem at build time, not in the host — so every app on the
+same gem version gets a byte-identical local. Re-run `the_local:refresh` (rake)
+after a `bundle install`/`update` to re-sync.
+
+**Provider gem** — contribute the locals an app installs. A gem registers its
+agents with `TheLocal.register` behind a soft guard, exposing the common command
+interface (`info` / `install` / worker), then renders them to committed `.md`
+with `rake the_local:build`. Scaffold it with:
+
+```bash
+bin/rails g the_local:provider <gem_name> --scope "the gem's domain"
+```
+
+See [PROVIDERS.md](PROVIDERS.md) for the full provider guide, including the
+manual steps for non-Rails gems.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/DYB-Development/the_local.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]
+
+require "the_local"
+require "the_local/rake"

data/exe/the_local

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "the_local/cli"
+
+TheLocal::CLI.new(ARGV).call

data/lib/generators/the_local/install_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "the_local"
+
+module TheLocal
+  module Generators
+    # `bin/rails g the_local:install` — installs the locals contributed by the
+    # app's direct dependencies into .claude/agents/, and writes the delegation
+    # trigger. A thin wrapper over Refresh, which discovers providers from each
+    # bundled gem's committed agents on disk.
+    class InstallGenerator < Rails::Generators::Base
+      desc "Install the Claude Code locals of this app's direct dependencies"
+
+      def install_locals
+        allowed = Refresh.call(destination: destination_root)
+        say "the_local: installed locals for #{allowed.join(", ")}", :green
+      end
+    end
+  end
+end

data/lib/generators/the_local/provider_generator.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "the_local/builder"
+
+module TheLocal
+  module Generators
+    # `bin/rails g the_local:provider <gem_name>` — scaffolds the provider side
+    # of the_local into a gem: a Reference loader, a knowledge guide, and a
+    # Companion that registers the common command interface (info / install /
+    # worker) via TheLocal.register behind a soft `require "the_local"` guard.
+    #
+    # The companion app side is `the_local:install`; this is its mirror for the
+    # gems that *contribute* locals. See PROVIDERS.md.
+    class ProviderGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      GEMFILE_LINE = %(gem "the_local", github: "DYB-Development/the_local")
+      RAKEFILE_REQUIRE = %(require "the_local/rake")
+
+      desc "Scaffold the_local provider wiring (info/install/worker locals) into this gem"
+
+      argument :gem_name, type: :string, desc: "The providing gem's name, e.g. citizen"
+      class_option :prefix, type: :string,
+                            desc: "Agent filename namespace (defaults to the gem name)"
+      class_option :scope, type: :string, default: "TODO: one-line phrase describing this gem's domain",
+                           desc: "One-line domain phrase used in the delegation trigger"
+      class_option :worker, type: :string, default: "develop",
+                            desc: "Name of the domain worker facet (develop for libraries, operate for CLIs)"
+
+      def relocate_to_gem_root
+        self.destination_root = gem_root
+      end
+
+      def create_reference
+        template "reference.rb.tt", "lib/#{lib_path}/reference.rb"
+      end
+
+      def create_guide
+        template "guide.md.tt", "lib/#{lib_path}/reference/guide.md"
+      end
+
+      def create_companion
+        template "the_local.rb.tt", "lib/#{lib_path}/the_local.rb"
+      end
+
+      def add_to_gemfile
+        return if gem_name == "the_local"
+
+        gemfile = File.join(destination_root, "Gemfile")
+        return unless File.exist?(gemfile)
+        return if File.read(gemfile).include?(GEMFILE_LINE)
+
+        append_to_file "Gemfile",
+                       "\n# Optional companion: #{gem_name} registers its locals with the_local " \
+                       "when present.\n# Registration is guarded, so #{gem_name} works standalone.\n#{GEMFILE_LINE}\n"
+      end
+
+      def require_from_entrypoint
+        entrypoint = File.join("lib", "#{lib_path}.rb")
+        return unless File.exist?(File.join(destination_root, entrypoint))
+        return if File.read(File.join(destination_root, entrypoint)).include?(require_line)
+
+        append_to_file entrypoint,
+                       "\n# Register #{gem_name}'s locals when the_local is present (no-op otherwise).\n" \
+                       "#{require_line}\n"
+      end
+
+      def hook_build_task_into_rakefile
+        return unless File.exist?(File.join(destination_root, "Rakefile"))
+        return if File.read(File.join(destination_root, "Rakefile")).include?(RAKEFILE_REQUIRE)
+
+        append_to_file "Rakefile",
+                       "\n# Render #{gem_name}'s committed the_local agent files: `rake the_local:build`.\n" \
+                       "require \"#{lib_path}\"\n#{RAKEFILE_REQUIRE}\n"
+      end
+
+      # Render the committed .md files now, so they land in the diff for review.
+      # Loading the companion registers this gem's locals; reset first so only
+      # they are built, not anything else the process may have registered.
+      def build_agent_files
+        companion = File.join(destination_root, "lib", lib_path, "the_local.rb")
+        return unless File.exist?(companion)
+
+        TheLocal.reset!
+        load companion
+        TheLocal::Builder.new(registry: TheLocal.registry).call
+      end
+
+      private
+
+      def require_line
+        %(require_relative "#{File.basename(lib_path)}/the_local")
+      end
+
+      def prefix
+        options[:prefix] || gem_name
+      end
+
+      # Thor renders templates via File.binread, so the ERB buffer is ASCII-8BIT.
+      # A UTF-8 scope would flip the buffer mid-render and then clash with the
+      # template's own non-ASCII literals; match the buffer's encoding to avoid it.
+      def scope
+        options[:scope]&.b
+      end
+
+      def worker
+        options[:worker]
+      end
+
+      def gem_root
+        ascend_to_gemspec(destination_root) || destination_root
+      end
+
+      def ascend_to_gemspec(start)
+        dir = File.expand_path(start)
+        loop do
+          return dir if Dir.glob(File.join(dir, "*.gemspec")).any?
+
+          parent = File.dirname(dir)
+          return nil if parent == dir
+
+          dir = parent
+        end
+      end
+
+      def lib_path
+        gem_name.tr("-", "/")
+      end
+
+      def module_name
+        gem_name.split("-").map { |segment| segment.split("_").map(&:capitalize).join }.join("::")
+      end
+
+      def open_module
+        module_name.split("::").map { |name| "module #{name}" }.join("\n")
+      end
+
+      def close_module
+        module_name.split("::").map { "end" }.join("\n")
+      end
+    end
+  end
+end

data/lib/generators/the_local/templates/guide.md.tt

@@ -0,0 +1,25 @@
+## <%= module_name %>
+
+> **DO NOT** explore the <%= gem_name %> gem source code. This reference is the
+> complete user-facing API, embedded verbatim into every <%= gem_name %> local so
+> their guidance never drifts. Keep it the single source of truth.
+
+TODO: One paragraph — what <%= gem_name %> 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 `<%= worker %>` locals answer from.
+
+### Install
+
+TODO: The exact, correct steps to add <%= gem_name %> to a host and set it up —
+this is what the `install` local follows. Be specific to how <%= gem_name %> 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.
+
+### <%= module_name %> conventions
+
+TODO: The conventions the `<%= worker %>` local must enforce when doing
+<%= gem_name %> work, so usage stays consistent across the host.

data/lib/generators/the_local/templates/reference.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+<%= open_module %>
+  # Single source of truth for <%= gem_name %>'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
+<%= close_module %>

data/lib/generators/the_local/templates/the_local.rb.tt

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "reference"
+
+<%= open_module %>
+  # Registers <%= gem_name %>'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
+  # `<%= worker %>` (the proactive domain worker). Soft dependency: registration
+  # is a no-op when the_local is absent.
+  module Companion
+    def self.register!
+      TheLocal.register("<%= gem_name %>"<%= ", prefix: \"#{prefix}\"" unless prefix == gem_name %>, scope: "<%= scope %>",
+                        agents_dir: File.expand_path("the_local/agents", __dir__)) do |c|
+        c.agent "info",
+          description: "Use to learn what <%= gem_name %> offers — its API and conventions.",
+          tools: "Read",
+          body: "You explain what <%= gem_name %> does and how to use it, answering from the " \
+                "reference. You make no changes. TODO: tailor this body to <%= gem_name %>.",
+          knowledge: <%= module_name %>::Reference.content
+
+        c.agent "install",
+          description: "Use to add <%= gem_name %> to a project and set it up correctly.",
+          tools: "Bash, Read, Edit",
+          body: "You add <%= gem_name %> to the project and complete its setup, following the " \
+                "reference's install section exactly. TODO: tailor this body to <%= gem_name %>.",
+          knowledge: <%= module_name %>::Reference.content
+
+        c.agent "<%= worker %>",
+          description: "Use PROACTIVELY for any <%= gem_name %> 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 <%= gem_name %> work following the reference's conventions. TODO: tailor " \
+                "this body to <%= gem_name %>.",
+          knowledge: <%= module_name %>::Reference.content
+      end
+    end
+  end
+<%= close_module %>
+
+begin
+  require "the_local"
+  <%= module_name %>::Companion.register!
+rescue LoadError
+  # the_local not installed — <%= gem_name %> works standalone.
+end

data/lib/the_local/agent.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module TheLocal
+  # An immutable description of one Claude Code subagent contributed by a
+  # provider (a gem or the app). Renders to a `.claude/agents/*.md` definition.
+  #
+  # +gem_name+ is the providing gem (used to filter to a host's direct
+  # dependencies). +prefix+ is the filename namespace (often a shorter alias,
+  # e.g. gem "keystone_ui" → prefix "keystone"). +knowledge+ is a string or
+  # array of strings appended below the role body — the provider's reference(s).
+  # +source_path+ is the absolute path to the provider's committed, pre-rendered
+  # .md file; the host installer copies it verbatim. It stays nil until a
+  # provider supplies an agents_dir, so existing providers keep working.
+  Agent = Data.define(:gem_name, :prefix, :name, :description, :tools, :body, :knowledge, :source_path) do
+    def initialize(source_path: nil, **args)
+      super
+    end
+
+    def qualified_name
+      "#{prefix}-#{name}"
+    end
+
+    def filename
+      "#{qualified_name}.md"
+    end
+
+    def to_markdown
+      <<~MARKDOWN
+        ---
+        name: #{qualified_name}
+        description: #{description}
+        tools: #{tools}
+        ---
+
+        #{body}
+
+        #{Array(knowledge).join("\n\n")}
+      MARKDOWN
+    end
+  end
+end

data/lib/the_local/builder.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module TheLocal
+  # Renders each registered agent's markdown to its committed source_path, so a
+  # provider gem can commit the files and the host installer later copies them
+  # verbatim (rather than rendering at install time). Plain Ruby — driven by the
+  # the_local:build rake task a provider runs. Agents that declared no agents_dir
+  # (and so have no source_path) are skipped: there is nowhere to write them.
+  class Builder
+    def initialize(registry:)
+      @registry = registry
+    end
+
+    def call
+      buildable_agents.map do |agent|
+        FileUtils.mkdir_p(File.dirname(agent.source_path))
+        File.write(agent.source_path, agent.to_markdown)
+        agent.source_path
+      end
+    end
+
+    private
+
+    def buildable_agents
+      @registry.agents.select(&:source_path)
+    end
+  end
+end

data/lib/the_local/cli.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "the_local"
+
+module TheLocal
+  # Rails-free entrypoint for the `the_local` executable. `the_local install`
+  # syncs the current bundle's locals into .claude/agents/, so a plain gem can
+  # install without a Rails generator or a Rakefile.
+  class CLI
+    def initialize(argv, out: $stdout)
+      @argv = argv
+      @out = out
+    end
+
+    def call
+      case @argv.first
+      when "install" then install
+      else usage
+      end
+    end
+
+    private
+
+    def install
+      allowed = Refresh.call(destination: Dir.pwd)
+      @out.puts "the_local: installed locals for #{allowed.join(", ")}"
+      @out.puts "Restart your Claude Code session to use them — agents load at startup."
+    end
+
+    def usage
+      @out.puts "Usage: the_local install"
+    end
+  end
+end