brut 0.0.26 → 0.0.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 327b83333a37823010e1d2763646d56bd503d505d6c965ddc5d0d8098ecd9299
-  data.tar.gz: d12d8d46f6e459d97f3489218302da647e073ac4d8e48cf57cd1d1fee998c6a1
+  metadata.gz: '0212844b1dd1d69682b3b4ec4ab2a9917087b3d931916e39d9ccf0239d6a2f9c'
+  data.tar.gz: 871a018ce32f9d1f556eef7950570c8a4dd072736be733e6a7a925e14a8c968c
 SHA512:
-  metadata.gz: a55e3607d5d127e74f93864f6dc19fad6dc2a0631e56559cf92df4b5762771d82d5bc0c5a2d289d6948a0899568e0138e503fea98f91d42007cefb9b3e83482b
-  data.tar.gz: e901897e8d8eb2a2ef08bc4e5efacc0c3a13f6981f8523a2e0db3ade740f648923ecb29e9634ea133dd16efccedeecb0b9ec06f820c0b4d77b7f34068f96d540
+  metadata.gz: eb49d9e87e53893962c86e2a26ca54f8c82cc9a8fbbeac5e12e1d7aaa4b47cbb13de6ab9429779422a6bc075dd3f4499bf6b18accb7c7ff87943eb32afda0342
+  data.tar.gz: c8f56cb073d99b1b3f304afe2daf3839b6b2b39ebe492bde05f00037ebf448459049560d3b32707450b65e32916366ea766d57598752026d0c025d1db63d7fe7

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brut (0.0.26)
+    brut (0.0.28)
       concurrent-ruby
       i18n
       irb

data/brutrb.com/.vitepress/config.mjs

@@ -39,6 +39,7 @@ export default defineConfig({
         items: [
           { text: "Routes", link: "/routes" },
           { text: "Pages", link: "/pages" },
+          { text: "Layouts", link: "/layouts" },
           { text: "Forms", link: "/forms" },
           { text: "Handlers and Actions", link: "/handlers" },
           { text: "Components", link: "/components" },
@@ -89,6 +90,7 @@ export default defineConfig({
           { text: "Middleware", link: "/middleware" },
           { text: "Instrumentation", link: "/instrumentation" },
           { text: "Security", link: "/security" },
+          { text: "LSP Support", link: "/lsp" },
         ],
       },
       {

data/brutrb.com/ai.md

@@ -58,7 +58,7 @@ The logo is level 4 - ChatGPT created it. I'd love to have a real person make a
 something to get this launched.  Please reach out if you want to make a better one + other assets. I'm
 willing to pay a real person.
 
-## AI That Teachs You About Brut Does Not Currently Exist
+## AI Completions Should Be Viewed with Skepticism
 
 Due to how LLMs work, there is naturally nothing in any model about Brut.  Anything an
 existing model tells you about Brut is **100% untrustworthy**.  We hope to allow LLMs to consume Brut's
@@ -66,3 +66,8 @@ code, documentation, and examples, so it can be an additional source of help, bu
 the case.
 
 **Do not ask an LLM about Brut** until this part of the documentation changes.
+
+For completion-based AI suggestions, **view them with skepticism**.  In my
+experience, completions from e.g. GitHub CoPilot work OK when replicating a pattern
+in the file you are editing, but suggestions in a freshly-opened file tend to be
+entirely imaginary or Rails-based.  Beware.

data/brutrb.com/components.md

@@ -136,7 +136,7 @@ To use it without having to instantiate it, call `global_component` with the com
 class HomePage < AppPage
   def page_template
     header do
-      render global_component(FlashMessage)
+      global_component(FlashMessage) # note: render not required
     end
   end
 end

data/brutrb.com/dev-environment.md

@@ -137,16 +137,17 @@ that the versions of these command line apps provided when you set up your app a
 While you are free to set up mise or rbenv or whatever to run all this on your computer, this way of
 working is currently not supported nor encouraged.  For now, Brut will focus on the Docker-based approach.
 
-You are encouraged to understand how it works, especially because the Docker skills you learn in doing so
-will help with production deployment and operations.
+The primary reason is that it's a tightly controlled environment that is almost
+entirely scriptable, but does not require devs to abandon their preffered editor.
+Environment manager-based approaches tend to be more fussy and require documentation
+to ensure they are set up.
 
-Beyond this, we recommend that you keep a few things in mind with respect to automation:
+Keep in mind a few things when adding your own automation:
 
 * The *Foundational Core* is bootstrapped in a degenerate environment without reliable tools beyond Bash.
 This is why it's almost entirely written in Bash, since it's available everywhere and relatively stable.
 * The *Workspace* **can and should** rely on the languages and third party modules that are part of your
-app. Just keep in mind that `bin/setup` can only rely on programming language runtimes and not any
-particular Ruby gem having been installed.
+app. The only exception is `bin/setup`, since it installs third party modules.  As such, it should work entirely based on Ruby and its standard library.
 
 ## Technical Notes
 

data/brutrb.com/doc-conventions.md

@@ -6,7 +6,7 @@ Brut attempts to use existing terminology where possible, particularly where tha
 
 When speaking about Ruby, we prefer the term *initializer* over constructor, *parameters* over arguments, and *methods* over messages.  We also prefer *tests* over specs, however test files *are* located in `specs/` and named `*.spec.rb` to be consistent with RSpec's nomenclature.  We prefer *end-to-end* or *e2e* tests instead of browser tests or request specs. 
 
-Further, Brut doesn't render HTML, it *generates* it.  The browser renders the HTML for the website's visitor.
+Further, Brut doesn't render HTML, it *generates* it.  The browser renders the HTML for the website's visitor. One exception is Phlex, which uses the term *render* to mean "generate HTML to an internal buffer that will be delivered to the client later".  Thus, you will need to call Phlex's `render` method from time to time, even though it is not rendering HTML but helping to generate it.
 
 Lastly, the documentation tries to talk about the person accessing a website as a "vistor" not a "user". Though the "user" nomenclature is near-ossified in software development, we feel "visitor" is more apt.
 

data/brutrb.com/forms.md

@@ -87,7 +87,7 @@ class LoginPage < AppPage
 end
 ```
 
-Brut can generate the HTML for the needed inputs via `Brut::FrontEnd::Components::Inputs::TextField.for_form_input`, which is a very long name.  Hold that thought for now. This method will generate an `<input>` element for you, based on how you've set up the field in your form class. The HTML element will have a value set based on the form, if there is a value.
+Brut can generate the HTML for the needed inputs via `Brut::FrontEnd::Components::Inputs::TextField`, which is a very long class name.  Hold that thought for now. This method will generate an `<input>` element for you, based on how you've set up the field in your form class. The HTML element will have a value set based on the form, if there is a value.
 
 ```ruby {11,12}
 # app/src/front_end/pages/login_page.rb
@@ -100,8 +100,8 @@ class LoginPage < AppPage
     form_tag(method: :post,
              action: LoginHandler.routing) do
       # We promise you don't have to type this every time!
-      Brut::FrontEnd::Components::Inputs::TextField.for_form_input(form: @form, input_name: :email)
-      Brut::FrontEnd::Components::Inputs::TextField.for_form_input(form: @form, input_name: :password)
+      Brut::FrontEnd::Components::Inputs::TextField.new(form: @form, input_name: :email)
+      Brut::FrontEnd::Components::Inputs::TextField.new(form: @form, input_name: :password)
       button { "Login" }
     end
   end
@@ -134,7 +134,7 @@ class LoginPage < AppPage
 end
 ```
 
-This allows you to call `Inputs::TextField.for_form_input`:
+This allows you to call `Inputs::TextField` like a method:
 
 ```ruby {12,13}
 # app/src/front_end/pages/login_page.rb
@@ -148,8 +148,8 @@ class LoginPage < AppPage
   def page_template
     form_tag(method: :post,
              action: LoginHandler.routing) do
-      Inputs::TextField.for_form_input(form: @form, input_name: :email)
-      Inputs::TextField.for_form_input(form: @form, input_name: :password)
+      Inputs::TextField(form: @form, input_name: :email)
+      Inputs::TextField(form: @form, input_name: :password)
       button { "Login" }
     end
   end
@@ -217,7 +217,7 @@ with that email and password. Let's assume the existence of the class `Authorize
 If that returns `nil`, we want to re-render the `LoginPage`, exposing some sort of constraint violation message
 so it can be rendered. We also want the form fields to be pre-filled with the values the visitor provided.
 
-`for_form_input` can handle this, so we need to pass our form object into `LoginPage` instead of allowing `LoginPage` to create an empty one.  We can do that by adding a `form:` keyword argument that defaults to `nil`:
+`Brut::FrontEnd::Components` can handle this, so we need to pass our form object into `LoginPage` instead of allowing `LoginPage` to create an empty one.  We can do that by adding a `form:` keyword argument that defaults to `nil`:
 
 ```ruby {3,4}
 # app/src/front_end/pages/login_page.rb
@@ -229,8 +229,8 @@ class LoginPage < AppPage
   def page_template
     form_tag(method: :post,
              action: LoginHandler.routing) do
-      Inputs::TextField.for_form_input(form: @form, input_name: :email)
-      Inputs::TextField.for_form_input(form: @form, input_name: :password)
+      Inputs::TextField(form: @form, input_name: :email)
+      Inputs::TextField(form: @form, input_name: :password)
       button { "Login" }
     end
   end
@@ -267,12 +267,11 @@ class LoginHandler < AppHandler
 end
 ```
 
-When `LoginPage` generates HTML, different HTML is generated, since the form being passed to
-`for_form_input` contains constraint violations.
+When `LoginPage` generates HTML, different HTML is generated, since the form being passed to the components contains constraint violations.
 
 #### Showing Constraint Violations in HTML
 
-When `Inputs::TextField.for_form_input` is called with an existing form that has constraint violations, different HTML is generated.  This is what would be produced by our existing `LoginPage` (again, formatted her for clarity):
+When `Brut::FrontEnd::Components::Inputs::TextField` is created with an existing form that has constraint violations, different HTML is generated.  This is what would be produced by our existing `LoginPage` (again, formatted her for clarity):
 
 ```html {3}
 <form method="post" action="/login">
@@ -335,10 +334,10 @@ def page_template
   form_tag(method: :post,
            action: LoginHandler.routing) do
 
-    Inputs::TextField.for_form_input(form: @form, input_name: :email)
+    Inputs::TextField(form: @form, input_name: :email)
     ConstraintViolations(form: @form, input_name: :email)
 
-    Inputs::TextField.for_form_input(form: @form, input_name: :password)
+    Inputs::TextField(form: @form, input_name: :password)
     ConstraintViolations(form: @form, input_name: :password)
 
     button { "Login" }
@@ -419,10 +418,10 @@ def page_template
     form_tag(method: :post,
              action: LoginHandler.routing) do
 
-      Inputs::TextField.for_form_input(form: @form, input_name: :email)
+      Inputs::TextField(form: @form, input_name: :email)
       ConstraintViolations(form: @form, input_name: :email)
 
-      Inputs::TextField.for_form_input(form: @form, input_name: :password)
+      Inputs::TextField(form: @form, input_name: :password)
       ConstraintViolations(form: @form, input_name: :password)
 
       button { "Login" }
@@ -564,7 +563,7 @@ class LoginForm < AppForm
 end
 ```
 
-Checkboxes can be rendered by `Inputs::TextField.for_form_input`, and their `value` attribute would always be the string `"true"`. If the form's value for the input is the string `"true"`, the checkbox would have the `checked` attribute:
+Checkboxes can be rendered by a `Brut::FrontEnd::Components::Inputs::TextField`, and their `value` attribute would always be the string `"true"`. If the form's value for the input is the string `"true"`, the checkbox would have the `checked` attribute:
 
 ```html
 <!-- Form.new(params: { remember: "true" }) -->
@@ -578,8 +577,7 @@ Radio buttons are implemented in HTML by `<input type="radio">`, with an expecta
 having the same value for the `name` attribute, but different values for the `value` attributes, one of which may
 be `checked`.
 
-Brut implements this via `Brut::FrontEnd::Components::Inputs::RadioButton`, which has the class method
-`for_form_input`.  To create radio buttons in a form, use `radio_button_group`:
+Brut implements this via `Brut::FrontEnd::Components::Inputs::RadioButton`, whose initializer behaves like the other form input components. To create radio buttons in a form, use `radio_button_group`:
 
 ```ruby {5}
 # app/src/front_end/forms/login_form.rb
@@ -598,7 +596,7 @@ def view_template
     [ :never, :one_week, :one_month ].each do |remember|
       label do
         render(
-          Inputs::RadioButton.for_form_input(
+          Inputs::RadioButton(
             form:,
             input_name: :remember,
             value: remember
@@ -643,8 +641,7 @@ class LoginForm < AppForm
 end
 ```
 
-Creating the HTML can be done with `Brut::FrontEnd::Components::Inputs::Select`. It's `for_form_input` is more complex, since it provides a way to show visitor-friendly values instead of the innate `value` for each option,
-  as well as to allow for a "blank" entry.
+Creating the HTML can be done with `Brut::FrontEnd::Components::Inputs::Select`. It's initializer is more complex, since it provides a way to show visitor-friendly values instead of the innate `value` for each option, as well as to allow for a "blank" entry.
 
 Let's suppose we have a class named `LoginRememberOption`. It's a simple wrapper around a value we might store in the database and use to lookup an I18n key.
 
@@ -677,7 +674,7 @@ To show these options in a `<select>`, we might do this:
 def view_template
   form do
     render(
-      Inputs::Select.for_form_input(
+      Inputs::Select(
         form:,
         input_name: :remember,
         options: LoginRememberOption.all,
@@ -718,8 +715,7 @@ end
 
 In this case, we need `required: false` or every single field we generate will be required.
 
-To generate the HTML, use the optional `index:` parameter to `for_form_input` as well as for
-`ConstraintViolations`:
+To generate the HTML, use the optional `index:` parameter to the initializer as well as for `ConstraintViolations`:
 
 ```ruby {11,16}
 # Inside e.g. app/src/front_end/pages/create_bulk_widget_page.rb
@@ -729,7 +725,7 @@ def page_template
              action: BulkWidgetForm.routing) do
 
       10.times do |i|
-        Inputs::TextField.for_form_input(
+        Inputs::TextField(
           form: @form,
           input_name: :name,
           index: i

data/brutrb.com/getting-started.md

@@ -1,66 +1,137 @@
 # Getting Started
 
-To make a new app with Brut, you'll need to clone a template app, initialize it, then set up your dev environment.
+Brut is developed alongside a separate gem called `mkbrut`, which allows you to
+create a new Brut app. It will set up your dev environment as well.
 
-## Clone the App Template
+## Get `mkbrut`
 
-To get started, clone the Brut app template:
+The simplest way to use `mkbrut` is to use an existing [Docker image](https://hub.docker.com/repository/docker/thirdtank/mkbrut/general).  You don't have to install or configure Ruby:
 
 ```
-> git clone https://github.com/thirdtank/brut-app-template your-app-name
+docker run \
+       -v "$PWD":"$PWD" \
+       -w "$PWD" \
+       -it \
+       thirdtank/mkbrut \
+       mkbrut my-new-app
+```
+
+If you already have Ruby 3.4 installed, you can install `mkbrut` directly:
+
+```
+> gem install mkbrut
+> mkbrut my-new-app
 ```
 
 ## Init Your App
 
-The template includes `init`, which will ask you a few questions to get everything set up.
+A Brut app just needs a name, which will be used to derive a few more useful values.
+For now:
 
+::: code-group
+
+``` [Docker-based]
+docker run \
+       -v "$PWD":"$PWD" \
+       -w "$PWD" \
+       -it \
+       thirdtank/mkbrut \
+       mkbrut my-new-app
 ```
-> cd your-app-name
-> ./init
+
+``` [RubyGems-based]
+mkbrut my-new-app
 ```
 
-You'll need to provide four pieces of info:
+:::
+
+This will create your new app, along with some demo routes, components, handlers, and tests. If this is your first time using Brut, we recommend you examine these demo components.
+
+To create your app without the demo components:
 
-* Your app's name, suitable has a hostname or identifier
-* A prefix for your app's externalizable ids
-* A prefix for your app's custom elements
-* An organization name, needed for deployment
+::: code-group
+
+``` [Docker-based]
+docker run \
+       -v "$PWD":"$PWD" \
+       -w "$PWD" \
+       -it \
+       thirdtank/mkbrut \
+       mkbrut my-new-app --no-demo
+```
+
+``` [RubyGems-based]
+mkbrut my-new-app --no-demo
+```
 
-::: tip
-Choose your app's name wisely, however everything else can be easily changed later, so don't stress!
 :::
 
-## Set Up Your Dev Environment
+## Start Your Dev Environment
 
-Brut includes a dev environment based on Docker.
+Brut includes a dev environment based on Docker.  It uses Docker compose to run a
+Docker container where your app will run, a Docker container for Postgres, and a
+Docker container for local observability via OpenTelemetry.
 
 1. [Install Docker](https://docs.docker.com/get-started/get-docker/)
-2. Build Your images
+2. Build the image used to create you app's container:
 
    ```
    > dx/build
    ```
-3. Start up the environment
+3. Start up all the containers:
 
    ```
    > dx/start
    ```
-4. Install gems and modules for your app. In another terminal:
+4. Now, "log in" to the container where your app and its tests will run:
+
+   ```
+   > dx/exec login
+   ```
+
+5. Set everything up:
 
    ```
-   > dx/exec bin/setup
+   inside-container> bin/setup
    ```
 
-Now, you're ready to go
+Now, you're ready to go.  See [Dev Environemnt](/dev-environment) for details on how
+this all works.
 
 ## Run the App
 
 ```
-> dx/exec bin/dev
+inside-container> bin/dev
 ```
 
 You can now visit your app at `localhost:6502`
 
+You can make changes and see them when you reload.  Open up `app/src/front_end/pages/home_page.rb` *in your editor running on your computer* and change the `h1` to look like so:
+
+```ruby {6}
+class HomePage < AppPage
+  def page_template
+    div(class: "flex flex-column items-center justify-center h-80vh") do
+      img(src: "/static/images/icon.png", class: "h-50")
+      h1(class: "ff-sans ma-0 lh-title f-5") do
+        "Welcome to My New App!"
+      end
+
+      # ...
+```
+
+When you reload your browser, you'll see your change
+
+## Run the Tests
+
+There are a few tests you can run, as well as some checks that you aren't using
+RubyGems with security vulnerabilities.  Run it all now with `bin/ci`:
+
+```
+inside-container> bin/dev
+```
+
 ## Now Build The Rest of Your App 🦉
 
-You can [follow the tutorial](/tutorial), check out the [conceptual overview](/overview), or dive straight into the API docs.
+You can [follow the tutorial](/tutorial), check out the [conceptual overview](/overview), or dive straight into the API docs.  You might also want to check out the docs for [LSP Support](/lsp).
+

data/brutrb.com/instrumentation.md

@@ -66,6 +66,17 @@ Here is a non-exhaustive list of what Brut automatically instruments:
 * Ignored parameters on all form submissions
 * How long reloading takes in development
 * CSP reporting results
+* SQL Statements
+
+> [!WARNING]
+> `Sequel::Extensions::BrutInstrumentation` sets up telemetry for
+> Sequel, and it does it in a relatively simplistic way.  The result
+> is that *all* SQL statements are part of the telemetry, including
+> the actual values inserted or used in `WHERE` clauses.
+> While you should not be putting sensitive data into your database,
+> be warned that this is happening. There are plans to improve this
+> to be more flexible and reduce the Schance of sensitive data
+> being sent in traces.
 
 ### Adding Your Own Instrumentation
 
@@ -175,6 +186,7 @@ specific issues.
 
 _Last Updated June 12, 2025_
 
+
 Brut does not have plans to support non-OTel instrumentation, nor does it have plans to provide hooks to
 use proprietary formats.  This could change of course.
 

data/brutrb.com/layouts.md

@@ -0,0 +1,130 @@
+# Layouts
+
+Brut supports *layouts*, which are a way to centralizing common HTML amongst many
+different pages.  Conceptually, they are the same as a Rails layout.  Technically, they are a Phlex component designed to render a page from a `yield` block.
+
+## Overview
+
+Your app should include `app/src/front_end/layouts/default_layout.rb`. The name
+"default" is special, in that all pages will use this layout by default.
+
+Since a layout is a Phlex component, its HTML is generated from `view_template`, and
+it is expected to have exactly one `yield`, where the page's content will be
+inserted.
+
+```ruby {33}
+class DefaultLayout < Brut::FrontEnd::Layout
+  include Brut::FrontEnd::Components
+
+  def initialize(page_name:)
+    @page_name = page_name
+  end
+
+  def view_template
+    doctype
+    html(lang: "en") do
+      head do
+        meta(charset: "utf-8")
+        meta(content: "width=device-width,initial-scale=1", name:"viewport")
+        meta(content: "website", property:"og:type")
+        link(rel: "manifest",  href: "/static/manifest.json")
+        link(rel: "preload", as: "style", href: asset_path("/css/styles.css"))
+        link(rel: "stylesheet",           href: asset_path("/css/styles.css"))
+        script(defer: true, src: asset_path("/js/app.js"))
+        title { app_name }
+        PageIdentifier(@page_name)
+        I18nTranslations("cv.fe")
+        I18nTranslations("cv.this_field")
+        Traceparent()
+        render(
+          Brut::FrontEnd::RequestContext.inject(
+            Brut::FrontEnd::Components::LocaleDetection
+          )
+        )
+      end
+      body do
+        brut_tracing url: "/__brut/instrumentation", show_warnings: true
+        main class: @page_name do
+          yield
+        end
+      end
+    end
+  end
+end
+```
+
+### Maintaining Layouts
+
+You are free to manage this how you like, however a few components inside the
+`<head>` and `<body>` that are important to keep:
+
+* `Brut::FrontEnd::Components::PageIdentifier` includes a `<meta>` tag with the page's name in it, which is handy for managing your end-to-end tests.
+* `Brut::FrontEnd::Components::I18nTranslations` includes translatsion for common client-side constraint violations.  See [Forms](/forms), [I18n](/i18n), and [JavaScript](/javascript) for more details on how this is used.
+* `Brut::FrontEnd::Components::Traceparent` ensures that the OpenTelemetry *traceparent* is available so when client-side telemetry is reported back to the server, it can be connected to the request that initiated it.
+* The `<brut-tracing>` element collects the client-side telemetry and sends it back
+to the server.
+
+### Creating Alternate Layouts
+
+The way each page knows to use `DefaultLayout` is due to the `layout` method of
+`Brut::FrontEnd::Page`, which returns `"default"`.  The return value of `layout` is
+used to figure out the name of the layout class.
+
+You can set up your own by overriding `layout`:
+
+```ruby
+class MyOtherPage < AppPage
+  def layout = "other_design"
+
+  # ...
+
+end
+```
+
+Brut will expect the class `OtherDesignLayout` to exist and provide HTML.  Based on
+Zeitwerk's conventions, that class should be in
+`app/src/front_end/layouts/other_design_layout.rb`.
+
+### No Layout
+
+If you don't want a layout, you are encouraged to creat a blank layout, for example:
+
+```ruby
+class BlankLayout < Brut::FrontEnd::Layout
+  def view_template
+    yield
+  end
+end
+
+# use like so:
+
+def layout = "blank"
+```
+
+## Testing
+
+You generally don't test a layout, aside from end-to-end tests.  If your layout
+needs complex logic, you are encouraged to extract that to a
+[component](/components) and test that instead.
+
+## Recommended Practices
+
+Keep your layouts as simple as you can.
+
+
+
+## Technical Notes
+
+> [!IMPORTANT]
+> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
+> internals, the source code is always more correct.
+
+_Last Updated July 1, 2025_
+
+Layouts work due to the implementation of the method `view_template` in `Brut::FrontEnd::Page`. This is why a page class must provide `page_template` instead.
+
+While you could override `view_template` in your page to provide a "blank layout",
+this is discouraged, as the use of `view_template` should be considered a
+private implementation detail.
+
+

data/brutrb.com/lsp.md

@@ -0,0 +1,23 @@
+# Language Server Protocol (LSP) Support
+
+Because Brut development happens inside Docker, but your editor likely runs on your
+computer, getting LSP servers running takes a few more steps.
+
+## Overview
+
+When you created your app with `mkbrut`, the following LSP-related modules are set
+up and/or installed:
+
+* Shopify's Ruby LSP server (installed from `bin/setup`)
+* Microsoft's TypeScript/JavaScript and CSS LSP serfvers (specified in `package.json`, installed when `npm install` runs from `bin/setup`)
+
+In order to use them from your computer a few configurations are needed, some of
+which Brut has done, and some you will need to do.
+
+| Configuration | Description | Brut Handled? |
+|---|---|---|
+| Paths inside Docker Must Match Your Computer | When an LSP server communicates about a file, it does so with a path. That means that paths inside the Docker container must be the same as those on your computer.  Brut achievecs this by using `${CWD}` inside `docker-compose.dx.yml` | ✅ |
+| Third party libraries must *also* be installed in a path that is the same in both places | When jumping to a definition, the LSP server will again use paths, which must match.  Because Node modules are installed local to your app, they already work.  Ruby Gems, however, are configured to be installed in `local-gems` in your app.  Brut should've added this to `.gitignore` and setup everything inside Docker to use it. | ✅ |
+| Your editor must use `dx/exec` to execute LSP commands | Your editor will need to know that the LSP servers are running inside Docker.  If your editor allows configuring the commands used to do this, you must prefix them with `dx/exec bashc -lc`. See [my blog post](https://naildrivin5.com/blog/2025/06/12/neovim-and-lsp-servers-working-with-docker-based-development.html) for details. | ❌ |
+| Other languages or plugins to existing LSP servers | I haven't used these, so no idea how well they work. | ❌ |
+