the_local 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16b120e16f6b7ca6130882854eaafb3d7d5c70ae35e2fbab17e094f4cb365056
-  data.tar.gz: 32ef6ba59eac385d577fc5d068477ffd465e14130dadf09b47b7b9166bf07b89
+  metadata.gz: 46515a04fbebe5b7f0b5bbd09fb5ac194b013e7cb08a10445849b0a3954b593a
+  data.tar.gz: 1840cb121e1d6c8cd0e458d945396d29c620db62f391c15836e1130a686fa682
 SHA512:
-  metadata.gz: e4fb273d9d3646d17a47f76b6c21048c38d62c2bf40ad491d609b9873e759e9063a47bdfc0f1eb1ccbf7cd33acea2757411b862aa5ec19ad5659d0fbbf3ba69f
-  data.tar.gz: 3fa1ff5e3989868bd713e7b21b1b253d866e9bc060b02294b1ea09f37b4056b8c0a2b4df9c009fcfa8198041ab301feab9985a1368daff5c6c561a1c072bf3b5
+  metadata.gz: ff8308ecbcc6adab431e1148f0a87a082de8e0a7441b390f4766886facda382fa0416f01a0b248340d8fb4eff4dd55aa2b794b82e249d49d52ea3b137f91dd98
+  data.tar.gz: a1e570c7f1a4341e61dfbf35805762bf6d7a1bdb1ad0175bce502603e3e35404b901ec3ef320acefa1a0765ba8aa20e917e36ddee93d880cd0f9bcfc1cbd06b7

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-06-20
+
+- `rake the_local:build` now refuses a guide that still holds line-leading
+  `TODO:` placeholders or is missing a canonical section, so a provider can't
+  ship a local that hasn't surfaced its gem's real interface (and would send
+  host agents digging into source).
+- Guides follow one canonical shape across every provider — **Interface**
+  (exact signatures), **Recipe** (copy-paste common task), **Install**,
+  **Conventions** — enforced at build and enumerated in the develop local's
+  authoring spec, so the consuming agent meets the same structure everywhere.
+  the_local's own guide models it with the `register` / `c.agent` signatures.
+- Scaffolded facet bodies (`info` / `install` / worker) are now a standard role
+  that defers to the guide and forbids reading source, identical across gems —
+  so the consuming agent gets consistent behavior, with gem-specifics in the
+  guide rather than hand-written per-provider bodies.
+- Install instructions and the provider generator now use the published
+  `gem "the_local"` instead of a `github:` git source, since the gem is on
+  RubyGems.
+
 ## [0.1.0] - 2026-06-02
 
 - Initial release.

data/PROVIDERS.md

@@ -74,10 +74,14 @@ 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.
+1. Write `reference/guide.md` as the complete user-facing API. The bar is that
+   a host agent can do your gem's work *from the guide alone, without opening
+   your source*: surface the literal interface (exact signatures — arguments,
+   required vs optional, return) and a complete copy-paste recipe for the common
+   task, not prose about them. 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.
+   Replace every `TODO:` — `rake the_local:build` refuses a guide that keeps one.
 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:
@@ -126,8 +130,8 @@ itself a non-Rails provider built this way — mirror its own wiring
    ```
 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).
+   needs it), and add `gem "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`.

data/lib/generators/the_local/provider_generator.rb

@@ -15,7 +15,7 @@ module TheLocal
     class ProviderGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
-      GEMFILE_LINE = %(gem "the_local", github: "DYB-Development/the_local")
+      GEMFILE_LINE = %(gem "the_local")
       RAKEFILE_REQUIRE = %(require "the_local/rake")
 
       desc "Scaffold the_local provider wiring (info/install/worker locals) into this gem"

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

@@ -3,13 +3,29 @@
 > **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.
+>
+> The bar for everything below: a host agent must be able to do <%= gem_name %>
+> work from this guide alone — exact signatures and a complete, copy-paste
+> recipe — without ever opening <%= gem_name %>'s source. If a signature or step
+> is missing, the agent will dig into source, which is the cost the_local exists
+> to remove. Replace every TODO; `rake the_local:build` refuses a guide that
+> still has one.
 
 TODO: One paragraph — what <%= gem_name %> is and the problem it solves.
 
-### What it offers
+### Interface
 
-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.
+TODO: The literal public API a host calls — every method/class/DSL entry with
+its exact signature: arguments, which are required vs optional, and what it
+returns. Give the signatures themselves, each with a one-line example, not prose
+about them. This is what the `info` and `<%= worker %>` locals answer from, so an
+agent never has to read source to recall how a call is shaped.
+
+### Recipe
+
+TODO: A complete, copy-paste implementation of the most common <%= gem_name %>
+task — the whole thing, not a fragment — so the `<%= worker %>` local reproduces
+it identically every time instead of re-deriving it from source.
 
 ### Install
 
@@ -19,7 +35,7 @@ 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
+### 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/the_local.rb.tt

@@ -15,23 +15,26 @@ require_relative "reference"
         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 %>.",
+          body: "You explain what <%= gem_name %> does and how to use it, answering only from " \
+                "your reference. You make no changes, and you never read <%= gem_name %>'s " \
+                "source — the reference is the complete interface.",
           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 %>.",
+          body: "You add <%= gem_name %> to the project and complete its setup by following your " \
+                "reference's Install section exactly, step by step. You do not invent steps it " \
+                "does not list, and you never read <%= gem_name %>'s source.",
           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 %>.",
+          body: "You do <%= gem_name %> work by following the Interface, Recipe, and Conventions " \
+                "in your reference exactly, so usage stays consistent across the host. You " \
+                "implement from the reference, never from <%= gem_name %>'s source.",
           knowledge: <%= module_name %>::Reference.content
       end
     end

data/lib/the_local/builder.rb

@@ -9,11 +9,22 @@ module TheLocal
   # 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:)
+    # A real placeholder is a line-leading "TODO:"; an inline mention of the
+    # marker (a guide documenting the convention) is left alone.
+    PLACEHOLDER = /^\s*TODO:/
+
+    # The canonical sections every guide must carry, so a consuming agent meets
+    # the same shape in every gem's local. Matched as header prefixes.
+    REQUIRED_SECTIONS = ["### Interface", "### Recipe", "### Install", "### Conventions"].freeze
+
+    def initialize(registry:, validate: false)
       @registry = registry
+      @validate = validate
     end
 
     def call
+      validate! if @validate
+
       buildable_agents.map do |agent|
         FileUtils.mkdir_p(File.dirname(agent.source_path))
         File.write(agent.source_path, agent.to_markdown)
@@ -23,6 +34,22 @@ module TheLocal
 
     private
 
+    def validate!
+      problems = buildable_agents.flat_map { |agent| problems_for(agent) }
+      return if problems.empty?
+
+      raise Error, "the_local: incomplete guide(s):\n- #{problems.join("\n- ")}"
+    end
+
+    def problems_for(agent)
+      markdown = agent.to_markdown
+      problems = []
+      problems << "#{agent.qualified_name}: TODO: placeholders remain" if markdown.match?(PLACEHOLDER)
+      missing = REQUIRED_SECTIONS.reject { |section| markdown.include?(section) }
+      problems << "#{agent.qualified_name}: missing #{missing.join(", ")}" if missing.any?
+      problems
+    end
+
     def buildable_agents
       @registry.agents.select(&:source_path)
     end

data/lib/the_local/rake.rb

@@ -11,7 +11,7 @@ require "the_local/builder"
 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
+    written = TheLocal::Builder.new(registry: TheLocal.registry, validate: true).call
     puts "the_local: built #{written.length} agent file(s)"
   end
 

data/lib/the_local/reference/guide.md

@@ -37,9 +37,7 @@ the aggregated set from every directly-depended provider into a consuming app's
 
 ### 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`.
+1. Add `gem "the_local"` to the host's `Gemfile`, 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
@@ -60,10 +58,18 @@ its Rakefile also gets `rake the_local:install`. All three share one engine.
    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.
+2. Write `guide.md` to the canonical shape — the same sections in every
+   provider, so the consuming agent meets one structure everywhere and
+   `rake the_local:build` rejects a guide missing one:
+   - **Interface** — every public call's *exact signature* (arguments, required
+     vs optional, return) as real signatures in a code block, not prose.
+   - **Recipe** — a complete copy-paste implementation of the common task.
+   - **Install** — the exact setup steps for *this* gem.
+   - **Conventions** — what the worker enforces to keep usage consistent.
+
+   The bar: a host agent does your gem's work from the guide alone, without ever
+   opening your source. Document your own gem only; 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).
@@ -75,7 +81,26 @@ its Rakefile also gets `rake the_local:install`. All three share one engine.
    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
+### Interface
+
+The complete public surface — every entry point with its exact signature, so a
+local answers from here instead of reading source.
+
+**Register locals (provider Ruby, behind a soft `require "the_local"` guard):**
+
+```ruby
+TheLocal.register(gem_name, prefix: gem_name, scope: nil, agents_dir: nil) { |c| … }
+#   Registers a provider and yields a Collector. gem_name is positional and
+#   filters to a host's direct dependencies; prefix is the filename namespace
+#   (defaults to gem_name); scope is the one-line delegation phrase; agents_dir
+#   is the absolute path to the committed .md files (each agent records its
+#   source_path there for the installer to copy verbatim).
+
+c.agent(name, description:, tools:, body:, knowledge: nil)
+#   Declares one local. name is positional; description, tools, body are
+#   required; knowledge — a String or Array of Strings, usually
+#   MyGem::Reference.content — is optional and appended below the body.
+```
 
 ```ruby
 TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
@@ -88,11 +113,62 @@ TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
 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.
+**Build (provider Rakefile, after `require "the_local/rake"`):**
+
+- `rake the_local:build` — renders each registered agent to its committed
+  `lib/<gem>/the_local/agents/<prefix>-<name>.md`. Refuses to render a guide that
+  still holds a `TODO:` placeholder or is missing a canonical section.
+- `rake the_local:install` — installs/refreshes this project's own locals.
+
+**Host (consuming app or gem):**
+
+- `bundle exec the_local install` — CLI; syncs direct providers' locals into
+  `.claude/agents/` and writes the delegation trigger. No Rails required.
+- `bin/rails g the_local:install` and `rake the_local:refresh` — Rails equivalents.
+- `bin/rails g the_local:provider <gem_name> [--prefix P] [--scope "…"] [--worker develop|operate]`
+  — scaffolds the provider wiring (Reference loader, guide, companion).
+
+### Recipe
+
+Turn a gem into a provider — the complete companion, copy-paste and rename:
+
+```ruby
+# lib/my_gem/the_local.rb
+require_relative "reference"
+
+module MyGem
+  module Companion
+    def self.register!
+      TheLocal.register("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 what my_gem does, answering only from your reference. " \
+                      "You make no changes and never read my_gem's source.",
+                knowledge: MyGem::Reference.content
+
+        c.agent "develop",
+                description: "Use PROACTIVELY for any my_gem work.",
+                tools: "Read, Write, Edit, Grep",
+                body: "You do my_gem work by following your reference's Interface, Recipe, " \
+                      "and Conventions exactly. You implement from the reference, never source.",
+                knowledge: MyGem::Reference.content
+      end
+    end
+  end
+end
+
+begin
+  require "the_local"
+  MyGem::Companion.register!
+rescue LoadError
+  # the_local not installed — my_gem works standalone.
+end
+```
+
+Then write `reference/guide.md` to the canonical shape, `rake the_local:build`,
+and commit `lib/my_gem/the_local/agents/*.md`.
 
 ### Conventions
 

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

@@ -45,9 +45,7 @@ the aggregated set from every directly-depended provider into a consuming app's
 
 ### 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`.
+1. Add `gem "the_local"` to the host's `Gemfile`, 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
@@ -68,10 +66,18 @@ its Rakefile also gets `rake the_local:install`. All three share one engine.
    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.
+2. Write `guide.md` to the canonical shape — the same sections in every
+   provider, so the consuming agent meets one structure everywhere and
+   `rake the_local:build` rejects a guide missing one:
+   - **Interface** — every public call's *exact signature* (arguments, required
+     vs optional, return) as real signatures in a code block, not prose.
+   - **Recipe** — a complete copy-paste implementation of the common task.
+   - **Install** — the exact setup steps for *this* gem.
+   - **Conventions** — what the worker enforces to keep usage consistent.
+
+   The bar: a host agent does your gem's work from the guide alone, without ever
+   opening your source. Document your own gem only; 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).
@@ -83,7 +89,26 @@ its Rakefile also gets `rake the_local:install`. All three share one engine.
    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
+### Interface
+
+The complete public surface — every entry point with its exact signature, so a
+local answers from here instead of reading source.
+
+**Register locals (provider Ruby, behind a soft `require "the_local"` guard):**
+
+```ruby
+TheLocal.register(gem_name, prefix: gem_name, scope: nil, agents_dir: nil) { |c| … }
+#   Registers a provider and yields a Collector. gem_name is positional and
+#   filters to a host's direct dependencies; prefix is the filename namespace
+#   (defaults to gem_name); scope is the one-line delegation phrase; agents_dir
+#   is the absolute path to the committed .md files (each agent records its
+#   source_path there for the installer to copy verbatim).
+
+c.agent(name, description:, tools:, body:, knowledge: nil)
+#   Declares one local. name is positional; description, tools, body are
+#   required; knowledge — a String or Array of Strings, usually
+#   MyGem::Reference.content — is optional and appended below the body.
+```
 
 ```ruby
 TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
@@ -96,11 +121,62 @@ TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
 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.
+**Build (provider Rakefile, after `require "the_local/rake"`):**
+
+- `rake the_local:build` — renders each registered agent to its committed
+  `lib/<gem>/the_local/agents/<prefix>-<name>.md`. Refuses to render a guide that
+  still holds a `TODO:` placeholder or is missing a canonical section.
+- `rake the_local:install` — installs/refreshes this project's own locals.
+
+**Host (consuming app or gem):**
+
+- `bundle exec the_local install` — CLI; syncs direct providers' locals into
+  `.claude/agents/` and writes the delegation trigger. No Rails required.
+- `bin/rails g the_local:install` and `rake the_local:refresh` — Rails equivalents.
+- `bin/rails g the_local:provider <gem_name> [--prefix P] [--scope "…"] [--worker develop|operate]`
+  — scaffolds the provider wiring (Reference loader, guide, companion).
+
+### Recipe
+
+Turn a gem into a provider — the complete companion, copy-paste and rename:
+
+```ruby
+# lib/my_gem/the_local.rb
+require_relative "reference"
+
+module MyGem
+  module Companion
+    def self.register!
+      TheLocal.register("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 what my_gem does, answering only from your reference. " \
+                      "You make no changes and never read my_gem's source.",
+                knowledge: MyGem::Reference.content
+
+        c.agent "develop",
+                description: "Use PROACTIVELY for any my_gem work.",
+                tools: "Read, Write, Edit, Grep",
+                body: "You do my_gem work by following your reference's Interface, Recipe, " \
+                      "and Conventions exactly. You implement from the reference, never source.",
+                knowledge: MyGem::Reference.content
+      end
+    end
+  end
+end
+
+begin
+  require "the_local"
+  MyGem::Companion.register!
+rescue LoadError
+  # the_local not installed — my_gem works standalone.
+end
+```
+
+Then write `reference/guide.md` to the canonical shape, `rake the_local:build`,
+and commit `lib/my_gem/the_local/agents/*.md`.
 
 ### Conventions
 

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

@@ -45,9 +45,7 @@ the aggregated set from every directly-depended provider into a consuming app's
 
 ### 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`.
+1. Add `gem "the_local"` to the host's `Gemfile`, 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
@@ -68,10 +66,18 @@ its Rakefile also gets `rake the_local:install`. All three share one engine.
    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.
+2. Write `guide.md` to the canonical shape — the same sections in every
+   provider, so the consuming agent meets one structure everywhere and
+   `rake the_local:build` rejects a guide missing one:
+   - **Interface** — every public call's *exact signature* (arguments, required
+     vs optional, return) as real signatures in a code block, not prose.
+   - **Recipe** — a complete copy-paste implementation of the common task.
+   - **Install** — the exact setup steps for *this* gem.
+   - **Conventions** — what the worker enforces to keep usage consistent.
+
+   The bar: a host agent does your gem's work from the guide alone, without ever
+   opening your source. Document your own gem only; 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).
@@ -83,7 +89,26 @@ its Rakefile also gets `rake the_local:install`. All three share one engine.
    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
+### Interface
+
+The complete public surface — every entry point with its exact signature, so a
+local answers from here instead of reading source.
+
+**Register locals (provider Ruby, behind a soft `require "the_local"` guard):**
+
+```ruby
+TheLocal.register(gem_name, prefix: gem_name, scope: nil, agents_dir: nil) { |c| … }
+#   Registers a provider and yields a Collector. gem_name is positional and
+#   filters to a host's direct dependencies; prefix is the filename namespace
+#   (defaults to gem_name); scope is the one-line delegation phrase; agents_dir
+#   is the absolute path to the committed .md files (each agent records its
+#   source_path there for the installer to copy verbatim).
+
+c.agent(name, description:, tools:, body:, knowledge: nil)
+#   Declares one local. name is positional; description, tools, body are
+#   required; knowledge — a String or Array of Strings, usually
+#   MyGem::Reference.content — is optional and appended below the body.
+```
 
 ```ruby
 TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
@@ -96,11 +121,62 @@ TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
 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.
+**Build (provider Rakefile, after `require "the_local/rake"`):**
+
+- `rake the_local:build` — renders each registered agent to its committed
+  `lib/<gem>/the_local/agents/<prefix>-<name>.md`. Refuses to render a guide that
+  still holds a `TODO:` placeholder or is missing a canonical section.
+- `rake the_local:install` — installs/refreshes this project's own locals.
+
+**Host (consuming app or gem):**
+
+- `bundle exec the_local install` — CLI; syncs direct providers' locals into
+  `.claude/agents/` and writes the delegation trigger. No Rails required.
+- `bin/rails g the_local:install` and `rake the_local:refresh` — Rails equivalents.
+- `bin/rails g the_local:provider <gem_name> [--prefix P] [--scope "…"] [--worker develop|operate]`
+  — scaffolds the provider wiring (Reference loader, guide, companion).
+
+### Recipe
+
+Turn a gem into a provider — the complete companion, copy-paste and rename:
+
+```ruby
+# lib/my_gem/the_local.rb
+require_relative "reference"
+
+module MyGem
+  module Companion
+    def self.register!
+      TheLocal.register("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 what my_gem does, answering only from your reference. " \
+                      "You make no changes and never read my_gem's source.",
+                knowledge: MyGem::Reference.content
+
+        c.agent "develop",
+                description: "Use PROACTIVELY for any my_gem work.",
+                tools: "Read, Write, Edit, Grep",
+                body: "You do my_gem work by following your reference's Interface, Recipe, " \
+                      "and Conventions exactly. You implement from the reference, never source.",
+                knowledge: MyGem::Reference.content
+      end
+    end
+  end
+end
+
+begin
+  require "the_local"
+  MyGem::Companion.register!
+rescue LoadError
+  # the_local not installed — my_gem works standalone.
+end
+```
+
+Then write `reference/guide.md` to the canonical shape, `rake the_local:build`,
+and commit `lib/my_gem/the_local/agents/*.md`.
 
 ### Conventions
 

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

@@ -45,9 +45,7 @@ the aggregated set from every directly-depended provider into a consuming app's
 
 ### 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`.
+1. Add `gem "the_local"` to the host's `Gemfile`, 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
@@ -68,10 +66,18 @@ its Rakefile also gets `rake the_local:install`. All three share one engine.
    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.
+2. Write `guide.md` to the canonical shape — the same sections in every
+   provider, so the consuming agent meets one structure everywhere and
+   `rake the_local:build` rejects a guide missing one:
+   - **Interface** — every public call's *exact signature* (arguments, required
+     vs optional, return) as real signatures in a code block, not prose.
+   - **Recipe** — a complete copy-paste implementation of the common task.
+   - **Install** — the exact setup steps for *this* gem.
+   - **Conventions** — what the worker enforces to keep usage consistent.
+
+   The bar: a host agent does your gem's work from the guide alone, without ever
+   opening your source. Document your own gem only; 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).
@@ -83,7 +89,26 @@ its Rakefile also gets `rake the_local:install`. All three share one engine.
    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
+### Interface
+
+The complete public surface — every entry point with its exact signature, so a
+local answers from here instead of reading source.
+
+**Register locals (provider Ruby, behind a soft `require "the_local"` guard):**
+
+```ruby
+TheLocal.register(gem_name, prefix: gem_name, scope: nil, agents_dir: nil) { |c| … }
+#   Registers a provider and yields a Collector. gem_name is positional and
+#   filters to a host's direct dependencies; prefix is the filename namespace
+#   (defaults to gem_name); scope is the one-line delegation phrase; agents_dir
+#   is the absolute path to the committed .md files (each agent records its
+#   source_path there for the installer to copy verbatim).
+
+c.agent(name, description:, tools:, body:, knowledge: nil)
+#   Declares one local. name is positional; description, tools, body are
+#   required; knowledge — a String or Array of Strings, usually
+#   MyGem::Reference.content — is optional and appended below the body.
+```
 
 ```ruby
 TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
@@ -96,11 +121,62 @@ TheLocal.register("my_gem", prefix: "my_gem", scope: "one-line domain phrase",
 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.
+**Build (provider Rakefile, after `require "the_local/rake"`):**
+
+- `rake the_local:build` — renders each registered agent to its committed
+  `lib/<gem>/the_local/agents/<prefix>-<name>.md`. Refuses to render a guide that
+  still holds a `TODO:` placeholder or is missing a canonical section.
+- `rake the_local:install` — installs/refreshes this project's own locals.
+
+**Host (consuming app or gem):**
+
+- `bundle exec the_local install` — CLI; syncs direct providers' locals into
+  `.claude/agents/` and writes the delegation trigger. No Rails required.
+- `bin/rails g the_local:install` and `rake the_local:refresh` — Rails equivalents.
+- `bin/rails g the_local:provider <gem_name> [--prefix P] [--scope "…"] [--worker develop|operate]`
+  — scaffolds the provider wiring (Reference loader, guide, companion).
+
+### Recipe
+
+Turn a gem into a provider — the complete companion, copy-paste and rename:
+
+```ruby
+# lib/my_gem/the_local.rb
+require_relative "reference"
+
+module MyGem
+  module Companion
+    def self.register!
+      TheLocal.register("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 what my_gem does, answering only from your reference. " \
+                      "You make no changes and never read my_gem's source.",
+                knowledge: MyGem::Reference.content
+
+        c.agent "develop",
+                description: "Use PROACTIVELY for any my_gem work.",
+                tools: "Read, Write, Edit, Grep",
+                body: "You do my_gem work by following your reference's Interface, Recipe, " \
+                      "and Conventions exactly. You implement from the reference, never source.",
+                knowledge: MyGem::Reference.content
+      end
+    end
+  end
+end
+
+begin
+  require "the_local"
+  MyGem::Companion.register!
+rescue LoadError
+  # the_local not installed — my_gem works standalone.
+end
+```
+
+Then write `reference/guide.md` to the canonical shape, `rake the_local:build`,
+and commit `lib/my_gem/the_local/agents/*.md`.
 
 ### Conventions
 

data/lib/the_local/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TheLocal
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: the_local
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - tylercschneider
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-11 00:00:00.000000000 Z
+date: 2026-06-22 00:00:00.000000000 Z
 dependencies: []
 description: the_local lets any gem or app declare Claude Code subagents ("locals")
   that know its conventions, and installs the aggregated set from every installed