monkrb 0.19.0 → 0.21.0

data/lib/monk/persistence.rb

@@ -1,4 +1,5 @@
 require_relative "freeze_hooks"
+require_relative "persistence/pool"
 
 module Monk
   # Backend-agnostic persistence. Concrete backends (e.g.
@@ -8,6 +9,16 @@ module Monk
   # can seal every backend actually in use without needing to know their
   # names.
   module Persistence
+    # Closes every connection this Ractor opened, in every backend. A
+    # Ractor that ends leaves its connections to the garbage collector,
+    # which may not run for a long time; one that opened any calls this
+    # as it finishes (Monk::WebSocket::Server.serve, for a socket's).
+    def self.disconnect_all
+      # A copy: each backend's disconnect_all removes its own key.
+      backends = Ractor.current[:monk_persistence]&.keys || []
+      backends.each(&:disconnect_all)
+    end
+
     # Shared by every backend module: per-Ractor connection lifecycle, a
     # registry of named configs, and boot-time shareability sealing. A
     # backend `extend`s this and implements #connect(**opts) /
@@ -27,6 +38,14 @@ module Monk
         configs[name] = opts
       end
 
+      # The options a database was registered with, for something that
+      # opens its own connection to it (PgFanout's LISTEN).
+      def connection_options(name)
+        configs.fetch(name) do
+          raise Monk::UnknownPersistenceError, "no database registered as #{name.inspect}"
+        end
+      end
+
       # Registered connection names (e.g. :primary) -- Monk.boot's log
       # line reads this to report which backends an app actually uses.
       def names
@@ -37,6 +56,76 @@ module Monk
         entry(name).conn
       end
 
+      # With options, declares a named pool (docs/history/plan-pg-pool.md):
+      # `size` worker Ractors, each with its own connection to the
+      # registered database `db`, that run calls sent from any other
+      # Ractor. Nothing connects until #start_pools! runs, in the process
+      # that uses it. Every process loads the declarations
+      # (config/persistence.rb), next to #register.
+      #
+      # Without options, returns the started pool, from any Ractor.
+      # Raises if it was never declared, or declared but not started in
+      # this process.
+      def pool(name, **options)
+        return declare_pool(name, **options) unless options.empty?
+
+        handle = @running && @running[name]
+        return handle if handle
+
+        pool_config(name)
+        raise Monk::PoolNotStartedError,
+          "pool #{name.inspect} is declared but not started in this process -- call " \
+          "#{self}.start_pools!(#{name.inspect}) at boot in the process that uses it"
+      end
+
+      # Starts declared pools in this process: each pool's dispatcher and
+      # `size` workers, each worker with its own connection. Returns once
+      # every worker has connected; raises Monk::PoolStartError if any
+      # can't, and starts nothing for that pool. Main Ractor only, at boot,
+      # after every register and pool declaration: it freezes the
+      # registry, since the workers read it. A pool already started is
+      # left alone.
+      def start_pools!(*names)
+        unless Ractor.current == Ractor.main
+          raise ArgumentError, "#{self}.start_pools! runs in the main Ractor, at boot"
+        end
+
+        freeze_registry!
+        names.each { |name| start_pool(name) unless @running&.key?(name) }
+        self
+      end
+
+      # Hook: makes a copy of an exception fit to leave a pool's worker for
+      # another Ractor, by dropping what can't be copied. A backend whose
+      # errors carry nothing like that keeps this default.
+      def make_portable(_error) = nil
+
+      # This Ractor's own connections to this backend, closed and
+      # forgotten. A pool worker runs it as it stops; the next checkout in
+      # this Ractor reconnects.
+      def disconnect_all
+        Ractor.current[:monk_persistence]&.delete(self)&.each_value do |e|
+          disconnect(e.conn)
+        rescue StandardError
+          nil
+        end
+      end
+
+      # The pools started in this process, name => size (Monk.boot's line).
+      def running_pools
+        (@running || {}).transform_values { |handle| handle.config.size }
+      end
+
+      # A declared pool's options (a frozen Pool::Config).
+      def pool_config(name)
+        pools.fetch(name) do
+          raise Monk::UnknownPoolError,
+            "pool #{name.inspect} was never declared -- declare it once at boot with " \
+            "#{self}.pool(#{name.inspect}, size: #{Pool::DEFAULTS[:size]}); " \
+            "pool(#{name.inspect}) with no options only looks one up"
+        end
+      end
+
       def checkout(name, timeout: DEFAULT_CHECKOUT_TIMEOUT)
         e = entry(name)
         token = e.slot.pop(timeout: timeout)
@@ -46,9 +135,18 @@ module Monk
             "(checkout held longer than #{timeout}s)"
         end
 
+        # Checked here, before the block, and never by re-running it: Monk
+        # can't tell whether a failed block's writes reached the server,
+        # so a drop in the middle of a block fails that block, and the
+        # next checkout finds the connection dead and revives it. A
+        # revive that can't reach the server raises from here.
+        revive(e.conn) unless alive?(e.conn)
         yield e.conn
       ensure
-        e.slot << true if token
+        if token
+          release(e.conn)
+          e.slot << true
+        end
       end
 
       # Called from Base#freeze! (Seam B), via Monk.freeze_hooks.
@@ -61,17 +159,16 @@ module Monk
       # the value (not the module) fixes it, the same way it did there.
       def freeze_registry!
         @configs = Ractor.make_shareable(configs)
+        @pools = Ractor.make_shareable(pools)
       end
 
       # Test-only: drops all registered configs and this Ractor's cached
       # connections. Not part of the app-facing API.
       def reset!
-        Ractor.current[:monk_persistence]&.each_value do |e|
-          disconnect(e.conn)
-        rescue StandardError
-        end
-        Ractor.current[:monk_persistence] = {}
+        stop_pools
+        disconnect_all
         @configs = {}
+        @pools = {}
       end
 
       private
@@ -80,8 +177,87 @@ module Monk
         @configs ||= {}
       end
 
+      def pools
+        @pools ||= {}
+      end
+
+      # The started pools' dispatchers and inboxes, which only this (the
+      # main) Ractor uses: to stop them. Kept apart from @running, the
+      # frozen handles every Ractor reads.
+      def pool_ractors
+        @pool_ractors ||= {}
+      end
+
+      def start_pool(name)
+        ready = Ractor::Port.new
+        dispatcher = Ractor.new(self, pool_config(name), ready, name: "monk-pool-#{name}") do |backend, config, r|
+          Monk::Persistence::Pool::Dispatcher.run(backend, config, r)
+        end
+        status, value = ready.receive
+        unless status == :ok
+          dispatcher.join
+          raise Monk::PoolStartError, "pool #{name.inspect} couldn't connect its workers: #{value}"
+        end
+
+        pool_ractors[name] = { dispatcher: dispatcher, inbox: value }
+        handle = Pool::Handle.new(config: pool_config(name), inbox: value)
+        @running = Ractor.make_shareable((@running || {}).merge(name => handle))
+      ensure
+        ready&.close
+      end
+
+      # Test-only path (reset!). The dispatcher stops its workers, each
+      # finishing the call in hand, and answers every caller still waiting.
+      def stop_pools
+        pool_ractors.each_key { |name| stop_pool(name) }
+        @running = nil
+      end
+
+      def stop_pool(name)
+        stopping = pool_ractors.delete(name)
+        return unless stopping
+
+        send_stop(stopping[:inbox], [:stop])
+        stopping[:dispatcher].join
+      end
+
+      def send_stop(port, message)
+        port.send(message)
+      rescue Ractor::ClosedError
+        nil # already ended
+      end
+
+      def declare_pool(name, **options)
+        unknown = options.keys - Pool::DEFAULTS.keys
+        raise ArgumentError, "unknown pool option(s) #{unknown.join(", ")} for #{name.inspect}" if unknown.any?
+        raise ArgumentError, "pool #{name.inspect} is already declared" if pools.key?(name)
+
+        config = Pool::Config.new(name: name, **Pool::DEFAULTS, **options)
+        validate_pool!(config)
+        pools[name] = Ractor.make_shareable(config)
+      end
+
+      def validate_pool!(config)
+        unless configs.key?(config.db)
+          raise Monk::UnknownPersistenceError,
+            "pool #{config.name.inspect} uses db: #{config.db.inspect}, but no database is registered as " \
+            "#{config.db.inspect} -- call #{self}.register(#{config.db.inspect}, ...) before declaring the pool"
+        end
+
+        { size: Integer, queue: Integer, timeout: Numeric }.each do |option, type|
+          value = config.public_send(option)
+          next if value.is_a?(type) && value.positive?
+
+          raise ArgumentError,
+            "pool #{config.name.inspect}: #{option}: must be a positive #{type}, got #{value.inspect}"
+        end
+      end
+
+      # This Ractor's connections, by backend, then by name: so
+      # Persistence.disconnect_all can find every backend this Ractor
+      # used, from any Ractor.
       def ractor_local
-        Ractor.current[:monk_persistence] ||= {}
+        (Ractor.current[:monk_persistence] ||= {})[self] ||= {}
       end
 
       def entry(name)
@@ -108,6 +284,19 @@ module Monk
       def disconnect(conn)
         raise NotImplementedError, "#{self} must implement #disconnect(conn)"
       end
+
+      # Optional hooks around #checkout's block. A backend that can't tell
+      # a dead connection from a live one keeps these defaults.
+
+      # Whether conn can take a query. Cheap: runs before every checkout.
+      def alive?(_conn) = true
+
+      # Reconnects a connection #alive? said was dead; raises if it can't.
+      def revive(_conn) = nil
+
+      # Runs after every checkout's block, however it ended. Must not
+      # raise: it runs in an ensure, and would hide the block's exception.
+      def release(_conn) = nil
     end
   end
 end

data/lib/monk/templates/auth/agents.md

@@ -0,0 +1,29 @@
+## auth
+
+**Where:** `config/auth.rb` (settings, `callback_path:`),
+`app/routes/auth.rb` (the routes, commented: block `auth-routes`),
+`app/mailers/auth_mailer.rb` (sends the link), `app/views/auth/login.erb`
+(the login page), `app/views/mail/magic_link.erb` (the email's HTML).
+
+**Main calls:** `Monk::Auth.request_login(email)` returns a token;
+`Monk::Auth.login_link(token)` builds its link;
+`Monk::Auth.deliver_link(email:, link:, token:)` sends it;
+`Monk::Auth.redeem(token)` returns a session or nil. In routes:
+`set_session_cookie(session)`, `current_subject` (nil when logged out),
+`require_user!` (halts 401), `require_csrf!`, `log_out!`. With jobs:
+`Monk::Auth::SendLoginLink.enqueue(email)`.
+
+**Test:** `test/auth_test.rb` sends a link to `log/test.log` and redeems it.
+
+**Pitfalls:**
+- `/auth/request` needs a per-email rate limit before it goes live: without
+  one, anyone can make the app send mail to any address.
+- Never point `deliver:` at `Monk::Mail.deliver_later`: the link, token
+  included, would sit in the job queue. Use `SendLoginLink` instead.
+- Links come from `Monk::Settings[:public_url]`, never from request headers.
+- A `redirect_to` must be listed in `redirect_allowlist`.
+- Monk reads `params` from JSON bodies and query strings, not form bodies:
+  pages post with `fetch`. A cookie-authenticated POST sends the
+  `x-csrf-token` header (the `csrf_token` cookie's value).
+
+**Examples:** `auth-routes` in `app/routes/auth.rb`.

data/lib/monk/templates/auth/app/mailers/{app_mailer.rb → auth_mailer.rb}

@@ -1,9 +1,9 @@
-# The emails this app sends, through Monk::Mail (config/mail.rb). Module
-# constants and module methods rather than an instance, since Monk::Auth's
-# deliver: hook must be Ractor-shareable (a lambda built at a file's top
-# level, where self isn't, would fail) -- the same constraint as
+# The login email Monk::Auth sends (config/auth.rb's deliver:), through
+# Monk::Mail (config/mail.rb). A lambda in a module constant: the deliver:
+# hook must be Ractor-shareable, and a lambda built at a file's top level,
+# where self isn't, would fail -- the same constraint as
 # Monk::Live.authorize blocks.
-module AppMailer
+module AuthMailer
   # Monk::Auth's deliver: hook (config/auth.rb), called by
   # Monk::Auth.deliver_link. The HTML part is
   # app/views/mail/magic_link.erb. Swap the body for SMS or any other

data/lib/monk/templates/auth/app/routes/auth.rb

@@ -0,0 +1,48 @@
+# Logging in by email link (monk add auth). Monk::Auth makes and checks the
+# tokens and sessions; these routes are the app's own, because they carry
+# its decisions: the rate limit, where to go after logging in, JSON or HTML.
+#
+# monk:example auth-routes -- log in by email link, log out, a page for logged-in users.
+# # Before going live: keep a rate limit (without one, anyone can make this
+# # app send mail to any address), and list your redirects in config/auth.rb.
+# module AuthRoutes
+#   # Per process and approximate: 5 links per address per 10 minutes. With
+#   # several bin/server processes, count in the database instead.
+#   LIMIT = Monk::Auth::RateLimiter.new(limit: 5, window: 600)
+# end
+#
+# class App
+#   get("/login") { @title = "Log in"; render "auth/login" }
+#
+#   # app/views/auth/login.erb sends {"email": "..."} as JSON.
+#   post("/auth/request") do
+#     email = params[:email].to_s.strip.downcase
+#     halt(422) if email.empty?
+#     halt(429) if AuthRoutes::LIMIT.exceeded?(email)
+#
+#     # Sent here, in the request. With jobs, replace these two lines with
+#     # Monk::Auth::SendLoginLink.enqueue(email): the token is then made and
+#     # sent in bin/jobs, and never stored.
+#     token = Monk::Auth.request_login(email)
+#     Monk::Auth.deliver_link(email: email, link: Monk::Auth.login_link(token), token: token)
+#     json(sent: true)
+#   end
+#
+#   # The link in the email: callback_path in config/auth.rb.
+#   get("/auth/callback/:token") do
+#     session = Monk::Auth.redeem(params[:token]) || halt(401, "This link has expired or was already used.")
+#     set_session_cookie(session)
+#     redirect(session[:redirect_to] || "/")
+#   end
+#
+#   # From a page: fetch("/auth/logout", { method: "POST", headers: { "x-csrf-token": csrfToken } }),
+#   # where csrfToken is the csrf_token cookie's value.
+#   post("/auth/logout") do
+#     require_csrf!
+#     log_out!
+#     json(logged_out: true)
+#   end
+#
+#   get("/me") { json(email: require_user!) }
+# end
+# monk:end

data/lib/monk/templates/auth/app/views/auth/login.erb

@@ -0,0 +1,25 @@
+<h1>Log in</h1>
+
+<%# Sent with fetch and a JSON body: Monk reads params from JSON bodies,
+    not form bodies. POST /auth/request is in app/routes/auth.rb. %>
+<form id="login">
+  <label>Email <input type="email" name="email" required autocomplete="email"></label>
+  <button>Send me a login link</button>
+</form>
+<p id="login-sent" hidden>Check your email for the link.</p>
+
+<script type="module">
+  const form = document.getElementById("login")
+  form.addEventListener("submit", async (event) => {
+    event.preventDefault()
+    const response = await fetch("/auth/request", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ email: form.email.value }),
+    })
+    if (response.ok) {
+      form.hidden = true
+      document.getElementById("login-sent").hidden = false
+    }
+  })
+</script>

data/lib/monk/templates/auth/config/auth.rb

@@ -2,17 +2,16 @@ require "monk"
 require "monk/auth"
 require_relative "persistence"
 
-# config/settings.rb already declares public_url -- the trusted origin for
-# the magic link your own login route builds (e.g.
-# "#{Monk::Settings[:public_url]}/auth/callback/#{token}"), see its comment
-# there and auth.md's "Sending the magic link".
+# Magic links are Monk::Auth.login_link(token): config/settings.rb's
+# public_url (the trusted origin), then callback_path: below, then the
+# token -- see auth.md's "Sending the magic link".
 
-# Sends the magic link by email: AppMailer::MAGIC_LINK, in
-# app/mailers/app_mailer.rb. Required here, not left to config/load.rb:
+# Sends the magic link by email: AuthMailer::MAGIC_LINK, in
+# app/mailers/auth_mailer.rb. Required here, not left to config/load.rb:
 # Monk::Auth.configure checks deliver: right away, and bin/websocket_server
 # loads this file without config/load.rb. The mailer only touches
 # Monk::Mail when it's called, so that process needs no mail config.
-require_relative "../app/mailers/app_mailer"
+require_relative "../app/mailers/auth_mailer"
 
 Monk::Auth.configure(
   db_name: :primary,
@@ -20,6 +19,13 @@ Monk::Auth.configure(
   login_ttl: 600,          # seconds a login token stays redeemable
   session_ttl: 1_209_600,  # seconds a session stays valid (14 days)
   redirect_allowlist: [],  # paths request_login(redirect_to:) is allowed to target
+  callback_path: "/auth/callback", # your route redeeming a token: GET "#{callback_path}/:token"
   secure: !Monk.env.development?, # Secure cookie flag; off in dev so plain-http testing works (Safari drops it)
-  deliver: AppMailer::MAGIC_LINK,
+  deliver: AuthMailer::MAGIC_LINK,
 )
+
+# bin/websocket_server checks each socket's session through this pool, so
+# it holds 4 connections however many pages are open, instead of one per
+# open page. Declaring it opens nothing: only bin/websocket_server starts
+# it. See docs/guides/persistence.md, "Pools", in the monk repo.
+Monk::Persistence::Pg.pool(:auth, size: 4)

data/lib/monk/templates/auth/setup.md

@@ -0,0 +1,37 @@
+## auth
+
+Logging in by email link. `config/auth.rb` configures Monk::Auth,
+`app/mailers/auth_mailer.rb` sends the link through mail, and a migration
+creates the `login_tokens` and `sessions` tables: run `bin/setup_db` and
+`DB_NAME={{app}}_test bin/setup_db` (postgres, above).
+
+### Before production
+
+`AUTH_SECRET` in `.env` and `.env.test` is a placeholder. Set a long random
+one in production's environment, e.g. from
+`ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'`. `config/auth.rb`
+reads it with `ENV.fetch`: unset, the app doesn't boot.
+
+### Check it works
+
+1. `bundle exec rake test` runs `test/auth_test.rb`: a link is sent (to
+   `log/test.log`) and redeemed into a session.
+2. By hand: the login routes are commented out in `app/routes/auth.rb`,
+   block `auth-routes`. Uncomment them and restart `bin/server`. Then:
+   - http://localhost:9292/me answers `401`: nobody is logged in.
+   - http://localhost:9292/login: enter an email. In development the link
+     is printed, not sent: in `bin/server`'s console, or in `bin/jobs`'
+     when a job sends it (`Monk::Auth::SendLoginLink`), and in
+     `log/development.log` either way. Open it: it logs you in and goes
+     back to `/`.
+   - http://localhost:9292/me now shows your email.
+   - To log out, from the browser's console on any page of the app:
+
+     ```js
+     fetch("/auth/logout", { method: "POST", headers: {
+       "x-csrf-token": document.cookie.match(/csrf_token=([^;]+)/)[1] } })
+     ```
+
+     and `/me` answers `401` again.
+3. Before going live: keep the rate limit, and list in `config/auth.rb`
+   (`redirect_allowlist`) the paths a login may send the user back to.

data/lib/monk/templates/auth/test/auth_test.rb

@@ -0,0 +1,17 @@
+require_relative "test_helper"
+
+# Monk::Auth works end to end without any route: a login link is created,
+# sent by config/auth.rb's deliver: (AuthMailer, to log/test.log here), and
+# redeemed into a session. SETUP.md, auth.
+class AuthTest < Minitest::Test
+  def test_a_login_link_is_sent_and_redeems_into_a_session
+    email = "login-check-#{rand(1_000_000)}@example.test"
+    token = Monk::Auth.request_login(email)
+
+    Monk::Auth.deliver_link(email: email, link: Monk::Auth.login_link(token), token: token)
+
+    assert_includes File.read(File.expand_path("../log/test.log", __dir__)), Monk::Auth.login_link(token)
+    session = Monk::Auth.redeem(token)
+    assert_equal email, Monk::Auth.verify(session[:token])
+  end
+end

data/lib/monk/templates/base/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

data/lib/monk/templates/base/Dockerfile

@@ -5,8 +5,8 @@
 # (Gemfile.lock committed) already resolves every compatible platform, not
 # just the machine that ran it -- nothing to add by hand before building on
 # a different host (docs/guides/deploying.md, "Before the first build").
-# monk/rackup/webrick are pure Ruby. The --postgres/--auth scaffold
-# overrides this file to add libpq for the pg gem's native extension.
+# monk/rackup/webrick are pure Ruby, and pg (monk add postgres) 1.6+
+# ships precompiled with its own libpq.
 FROM ruby:4.0-slim AS builder
 WORKDIR /app
 
@@ -23,6 +23,7 @@ COPY . .
 # platform that assigns its own). bin/websocket_server (WS_PORT default
 # 9293) is a separate process/deploy unit -- run this same image with
 # `bin/websocket_server` as the command instead of publishing another
-# port from this Dockerfile -- see docs/guides/deploying.md.
+# port from this Dockerfile -- see docs/guides/deploying.md. Every other
+# process in bin/ (bin/jobs, say) is the same: this image, that command.
 EXPOSE 9292
 CMD ["bin/server", "--bind", "0.0.0.0"]

data/lib/monk/templates/base/Gemfile

@@ -1,7 +1,12 @@
 source "https://rubygems.org"
 
-gem "monkrb", require: "monk"
+gem "monkrb", "~> 0.21", require: "monk"
 gem "rackup"
 gem "webrick"
 gem "kino"
-# gem "dotenv" # uncomment to load a local .env file (config/settings.rb)
+gem "dotenv" # loads .env files, see config/settings.rb
+
+group :test do
+  gem "minitest"
+  gem "rake"
+end

data/lib/monk/templates/base/Rakefile

@@ -0,0 +1,8 @@
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

data/lib/monk/templates/base/agents.md

@@ -0,0 +1,41 @@
+# {{app}}: notes for coding agents
+
+A Monk app (Ruby, Ractor-based). Read this before changing code.
+
+## Commands
+
+- `bin/server`: the app on :9292.
+- `bundle exec rake test`: all tests. Run them after every change.
+- `monk add --list --json`: the modules available, and which are installed.
+- `monk add <module> --json`: add a module. Never wire one by hand in
+  `config/load.rb`: it loads every module's config already.
+
+## Where code goes
+
+| Path | What |
+|---|---|
+| `app/app.rb` | `class App`, its base routes; loads `app/routes/*.rb` |
+| `app/routes/<name>.rb` | more routes, each file reopening `class App` |
+| `app/models/` `presenters/` `helpers/` `mailers/` `broadcasts/` `jobs/` | code by role, loaded in that order by `config/load.rb` |
+| `app/views/` | `.erb` templates only, the one template root |
+| `config/<module>.rb` | one per Monk module, loaded by `config/load.rb` in a fixed order |
+| `test/` | Minitest; `test/test_helper.rb` boots the app as `APP` |
+
+## Rules that break the app if ignored
+
+- Everything loads before `Monk.boot` freezes the app. Nothing can be
+  required later, from a route or a job.
+- Routes, jobs and Live rules run in Ractors. A block they use must be
+  Ractor-shareable: define it inside a module or class body, never at the
+  top level of a file (`self` there is the main object).
+- State shared across requests lives in a `Monk::StateRactor`, never in a
+  constant or a class variable.
+- Templates escape what they print. `raw(...)` is only for HTML the app
+  built itself.
+
+## Examples
+
+Commented examples are tagged `# monk:example <name>` ... `# monk:end`.
+`grep -rn "monk:example" app config` lists them; uncomment one and adapt it.
+
+## Modules

data/lib/monk/templates/base/app/app.rb

@@ -7,3 +7,8 @@ class App < Monk::Base
   get("/hello") { "hello from monk" }
   get("/api/hello") { json(message: "hello from monk") }
 end
+
+# More routes, each file reopening `class App`: the ones Monk modules add
+# (monk add), and any of your own. Loaded in name order, before Monk.boot
+# freezes the app.
+Dir[File.expand_path("routes/*.rb", __dir__)].sort.each { |file| require file }

data/lib/monk/templates/base/app/views/index.erb

@@ -1,6 +1,6 @@
 <h1>It works</h1>
 <p>
-  Edit <code>views/index.erb</code> and restart the server to see this
+  Edit <code>app/views/index.erb</code> and restart the server to see this
   change. Templates compile once at boot; <code>&lt;%= %&gt;</code>
   escapes by default, <code>raw(...)</code> opts out.
 </p>

data/lib/monk/templates/base/app/views/layouts/app.erb

@@ -11,6 +11,8 @@
       { "imports": {} }
     </script>
     <script type="module" src="<%= asset_path "/js/app.js" %>"></script>
+    <%# The <head> tags of the Monk modules this app uses (Monk::Live's, say). %>
+    <%= monk_head %>
   </head>
   <body>
     <main><%= yield %></main>

data/lib/monk/templates/base/config/load.rb

@@ -3,6 +3,14 @@
 # it never boots the app itself (that's config.ru's Monk.boot).
 require_relative "settings"
 
+# Each Monk module's config, if this app has it (`monk add <module>` writes
+# it), in Monk's fixed order: a module's config may rely on the ones
+# before it. Nothing to edit here when a module is added.
+%w[persistence redis auth mail jobs websocket live storage].each do |name|
+  path = File.expand_path("#{name}.rb", __dir__)
+  require path if File.exist?(path)
+end
+
 # The app's code, one directory per role, in the order they call each
 # other: presenters read models, helpers, mailers and broadcasts use both,
 # and jobs call all of them. Everything is loaded here, before Monk.boot

data/lib/monk/templates/base/config/settings.rb

@@ -1,8 +1,7 @@
-# Loads a local .env file in development, if the app has uncommented the
-# dotenv gem in its Gemfile (see the commented-out line there) and added
-# a .env file of its own. A missing .env, or the gem not being in the
-# bundle at all, is a harmless no-op either way -- production deploys
-# get their env vars from the hosting platform directly, not from here.
+# Loads a local .env file, written by the modules `monk add` adds (DB_*,
+# MAIL_*, ...). A missing .env, or the dotenv gem not being in the bundle
+# at all, is a harmless no-op either way -- production deploys get their
+# env vars from the hosting platform directly, not from here.
 begin
   require "dotenv/load"
 rescue LoadError

data/lib/monk/templates/base/setup.md

@@ -0,0 +1,22 @@
+# Setting up {{app}}
+
+## First run
+
+```bash
+bundle install
+bin/server              # the app on http://localhost:9292
+```
+
+## Check it works
+
+1. `bundle exec rake test` runs the tests.
+2. By hand: with `bin/server` running, http://localhost:9292 shows
+   "It works", and http://localhost:9292/hello answers `hello from monk`.
+
+`test/test_helper.rb` loads `.env.test` (if there is one), then the app the
+way `config.ru` does, booted once as `APP`; `test/app_test.rb` makes a
+request through it. Minitest, like Monk's own suite.
+
+Each module added with `monk add` appends its own section below: the
+services it needs, how to start them, and how to check it works, with its
+test and by hand.