brut 0.0.20 → 0.0.22

data/brutrb.com/security.md

@@ -0,0 +1,105 @@
+# Security
+
+As a new framework, Brut has not been battle-tested against potential securitiy exploits.  That said, Brut
+does configure several features to help manage security issues.
+
+## Overview
+
+Web application security is a large topic.  Brut provides a few features out of the box to manage security
+of your app:
+
+* Encrypted sessions
+* Cross-Site Request Forgery (CSRF) protection
+* Content Security Policy headers and tools
+* `bundle audit`
+
+### Encrypted Sessions
+
+Brut uses the `Rack::Session::Cookie` middleware to manage cookies.  They are encrypted with the value of
+the environment variable `SESSION_SECRET`.  This prevents both the website visitor and other websites from
+examining the contents of the cookie.
+
+This means that if Brut places data in there, it can rely on it being safe when fetched later.
+
+Cookie behavior and configuration is currently not configurable.
+
+### CSRF Protection
+
+A [cross-site request forgery](https://owasp.org/www-community/attacks/csrf) happens when a malicious site submits information from their site to a Brut-powered site, assuming it will allow and respect your credentials, potentially initiating an action on the Brut-powered site that you did not intend.
+
+The common way to mitigate this is to require a CSRF token to be included with each form submission. This
+value is generated by the server and included int he user's secure session.  If the form submission's CSRF
+token matches, the request is assumed to be valid.
+
+Brut configures [Rack::Protection::AuthenticityToken](https://sinatrarb.com/rack-protection/) as a
+middleware. Its configuration requires that *all* form submissions include a valid CSRF token, with a few
+exceptions noted in the [Technical Notes](#technical-notes) section below.
+
+To include a valid CSRF token in your [form](/forms), use `Brut::FrontEnd::Components::FormTag` to
+generate your `<form>`.  That's it.
+
+Brut's approach to Ajax requests is to model them as form submissions, so by creating a form using
+`FormTag` and using its [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) to submit
+that form with e.g. `fetch`, the CSRF token will be supplied.
+
+> [!NOTE]
+> AJax and CSRF is currently somewhat immature in Brut, so there may be areas where things
+> don't work as you'd expect.
+
+### Content Security Policy headers and tools
+
+[Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) is a way for
+a website to tell the browser what CSS and JavaScript is allowed to execute on the page.  Most web
+frameworks default to a lax or no policy, which makes applying one later difficult.
+
+Brut takes the opposite approach.  By default, Brut configures `Brut::FrontEnd::RouteHooks::CSPNoInlineStylesOrScripts` as an after route hook. This sets the content security poilcy header to disallow all inline stylings (the `style=` attribute) and all inline script tags (e.g. `onclick=`).  In development, inline styles are allowed, since they are convienient when prototyping.
+
+Brut also configures CSP reporting, which is sent into the [instrumentation](/instrumentation) system.
+
+You can control this behavior by changing the `csp_class` and/or `csp_reporting_class` using
+`Brut.container.override` in your `App`.  You can either create your own route hook and use that, or set
+either to `nil` to disable CSP entirely.
+
+### `bundle audit`
+
+The `bin/ci` script provided when you created your Burt app includes  a call to `bundle exec bundle audit
+check --update`, which will audit your RubyGems for versions that have known vulnerabilities.  If any are
+found, `bin/ci` exits nonzero, thus failing your build.
+
+## Testing
+
+In general, you don't want to test any of this unless you've set up something custom or complex. Testing
+security is done more effectively by a third party evaluating your app as a so-called "black box" or
+"opaque box" where its probed for issues without knowing how the app is implemented.
+
+## Recommended Practices
+
+* Do not disable CSRF protection.
+* Do not disable your content security policy.  Use Brut's built-in and design your app to not require inline styles or scripts.  It's much easier to not do this in the first place than to try to unwind it later.
+* Do not ship your app if `bundle audit` finds vulnerabilities.
+
+## 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 June 13, 2025_
+
+### CSRF Protection
+
+CSRF protection is not required for *Brut-owned paths*, as defined by 
+`Brut::FrontEnd::Middlewares::AnnotateBrutOwnedPaths`.  The reason for this is that these paths
+semantically should not be HTTP GETs, but are also not form submissions.  They are currently used for
+locale detection and instrumentation, which we believe are OK to allow without CSRF protection.
+
+This may change in the future.
+
+### Encrypted Sessions
+
+Session cookies are set to expire after 1 year and use the value `Lax` for
+[`SameSite`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies#controlling_third-party_cookies_with_samesite). "Lax" allows other sites to submit the Brut-powered site's cookies, but only if the user navigates to the site.  They are not sent if another site submits an Ajax request.  We feel this is the right tradeoff betweeen usability and security.
+
+### Content Security Policy headers and tools
+
+### `bundle audit`

data/brutrb.com/seed-data.md

@@ -0,0 +1,63 @@
+# See Data for Development
+
+In Brut, *seed data* is data you set up for the purposes of doing local development.  It is *not* for managing
+production data and is not used for tests.
+
+## Overview
+
+Seed data lives in `app/src/back_end/data_models/seed`.  You can create as many files in here as you like. Each
+should contain a class that extends `Brut::BackEnd::SeedData` and implements `seed!`.  By doing this, the class
+is regsitered with Brut and when you run `bin/db seed` all the classes are created and `seed!` is called.
+
+FactoryBot will be set up for you, so you can call `FactoryBot.create` to create the data.
+
+For example, here is how we might create two accounts, one deactivated, in the same organization:
+
+```ruby
+# app/src/back_end/data_models/seed/all_seed_data.rb
+class AllSeedData < Brut::BackEnd::SeedData
+  include FactoryBot::Syntax::Methods
+
+  def seed!
+    organization     = create(:organization)
+    active_account   = create(:account,
+                              organization:,
+                              email: "pat@example.com")
+    inactive_account = create(:account, :inactive,
+                              organization:,
+                              email: "chris@example.com")
+  end
+end
+```
+
+You can store other data here, such as a CSV, if you want to load data organized in another way.  Seed data will
+only ever be loaded in development, so you can organize it however you like.
+
+## Testing
+
+You do not need to test your seed data. Presumably, you will be using your app in development, and this will be
+sufficient to determine if your seed data is fit for purpose.
+
+## Recommended Practices
+
+* Use FactoryBot as this is consistent with your tests
+* Use literal values for anything relevant to local development. In the example above, the two email addresses are important, presumably because you'd be using those to login. The organization name, however, is irrelevant, so we allow Faker to come up with a name.
+* Use local variables as documentation. In the example above, there's no need to set `active_account` or
+`inactive_account`, but doing so makes it clear what those objects are for.
+* Ensure all seed data classes are independent from one another, as the order of their exeuction cannot be guaranteed.
+
+## 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 May 8, 2025_
+
+All seed data is loaded in one transaction.  This means that if any class' seed data fails, no data will be
+written.
+
+Seed data also is not assumed to be idempotent. If you run it twice, you will likely get an error.  Because 
+[your dev database is ephemeral](/database-schema#ephemeral-dev-database), you can always recreate your dev
+database via `bin/db rebuild && bin/db seed`.
+

data/brutrb.com/space-time-continuum.md

@@ -0,0 +1,85 @@
+# Space/Time Continuum - Making Sense of Times and Time Zones
+
+Time zones are the worst.  But they are fact of life.  This means that answer a question like "what is the date?"
+or "is it Monday?" are not that easy to answer.
+
+## Timezones Outside of Web Requests
+
+For back-end code, storing dates to the database, etc., Brut falls back to the normal Ruby app mechanisms for
+determining the "current time zone", which is to say, it super duper depends.  The system, the database, and Ruby
+can all configure a time zone that is in effect when dates are parsed or stored.
+
+The main way to deal with this is in how [Brut manages your database schema](/database-schema), which is to say that it
+defaults to using `timestamp with time zone` and encourages you to do the same.  What this data type means is if
+your system is set to UTC, stores a timestamp, then restarts with the time zone set to America/Los\_Angeles, that timestamp will be read back without ambiguity.  If you use `timestamp without time zone` (which is typically `timestamp`), this will not be the case.
+
+All this is to say, if you use `timestamp with time zone`, you should generally not have to worry about this.
+Just be careful when serializing these values.
+
+## Timezones for User Sessions
+
+Depending on what your app does, you may need to show dates or times to the site visitor.  And you'll probably
+want to show those in their time zone.  Brut can help with this.
+
+As mentioned in [Flash and Session](/flash-and-session), the session provides access to timezone information.
+Brut also provides a `Clock` class that represents the current date and time in the current session's time zone.
+Here is how that works.
+
+There are two ways to determine a visitor's time zone: you can ask them, or you can ask their browser.
+
+### Getting Timezone from the Browser
+
+The default `<head>` section of your app's `DefaultLayout` will include the Brut-provided custom element
+`<brut-locale-detection>`. This HTML custom element is configured to communicate the browser's locale and
+timezone back to Brut at the URL `/__brut/local_detection`, which is handled by
+`Brut::FrontEnd::Handlers::LocaleDetectionHandler`.
+
+The custom element uses `Intl.DateTimeFormat().resolvedOptions().timeZone` to determine the browser's timezone
+and sends this back to Brut. Whatever this value is, it will be set in the session as `timezone_from_browser`.
+When you ask the session for the `timezone_from_browser`, Brut will attempt to locate a `TZInfo::Timezone` with
+that name. If it finds one, that is returned.  Otherwise, `nil` is returned.
+
+This is only part of how Brut determines the session's time zone.
+
+### Getting the Session's Timezone
+
+If you ask the session instead for `timezone`, and it has not been set explicitly, 
+Brut will first check `timezone_from_browser`. If it's not `nil`, it's returned. If it *is* `nil`, the timezone
+whose name is in `ENV['TZ']` is returned, unless that is missing or invalid, in which case UTC is returned.
+
+If you have a way to ask the user what their timezone is, you can set it via `session.timezone=`. If you have
+done this, *that* value is returned instead of the above logic.
+
+Note that in all cases, the timezone that is serialized into the session is the name. This means it's technically
+possible for the name to valid when stored and invalid when read, if you have updated the `tzinfo` gem and
+something changed.
+
+Therefore, it's recommended that if you have asked the visitor their preferred time zone, you store that
+somewhere in the database, so you can detect when the value from the session has drifted.
+
+### Using the Timezone
+
+With a `TZInfo::Timezone` object, you can certainly create a Ruby `Time` object via
+`timezone.to_local(Time.new)`.  However, you don't have to do this.  By [keyword injecting](/keyword-injection)
+`clock:`, you will get an instance of `Clock`, primed with the value of `session.timezone` as its timezone.
+
+The `Clock` responds to `now` and `today`, and will return the current timestamp and current date, respectively, in the visitor's time zone.  This means that if your view code does something like `l(clock.now, format: :date)`, it will show the current time in the visitor's time zone.
+
+This, coupled with the use of `timestamp with time zone`, means these values can be safely sent to the back-end
+to be stored in the database, and conversion is not necessary.
+
+## Testing
+
+If your app makes heavy use of timezone-based timestamps or dates, you are encouraged to test this logic. `Brut::SpecSupport::ClockSupport` (included by default in page, component, and handler tests) provides helper methods to manipulate and use `Clock` instances.  You should not need to mock time or use something like Timecop.
+
+If your tests just need a clock, or a clock at a time, regardless of time zone, you can use `real_clock` or
+`clock_at(now:)` to pass into your pages, components, and handlers.  These will be set at UTC.
+
+If your tests require a particular timezone, you may use `clock_in_timezone_at(timezone_name:, now:)`. The
+timezone name is from `tzinfo`'s database. `clock_in_timezone_at` will raise an error if given an invalid
+timezone.  `now:` is a string that will be parsed as a `Time`.
+
+If you are testing something that is sensitive to time, but you do not have access to the clock, `Brut::SpecSupport::SessionSupport` provides `empty_session`, which returns a session object on which you can call `timezone=`.  Beyond this, you may need to provide hooks for setting the time, for example via a query string parameter.
+
+
+

data/brutrb.com/tutorial.md

@@ -0,0 +1,3 @@
+# Tutorial
+
+This section will walk you through creating a Brut app and should touch on most of the major features.

data/brutrb.com/unit-tests.md

@@ -0,0 +1,148 @@
+# Unit Tests
+
+Tests in Brut use RSpec and given that most of your Brut-powered
+classes are simple Ruby classes, you can test them in conventional
+ways.
+
+## Overview
+
+When you scaffold something like a page or component, Brut will
+create an empty test file in `specs/`, whose path mirrors the
+class in `app/src`.  For example, `specs/front_end/handlers/login_handler.spec.rb` will test the class defined in `app/src/front_end/handlers/login_handler.rb`.
+
+Each page of Brut's documentation includes a "Testing" section
+that outlines additional features avialable to make testing work
+more easily.  This section will talk about general features and
+behavior.
+
+### Tests run in a Database Transaction
+
+At the start of each test (`it` block in RSpec), a database
+transaction is opened.  At the end, the transaction is rolled
+back.  This means that none of the changes you make to the
+database have any effect outside the context of the test.
+
+The downside of this approach is that you cannot test anything
+that involves database transactions.  For example, if you want to
+ensure that a piece of business logic runs inside a database
+transaction, you will have to assure that another way, such as
+spying.
+
+### A Usable `RequestContext` is Created for Front End Tests
+
+Although your tests of pages, components, and handlers are
+generally isolated, it's possible to trigger codepaths where Brut
+will use [keyword injection](/keyword-injection), such as a
+global component.
+
+To make sure this doesn't fail, Brut sets up a reasonable
+`RequestContext` that will be used for any such injections.
+
+Brut will also `let` that instance, named `request_context`.  This
+means you can access it and modify it in your test as needed.  It
+will be recreated new for each test, so you are safe making
+changes to it.
+
+### `bin/test audit` and Managing Tests
+
+`bin/test audit` will fail if any file in `app/src` does not have
+a corresponding test.  This is handy when you are moving fast to
+make sure you don't forget to add test coverage.
+
+That said, sometimes classes are simple and won't benefit from a
+test, or a class' behavior may be adequately covered by another
+test.  It's helpful to record this information so it's clear that
+you've given consideration to tests and not just forgotten them.
+
+Every Brut test has
+`Brut::SpecSupport::GeneralSupport::ClassMethods` included and it
+provides three methods to help record your intent with respect to
+omitting tests. These methods should be called in a `describe` or
+`context` block.
+
+* `implementation_is_covered_by_other_tests(description)` used to
+explain where the coverage for this class is.
+
+  ```ruby
+  RSpec.describe TaxCalculator do
+    implementation_is_covered_by_other_tests "e2e tests for checkout"
+  end
+  ```
+* `implementation_is_needed(check_again_at:)` used when you want to acknowledge that a test is required, but for whatever reason you cannot provide it now.  This will create a test that fails after the date/time given to `check_again_at:`.
+
+  ```ruby
+  RSpec.describe TaxCalculator do
+    implementation_is_needed(check_again_at: "2025-06-13")
+  end
+  ```
+* `implementation_is_trivial(check_again_at: nil)` used to indicate that code is trivial and would not benefit from the carrying cost of a test. `check_again_at:` is optional and this will create a failing test after that date.  You'd set this for a class that you suspect may grow in complexity, as a way to ensure it's not forgotten.
+
+  ```ruby
+  RSpec.describe TaxCalculator do
+    implementation_is_trivial
+  end
+  ```
+## Recommended Practices
+
+A list of recommended practices for testing could fill many books.
+Instead, we'll focus on a few things that will make life easier.
+
+### Go Easy on RSpec Features
+
+Shared contexts and shared examples usually make a test suite much
+harder to understand and much worse.  You should avoid them
+entirely.
+
+`let` and `let!` also generally make things worse and should be
+avoided. It's usually better to have duplication in various `it`
+blocks than to try to parameterize the use of `let`.  This is
+doubly true when you have nested contexts.
+
+### Custom Matchers Are Useful
+
+An effective way to re-use test assertions is via custom matchers.
+Brut makes use of these, and you can easily create your own. The
+recommended way to do this is:
+
+1. Create `specs/support/matchers`
+2. Create your matcher there, named for the matcher's method. For
+   example, if your matcher is `be_active_account`, create
+   `specs/support/matchers/be_active_account.rb`.
+3. Implement your matcher per RSpec's instructions.
+4. Use `require "support/matchers/be_active_account"` to require
+   your matcher explicitly. This will make it easier to understand
+   where everything is coming from when others read your test.
+5. Check your matchers behavior with passing and failing tests and
+   for negated versions.  Ensure that `failure_message` and
+   `failure_message_when_negated` produce useful messages.
+
+### Lint Your Factories
+
+By default, your Brut app should come with a spec to verify that
+all your Factory Bot factories work:
+
+```ruby
+# specs/lint_factories.spec.rb
+require "spec_helper"
+RSpec.describe "factories" do
+  it "should be possible to create them all" do
+    FactoryBot.lint traits: true
+  end
+end
+```
+
+This implies that each factory and each trait of that factory can
+be created without providing any additional attributes.  This is
+*critical* to sustainable tests over time.  If any factory can be
+created at any time without dependencies, your tests will be easy
+to write and maintain.
+
+## 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 May 9, 2025_
+
+

data/docker-compose.dx.yml

@@ -5,12 +5,15 @@ services:
     init: true
     volumes:
       - type: bind
-        source: "./"
-        target: "/root/work"
+        source: ${PWD}
+        target: ${PWD}
         consistency: "consistent"
       - type: bind
         source: ${GIT_CONFIG}
         target: "/root/.gitconfig"
     entrypoint: /root/show-help-in-app-container-then-wait.sh
-    working_dir: /root/work
+    working_dir: ${PWD}
+    ports:
+      - "8086:8086"
+      - "8087:8087"
 

data/docs/404.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en-US" dir="ltr">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>404 | Brut RB</title>
+    <meta name="description" content="Not Found">
+    <meta name="generator" content="VitePress v1.6.3">
+    <link rel="preload stylesheet" href="/assets/style.D73IYGCX.css" as="style">
+    <link rel="preload stylesheet" href="/vp-icons.css" as="style">
+    
+    <script type="module" src="/assets/app.D_yaTITQ.js"></script>
+    <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
+    <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ai.md\":\"tZrjP9im\",\"assets.md\":\"D3wunzLx\",\"brut-js.md\":\"o2DAO2s2\",\"business-logic.md\":\"BY4hGy0m\",\"cli.md\":\"RmeA2b0i\",\"components.md\":\"eCttGlN-\",\"configuration.md\":\"BRriU0cL\",\"css.md\":\"DJgj2clw\",\"custom-element-tests.md\":\"BrYJQEl3\",\"database-access.md\":\"C7l-Vuvb\",\"database-schema.md\":\"BUjR0VS1\",\"deployment.md\":\"Dbka4OTr\",\"dev-environment.md\":\"BNc8AYiK\",\"doc-conventions.md\":\"DCfRXXi-\",\"end-to-end-tests.md\":\"yfQHC0b5\",\"flash-and-session.md\":\"BXY8RvT0\",\"forms.md\":\"CBTYQ_Cz\",\"getting-started.md\":\"Bz2s1Vjb\",\"handlers.md\":\"089DVD3v\",\"hooks.md\":\"C4-moMny\",\"i18n.md\":\"Do9i1qWl\",\"index.md\":\"B28EwVpq\",\"instrumentation.md\":\"CL6ax7nT\",\"javascript.md\":\"GWbhRS51\",\"jobs.md\":\"S-2amAYp\",\"keyword-injection.md\":\"Dt2tKREs\",\"markdown-examples.md\":\"CCFEQO44\",\"middleware.md\":\"Czz_UlJN\",\"not-released.md\":\"BBy28McC\",\"overview.md\":\"CDalkuxV\",\"pages.md\":\"BE3kfOc5\",\"routes.md\":\"BMM7peut\",\"security.md\":\"C668yXCi\",\"seed-data.md\":\"BvFZlqIk\",\"space-time-continuum.md\":\"KPUIKysQ\",\"tutorial.md\":\"BnoGjrdK\",\"unit-tests.md\":\"DUGrnLj5\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Brut RB\",\"description\":\"Documentation for the Brut.RB web framework.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"search\":{\"provider\":\"local\"},\"nav\":[{\"text\":\"Home\",\"link\":\"/\"},{\"text\":\"Getting Started\",\"link\":\"/getting-started\"},{\"text\":\"Overview\",\"link\":\"/overview\"},{\"text\":\"Brut API\",\"link\":\"/api/index.html\",\"target\":\"_self\"},{\"text\":\"BrutJS\",\"link\":\"/brut-js/api/index.html\",\"target\":\"_self\"},{\"text\":\"BrutCSS\",\"link\":\"/brut-css/index.html\",\"target\":\"_self\"}],\"outline\":[2,3],\"sidebar\":[{\"text\":\"Overview\",\"collapsed\":false,\"items\":[{\"text\":\"Getting Started\",\"link\":\"/getting-started\"},{\"text\":\"Concepts\",\"link\":\"/overview\"},{\"text\":\"Documentation Conventions\",\"link\":\"/doc-conventions\"},{\"text\":\"Tutorial\",\"link\":\"/tutorial\"},{\"text\":\"Dev Environment\",\"link\":\"/dev-environment\"},{\"text\":\"AI Declaration\",\"link\":\"/ai\"}]},{\"text\":\"Front-End\",\"collapsed\":false,\"items\":[{\"text\":\"Routes\",\"link\":\"/routes\"},{\"text\":\"Pages\",\"link\":\"/pages\"},{\"text\":\"Forms\",\"link\":\"/forms\"},{\"text\":\"Handlers and Actions\",\"link\":\"/handlers\"},{\"text\":\"Components\",\"link\":\"/components\"},{\"text\":\"Flash and Session\",\"link\":\"/flash-and-session\"},{\"text\":\"Space/Time Continuum\",\"link\":\"/space-time-continuum\"},{\"text\":\"JavaScript\",\"link\":\"/javascript\"},{\"text\":\"CSS\",\"link\":\"/css\"},{\"text\":\"Assets\",\"link\":\"/assets\"},{\"text\":\"BrutJS\",\"link\":\"/brut-js\"}]},{\"text\":\"Back-End\",\"collapsed\":false,\"items\":[{\"text\":\"Database Schema\",\"link\":\"/database-schema\"},{\"text\":\"Database Access\",\"link\":\"/database-access\"},{\"text\":\"Seed Data\",\"link\":\"/seed-data\"},{\"text\":\"Jobs\",\"link\":\"/jobs\"},{\"text\":\"Business Logic\",\"link\":\"/business-logic\"}]},{\"text\":\"Framework\",\"collapsed\":false,\"items\":[{\"text\":\"Configuration\",\"link\":\"/configuration\"},{\"text\":\"Keyword Injection\",\"link\":\"/keyword-injection\"},{\"text\":\"I18n\",\"link\":\"/i18n\"},{\"text\":\"CLI / Tasks\",\"link\":\"/cli\"},{\"text\":\"Deployment\",\"link\":\"/deployment\"}]},{\"text\":\"Testing\",\"collapsed\":false,\"items\":[{\"text\":\"Unit Tests\",\"link\":\"/unit-tests\"},{\"text\":\"End-to-End Tests\",\"link\":\"/end-to-end-tests\"},{\"text\":\"Testing Custom Elements\",\"link\":\"/custom-element-tests\"}]},{\"text\":\"Advanced Topics\",\"collapsed\":false,\"items\":[{\"text\":\"Route Hooks\",\"link\":\"/hooks\"},{\"text\":\"Middleware\",\"link\":\"/middleware\"},{\"text\":\"Instrumentation\",\"link\":\"/instrumentation\"},{\"text\":\"Security\",\"link\":\"/security\"}]}],\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/thirdtank/brut\"}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    
+  </body>
+</html>

data/docs/CNAME

@@ -0,0 +1 @@
+brutrb.com

data/docs/ai.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en-US" dir="ltr">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>AI Declaration and Notes | Brut RB</title>
+    <meta name="description" content="Documentation for the Brut.RB web framework.">
+    <meta name="generator" content="VitePress v1.6.3">
+    <link rel="preload stylesheet" href="/assets/style.D73IYGCX.css" as="style">
+    <link rel="preload stylesheet" href="/vp-icons.css" as="style">
+    
+    <script type="module" src="/assets/app.D_yaTITQ.js"></script>
+    <link rel="modulepreload" href="/assets/chunks/theme.CfGFVRvE.js">
+    <link rel="modulepreload" href="/assets/chunks/framework.1L-BeKqY.js">
+    <link rel="modulepreload" href="/assets/ai.md.tZrjP9im.lean.js">
+    <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
+    <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
+  </head>
+  <body>
+    <div id="app"><div class="Layout" data-v-d8b57b2d><!--[--><!--]--><!--[--><span tabindex="-1" data-v-fcbfc0e0></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-fcbfc0e0>Skip to content</a><!--]--><!----><header class="VPNav" data-v-d8b57b2d data-v-7ad780c2><div class="VPNavBar" data-v-7ad780c2 data-v-9fd4d1dd><div class="wrapper" data-v-9fd4d1dd><div class="container" data-v-9fd4d1dd><div class="title" data-v-9fd4d1dd><div class="VPNavBarTitle has-sidebar" data-v-9fd4d1dd data-v-9f43907a><a class="title" href="/" data-v-9f43907a><!--[--><!--]--><!----><span data-v-9f43907a>Brut RB</span><!--[--><!--]--></a></div></div><div class="content" data-v-9fd4d1dd><div class="content-body" data-v-9fd4d1dd><!--[--><!--]--><div class="VPNavBarSearch search" data-v-9fd4d1dd><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-9fd4d1dd data-v-afb2845e><span id="main-nav-aria-label" class="visually-hidden" data-v-afb2845e> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/" tabindex="0" data-v-afb2845e data-v-815115f5><!--[--><span data-v-815115f5>Home</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/getting-started.html" tabindex="0" data-v-afb2845e data-v-815115f5><!--[--><span data-v-815115f5>Getting Started</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/overview.html" tabindex="0" data-v-afb2845e data-v-815115f5><!--[--><span data-v-815115f5>Overview</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/api/index.html" target="_self" tabindex="0" data-v-afb2845e data-v-815115f5><!--[--><span data-v-815115f5>Brut API</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/brut-js/api/index.html" target="_self" tabindex="0" data-v-afb2845e data-v-815115f5><!--[--><span data-v-815115f5>BrutJS</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/brut-css/index.html" target="_self" tabindex="0" data-v-afb2845e data-v-815115f5><!--[--><span data-v-815115f5>BrutCSS</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-9fd4d1dd data-v-3f90c1a5><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-3f90c1a5 data-v-be9742d9 data-v-b4ccac88><span class="check" data-v-b4ccac88><span class="icon" data-v-b4ccac88><!--[--><span class="vpi-sun sun" data-v-be9742d9></span><span class="vpi-moon moon" data-v-be9742d9></span><!--]--></span></span></button></div><div class="VPSocialLinks VPNavBarSocialLinks social-links" data-v-9fd4d1dd data-v-ef6192dc data-v-e71e869c><!--[--><a class="VPSocialLink no-icon" href="https://github.com/thirdtank/brut" aria-label="github" target="_blank" rel="noopener" data-v-e71e869c data-v-60a9a2d3><span class="vpi-social-github"></span></a><!--]--></div><div class="VPFlyout VPNavBarExtra extra" data-v-9fd4d1dd data-v-f953d92f data-v-bfe7971f><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-bfe7971f><span class="vpi-more-horizontal icon" data-v-bfe7971f></span></button><div class="menu" data-v-bfe7971f><div class="VPMenu" data-v-bfe7971f data-v-20ed86d6><!----><!--[--><!--[--><!----><div class="group" data-v-f953d92f><div class="item appearance" data-v-f953d92f><p class="label" data-v-f953d92f>Appearance</p><div class="appearance-action" data-v-f953d92f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-f953d92f data-v-be9742d9 data-v-b4ccac88><span class="check" data-v-b4ccac88><span class="icon" data-v-b4ccac88><!--[--><span class="vpi-sun sun" data-v-be9742d9></span><span class="vpi-moon moon" data-v-be9742d9></span><!--]--></span></span></button></div></div></div><div class="group" data-v-f953d92f><div class="item social-links" data-v-f953d92f><div class="VPSocialLinks social-links-list" data-v-f953d92f data-v-e71e869c><!--[--><a class="VPSocialLink no-icon" href="https://github.com/thirdtank/brut" aria-label="github" target="_blank" rel="noopener" data-v-e71e869c data-v-60a9a2d3><span class="vpi-social-github"></span></a><!--]--></div></div></div><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-9fd4d1dd data-v-6bee1efd><span class="container" data-v-6bee1efd><span class="top" data-v-6bee1efd></span><span class="middle" data-v-6bee1efd></span><span class="bottom" data-v-6bee1efd></span></span></button></div></div></div></div><div class="divider" data-v-9fd4d1dd><div class="divider-line" data-v-9fd4d1dd></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-d8b57b2d data-v-2488c25a><div class="container" data-v-2488c25a><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-2488c25a><span class="vpi-align-left menu-icon" data-v-2488c25a></span><span class="menu-text" data-v-2488c25a>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-2488c25a data-v-6b867909><button data-v-6b867909>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-d8b57b2d data-v-42c4c606><div class="curtain" data-v-42c4c606></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-42c4c606><span class="visually-hidden" id="sidebar-aria-label" data-v-42c4c606> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-51288d80><section class="VPSidebarItem level-0 collapsible has-active" data-v-51288d80 data-v-0009425e><div class="item" role="button" tabindex="0" data-v-0009425e><div class="indicator" data-v-0009425e></div><h2 class="text" data-v-0009425e>Overview</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-0009425e><span class="vpi-chevron-right caret-icon" data-v-0009425e></span></div></div><div class="items" data-v-0009425e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/getting-started.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Getting Started</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/overview.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Concepts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/doc-conventions.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Documentation Conventions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/tutorial.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Tutorial</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/dev-environment.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Dev Environment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/ai.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>AI Declaration</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-51288d80><section class="VPSidebarItem level-0 collapsible" data-v-51288d80 data-v-0009425e><div class="item" role="button" tabindex="0" data-v-0009425e><div class="indicator" data-v-0009425e></div><h2 class="text" data-v-0009425e>Front-End</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-0009425e><span class="vpi-chevron-right caret-icon" data-v-0009425e></span></div></div><div class="items" data-v-0009425e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/routes.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Routes</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/pages.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Pages</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/forms.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Forms</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/handlers.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Handlers and Actions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/components.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Components</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/flash-and-session.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Flash and Session</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/space-time-continuum.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Space/Time Continuum</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/javascript.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>JavaScript</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/css.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>CSS</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/assets.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Assets</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/brut-js.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>BrutJS</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-51288d80><section class="VPSidebarItem level-0 collapsible" data-v-51288d80 data-v-0009425e><div class="item" role="button" tabindex="0" data-v-0009425e><div class="indicator" data-v-0009425e></div><h2 class="text" data-v-0009425e>Back-End</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-0009425e><span class="vpi-chevron-right caret-icon" data-v-0009425e></span></div></div><div class="items" data-v-0009425e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/database-schema.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Database Schema</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/database-access.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Database Access</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/seed-data.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Seed Data</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/jobs.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Jobs</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/business-logic.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Business Logic</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-51288d80><section class="VPSidebarItem level-0 collapsible" data-v-51288d80 data-v-0009425e><div class="item" role="button" tabindex="0" data-v-0009425e><div class="indicator" data-v-0009425e></div><h2 class="text" data-v-0009425e>Framework</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-0009425e><span class="vpi-chevron-right caret-icon" data-v-0009425e></span></div></div><div class="items" data-v-0009425e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/configuration.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Configuration</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/keyword-injection.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Keyword Injection</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/i18n.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>I18n</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/cli.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>CLI / Tasks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/deployment.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Deployment</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-51288d80><section class="VPSidebarItem level-0 collapsible" data-v-51288d80 data-v-0009425e><div class="item" role="button" tabindex="0" data-v-0009425e><div class="indicator" data-v-0009425e></div><h2 class="text" data-v-0009425e>Testing</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-0009425e><span class="vpi-chevron-right caret-icon" data-v-0009425e></span></div></div><div class="items" data-v-0009425e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/unit-tests.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Unit Tests</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/end-to-end-tests.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>End-to-End Tests</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/custom-element-tests.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Testing Custom Elements</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-51288d80><section class="VPSidebarItem level-0 collapsible" data-v-51288d80 data-v-0009425e><div class="item" role="button" tabindex="0" data-v-0009425e><div class="indicator" data-v-0009425e></div><h2 class="text" data-v-0009425e>Advanced Topics</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-0009425e><span class="vpi-chevron-right caret-icon" data-v-0009425e></span></div></div><div class="items" data-v-0009425e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/hooks.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Route Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/middleware.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Middleware</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/instrumentation.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Instrumentation</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-0009425e data-v-0009425e><div class="item" data-v-0009425e><div class="indicator" data-v-0009425e></div><a class="VPLink link link" href="/security.html" data-v-0009425e><!--[--><p class="text" data-v-0009425e>Security</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-d8b57b2d data-v-9a6c75ad><div class="VPDoc has-sidebar has-aside" data-v-9a6c75ad data-v-e6f2a212><!--[--><!--]--><div class="container" data-v-e6f2a212><div class="aside" data-v-e6f2a212><div class="aside-curtain" data-v-e6f2a212></div><div class="aside-container" data-v-e6f2a212><div class="aside-content" data-v-e6f2a212><div class="VPDocAside" data-v-e6f2a212 data-v-cb998dce><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-cb998dce data-v-f610f197><div class="content" data-v-f610f197><div class="outline-marker" data-v-f610f197></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-f610f197>On this page</div><ul class="VPDocOutlineItem root" data-v-f610f197 data-v-53c99d69><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-cb998dce></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-e6f2a212><div class="content-container" data-v-e6f2a212><!--[--><!--]--><main class="main" data-v-e6f2a212><div style="position:relative;" class="vp-doc _ai" data-v-e6f2a212><div><h1 id="ai-declaration-and-notes" tabindex="-1">AI Declaration and Notes <a class="header-anchor" href="#ai-declaration-and-notes" aria-label="Permalink to &quot;AI Declaration and Notes&quot;">​</a></h1><p>LLMs and AI tools are a current fact of life. We feel it&#39;s important to be realistic and up front about how they affect this project.</p><h2 id="levels-of-ai-use" tabindex="-1">Levels of AI Use <a class="header-anchor" href="#levels-of-ai-use" aria-label="Permalink to &quot;Levels of AI Use&quot;">​</a></h2><p>I created <a href="https://declare-ai.org/" target="_blank" rel="noreferrer">declare-ai.org</a> to allow precise documentation of how AI is used in a project. It defines four levels of AI use:</p><ol><li>No involvement at all.</li><li>Non-create assistance, such as the completions GitHub Copilot may make while you are typing.</li><li>Creative assistance, where an AI generated a large amount of code that you then modified. An example would be using a tool like Cursor to write code for your review.</li><li>Completely Produced by an AI, for example if you used Stable Diffusion to create your icon.</li></ol><h2 id="code" tabindex="-1">Code <a class="header-anchor" href="#code" aria-label="Permalink to &quot;Code&quot;">​</a></h2><p>The entirety of Brut&#39;s codebase could be grouped into three parts:</p><ul><li>The library code developers use. This is, roughly, the code in <code>lib</code>, <code>brut-js/src</code>, and <code>brut-css/src</code>.</li><li>Tests of the library code.</li><li>Tools used to manage the library code, such as what&#39;s in <code>bin/</code>, <code>brut-js/bin</code>, <code>brut-css/bin</code>, etc.</li></ul><h3 id="library-code-should-be-written-by-a-person" tabindex="-1">Library Code Should Be Written By a Person <a class="header-anchor" href="#library-code-should-be-written-by-a-person" aria-label="Permalink to &quot;Library Code Should Be Written By a Person&quot;">​</a></h3><p>We want the library code written by a person, i.e. it should have level 1 AI assistance: none. As of this writing—June 17, 2025—all library code was written by a person.</p><p>If some code is level 2—non-creative assistance—that is probably fine.</p><h3 id="tests-should-not-be-totally-written-by-ai" tabindex="-1">Tests Should Not Be Totally Written by AI <a class="header-anchor" href="#tests-should-not-be-totally-written-by-ai" aria-label="Permalink to &quot;Tests Should Not Be Totally Written by AI&quot;">​</a></h3><p>As of this writing—June 17, 2025—the library has no automated tests. The <code>adrs.cloud</code> app serves as the test suite.</p><p>That said, as tests are developed, they must never be written entirely by an AI without human review (level 4). Our preference is that all tests comply with level 1 or level 2, however we are open to creative assistance for tests as might be provided by a tool like Cursor.</p><p>In any case, the author of a test should understand it and the maintainers must be able to understand and modify all tests without the use of AI tools.</p><h3 id="management-tools-should-not-be-totally-written-by-ai" tabindex="-1">Management Tools Should Not Be Totally Written by AI <a class="header-anchor" href="#management-tools-should-not-be-totally-written-by-ai" aria-label="Permalink to &quot;Management Tools Should Not Be Totally Written by AI&quot;">​</a></h3><p>Like tests, management tools must be comprehensible by a person and the creator of the code must understand it. That said, some of the tools were created with level 3 AI assistance, and we expect these tools may continue to be created this way.</p><p>Nevertheless, this code must be reviewed and understood by a person.</p><h2 id="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-label="Permalink to &quot;Documentation&quot;">​</a></h2><p>We strive to have all documentation written by a real person. None of this documentation, or the API documentation, is produced by a machine, although spelling and grammar corrections will certainly have been suggested by automated tools.</p><p>We expect an LLM to be able to digest this documentation and source code and provide alternate analysis of how Brut works and how to use it. We hope such analysis is correct and useful, however that cannot be guaranteed, so this documentation is the second best source of truth, the source code being the best.</p><h2 id="logo" tabindex="-1">Logo <a class="header-anchor" href="#logo" aria-label="Permalink to &quot;Logo&quot;">​</a></h2><p>The logo is level 4 - ChatGPT created it. I&#39;d love to have a real person make a better one. I just needed something to get this launched. Please reach out if you want to make a better one + other assets. I&#39;m willing to pay a real person.</p><h2 id="ai-that-teachs-you-about-brut-does-not-currently-exist" tabindex="-1">AI That Teachs You About Brut Does Not Currently Exist <a class="header-anchor" href="#ai-that-teachs-you-about-brut-does-not-currently-exist" aria-label="Permalink to &quot;AI That Teachs You About Brut Does Not Currently Exist&quot;">​</a></h2><p>Due to how LLMs work, there is naturally nothing in any model about Brut. Anything an existing model tells you about Brut is <strong>100% untrustworthy</strong>. We hope to allow LLMs to consume Brut&#39;s code, documentation, and examples, so it can be an additional source of help, but currently that is not the case.</p><p><strong>Do not ask an LLM about Brut</strong> until this part of the documentation changes.</p></div></div></main><footer class="VPDocFooter" data-v-e6f2a212 data-v-1bcd8184><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-1bcd8184><span class="visually-hidden" id="doc-footer-aria-label" data-v-1bcd8184>Pager</span><div class="pager" data-v-1bcd8184><a class="VPLink link pager-link prev" href="/dev-environment.html" data-v-1bcd8184><!--[--><span class="desc" data-v-1bcd8184>Previous page</span><span class="title" data-v-1bcd8184>Dev Environment</span><!--]--></a></div><div class="pager" data-v-1bcd8184><a class="VPLink link pager-link next" href="/routes.html" data-v-1bcd8184><!--[--><span class="desc" data-v-1bcd8184>Next page</span><span class="title" data-v-1bcd8184>Routes</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ai.md\":\"tZrjP9im\",\"assets.md\":\"D3wunzLx\",\"brut-js.md\":\"o2DAO2s2\",\"business-logic.md\":\"BY4hGy0m\",\"cli.md\":\"RmeA2b0i\",\"components.md\":\"eCttGlN-\",\"configuration.md\":\"BRriU0cL\",\"css.md\":\"DJgj2clw\",\"custom-element-tests.md\":\"BrYJQEl3\",\"database-access.md\":\"C7l-Vuvb\",\"database-schema.md\":\"BUjR0VS1\",\"deployment.md\":\"Dbka4OTr\",\"dev-environment.md\":\"BNc8AYiK\",\"doc-conventions.md\":\"DCfRXXi-\",\"end-to-end-tests.md\":\"yfQHC0b5\",\"flash-and-session.md\":\"BXY8RvT0\",\"forms.md\":\"CBTYQ_Cz\",\"getting-started.md\":\"Bz2s1Vjb\",\"handlers.md\":\"089DVD3v\",\"hooks.md\":\"C4-moMny\",\"i18n.md\":\"Do9i1qWl\",\"index.md\":\"B28EwVpq\",\"instrumentation.md\":\"CL6ax7nT\",\"javascript.md\":\"GWbhRS51\",\"jobs.md\":\"S-2amAYp\",\"keyword-injection.md\":\"Dt2tKREs\",\"markdown-examples.md\":\"CCFEQO44\",\"middleware.md\":\"Czz_UlJN\",\"not-released.md\":\"BBy28McC\",\"overview.md\":\"CDalkuxV\",\"pages.md\":\"BE3kfOc5\",\"routes.md\":\"BMM7peut\",\"security.md\":\"C668yXCi\",\"seed-data.md\":\"BvFZlqIk\",\"space-time-continuum.md\":\"KPUIKysQ\",\"tutorial.md\":\"BnoGjrdK\",\"unit-tests.md\":\"DUGrnLj5\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Brut RB\",\"description\":\"Documentation for the Brut.RB web framework.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"search\":{\"provider\":\"local\"},\"nav\":[{\"text\":\"Home\",\"link\":\"/\"},{\"text\":\"Getting Started\",\"link\":\"/getting-started\"},{\"text\":\"Overview\",\"link\":\"/overview\"},{\"text\":\"Brut API\",\"link\":\"/api/index.html\",\"target\":\"_self\"},{\"text\":\"BrutJS\",\"link\":\"/brut-js/api/index.html\",\"target\":\"_self\"},{\"text\":\"BrutCSS\",\"link\":\"/brut-css/index.html\",\"target\":\"_self\"}],\"outline\":[2,3],\"sidebar\":[{\"text\":\"Overview\",\"collapsed\":false,\"items\":[{\"text\":\"Getting Started\",\"link\":\"/getting-started\"},{\"text\":\"Concepts\",\"link\":\"/overview\"},{\"text\":\"Documentation Conventions\",\"link\":\"/doc-conventions\"},{\"text\":\"Tutorial\",\"link\":\"/tutorial\"},{\"text\":\"Dev Environment\",\"link\":\"/dev-environment\"},{\"text\":\"AI Declaration\",\"link\":\"/ai\"}]},{\"text\":\"Front-End\",\"collapsed\":false,\"items\":[{\"text\":\"Routes\",\"link\":\"/routes\"},{\"text\":\"Pages\",\"link\":\"/pages\"},{\"text\":\"Forms\",\"link\":\"/forms\"},{\"text\":\"Handlers and Actions\",\"link\":\"/handlers\"},{\"text\":\"Components\",\"link\":\"/components\"},{\"text\":\"Flash and Session\",\"link\":\"/flash-and-session\"},{\"text\":\"Space/Time Continuum\",\"link\":\"/space-time-continuum\"},{\"text\":\"JavaScript\",\"link\":\"/javascript\"},{\"text\":\"CSS\",\"link\":\"/css\"},{\"text\":\"Assets\",\"link\":\"/assets\"},{\"text\":\"BrutJS\",\"link\":\"/brut-js\"}]},{\"text\":\"Back-End\",\"collapsed\":false,\"items\":[{\"text\":\"Database Schema\",\"link\":\"/database-schema\"},{\"text\":\"Database Access\",\"link\":\"/database-access\"},{\"text\":\"Seed Data\",\"link\":\"/seed-data\"},{\"text\":\"Jobs\",\"link\":\"/jobs\"},{\"text\":\"Business Logic\",\"link\":\"/business-logic\"}]},{\"text\":\"Framework\",\"collapsed\":false,\"items\":[{\"text\":\"Configuration\",\"link\":\"/configuration\"},{\"text\":\"Keyword Injection\",\"link\":\"/keyword-injection\"},{\"text\":\"I18n\",\"link\":\"/i18n\"},{\"text\":\"CLI / Tasks\",\"link\":\"/cli\"},{\"text\":\"Deployment\",\"link\":\"/deployment\"}]},{\"text\":\"Testing\",\"collapsed\":false,\"items\":[{\"text\":\"Unit Tests\",\"link\":\"/unit-tests\"},{\"text\":\"End-to-End Tests\",\"link\":\"/end-to-end-tests\"},{\"text\":\"Testing Custom Elements\",\"link\":\"/custom-element-tests\"}]},{\"text\":\"Advanced Topics\",\"collapsed\":false,\"items\":[{\"text\":\"Route Hooks\",\"link\":\"/hooks\"},{\"text\":\"Middleware\",\"link\":\"/middleware\"},{\"text\":\"Instrumentation\",\"link\":\"/instrumentation\"},{\"text\":\"Security\",\"link\":\"/security\"}]}],\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/thirdtank/brut\"}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    
+  </body>
+</html>