the_local 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16b120e16f6b7ca6130882854eaafb3d7d5c70ae35e2fbab17e094f4cb365056
-  data.tar.gz: 32ef6ba59eac385d577fc5d068477ffd465e14130dadf09b47b7b9166bf07b89
+  metadata.gz: 16bc7ddfcc1ddab88976b10b156791a4e9a1985265d472517db9c56816d8022e
+  data.tar.gz: 57c2ec4821bd1165037311dad0720cbcf1a753770052e0f88ae5a879f4e8c2f7
 SHA512:
-  metadata.gz: e4fb273d9d3646d17a47f76b6c21048c38d62c2bf40ad491d609b9873e759e9063a47bdfc0f1eb1ccbf7cd33acea2757411b862aa5ec19ad5659d0fbbf3ba69f
-  data.tar.gz: 3fa1ff5e3989868bd713e7b21b1b253d866e9bc060b02294b1ea09f37b4056b8c0a2b4df9c009fcfa8198041ab301feab9985a1368daff5c6c561a1c072bf3b5
+  metadata.gz: bf6c8dfab319c69dd82da9654cee64085c0aca38253ad29bdd37794887ff8b35136c5c1f5288e4beab1688d767b4f7f53f02ca115c7d0abcc40b3d34eeac2e2f
+  data.tar.gz: 33a1549f7efedbcf20f3350f0c38224f03acf2865de2b7524037ba4c13889bf65b0ff75c2eff1d47a0ac6a0b4b57bdf57efcff4bd17b91a8c6a5bd1748258b8c

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-01
+
+- Installing no longer writes a `develop_process_rules.md` into host apps. The
+  `ProcessDocWriter`/`ProcessRules` machinery and its bundled doc are removed, so
+  `Sync`/`refresh` only install locals and the delegation trigger — a gem's
+  process conventions belong in its own guide, not propagated as a shared file.
+- A gem no longer installs its own locals into its own repo: `refresh` excludes
+  the gem being run from the direct-dependency set, so a provider working on
+  itself doesn't copy its locals back into `.claude/agents/`.
+
+## [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/refresh.rb

@@ -16,7 +16,7 @@ module TheLocal
       Sync.new(
         registry: TheLocal.registry,
         destination: destination,
-        direct_dependencies: definition.dependencies.map(&:name),
+        direct_dependencies: definition.dependencies.map(&:name) - [own_gem_name(definition, destination)],
         bundled_gems: definition.specs.map(&:name)
       ).call
     end
@@ -24,5 +24,10 @@ module TheLocal
     def self.specs_from(definition)
       definition.specs.map { |spec| { name: spec.name, path: spec.full_gem_path } }
     end
+
+    def self.own_gem_name(definition, destination)
+      here = File.expand_path(destination)
+      definition.specs.find { |spec| File.expand_path(spec.full_gem_path) == here }&.name
+    end
   end
 end

data/lib/the_local/sync.rb

@@ -21,7 +21,6 @@ module TheLocal
       )
       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

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.3.0"
 end

data/lib/the_local.rb

@@ -5,7 +5,6 @@ require_relative "the_local/agent"
 require_relative "the_local/registry"
 require_relative "the_local/installer"
 require_relative "the_local/trigger_writer"
-require_relative "the_local/process_doc_writer"
 require_relative "the_local/scope"
 require_relative "the_local/sync"
 require_relative "the_local/refresh"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: the_local
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - tylercschneider
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-11 00:00:00.000000000 Z
+date: 2026-07-02 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
@@ -38,9 +38,6 @@ files:
 - lib/the_local/cli.rb
 - lib/the_local/disk_providers.rb
 - lib/the_local/installer.rb
-- lib/the_local/process_doc_writer.rb
-- lib/the_local/process_rules.rb
-- lib/the_local/process_rules/develop_process_rules.md
 - lib/the_local/railtie.rb
 - lib/the_local/rake.rb
 - lib/the_local/reference.rb

data/lib/the_local/process_doc_writer.rb

@@ -1,48 +0,0 @@
-# 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

@@ -1,97 +0,0 @@
-# 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

@@ -1,17 +0,0 @@
-# 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