monkrb 0.20.0 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0346b062053981ee7d06c7d3cc9b563c429c1b81443e449b683e53a8080005a1
-  data.tar.gz: 8793cbc85210dc77a03b41e3adc39f58fed92488ef2662d2222c9136f5c55f4f
+  metadata.gz: fd1a1140ab4c223d2bdd9c10a226ea274e0051af1ab01444194cb4dc88ebb166
+  data.tar.gz: 9fab9365ba1a31224caf14038c2e36c0ba59c9cc70dd60c037f4dbfa78aec8c8
 SHA512:
-  metadata.gz: 711bddca3ff4fbe17dd0b776e3a759ede7a810304e7c42ad96e5e2dfb6c37e9ad5b77ebad8c5f6224a3c993544722e55067ebffc57c1d20f7436c18021b5afae
-  data.tar.gz: e79bb8a6e8d1b77c8bf0227ce0ceeaf16a3ec87b733ce063e8dc32ae7ebd0b24d19915440fb8603f1fe453c74ee91fbe04c68e41e41c84060e6f2d75eaca7353
+  metadata.gz: 36bf94be6268d9f12fbb703132f96b00a84c52e5eeb6b03d9b90b9e981d5c9be2ee89003ecc7952b2880d288454d4d6d1734ffb6cfd8bd70328dded0cbbc1e0e
+  data.tar.gz: 58c8a897231b31edcc82cfd0e3162c64633a2a121f2b3cc01dbbe3b2fa6ef7a7d9760eb2b623a4b6b8def85004322abba20b001758dadd291f8a2ada52b3d26b

data/CHANGELOG.md

@@ -4,6 +4,105 @@ All notable changes to this project are documented here. Format is loosely
 [Keep a Changelog](https://keepachangelog.com/); versions are as released
 in `lib/monk/version.rb`.
 
+## 0.21.1 - 2026-10-09
+
+### Fixed
+
+- **`monk add websocket --transport=postgres` publishes through the
+  `:notify` pool.** `config/websocket.rb` declares
+  `Monk::Persistence::Pg.pool(:notify, size: 1)` and builds
+  `PgFanout.new(..., db_pool: :notify)`, so a process holds one publishing
+  connection however many Ractors publish. Before, every `bin/server`
+  worker opened its own. `AppWebSocket.start!` starts the pool (with
+  Redis it does nothing): `config/load.rb` calls it at the end, which
+  covers `bin/server`, `bin/jobs`, `bin/console` and the tests, and
+  `bin/websocket_server` calls it too. An existing app: replace
+  `config/websocket.rb` with
+  `monk help websocket --file config/websocket.rb --transport=postgres`
+  and add the last lines of `monk help base --file config/load.rb`.
+- **The scaffolded `Dockerfile` builds with `monk add postgres`.** Its
+  builder stage installs `build-essential`: `irb`'s dependencies (`erb`,
+  `io-console`, `prism`) compile native extensions. The image that runs
+  still has no compiler. An existing app: add the `apt-get` line from
+  `monk help base --file Dockerfile`.
+
+## 0.21.0 - 2026-10-09
+
+### Changed (breaking)
+
+- **`monk new` no longer takes module flags.** `--postgres`, `--auth`,
+  `--mail`, `--jobs`, `--redis` and `--live` are a usage error that shows
+  the same command's new form, and nothing is written. Modules are added
+  with `monk add MODULE`, on any app, new or existing, or with
+  `monk new NAME --with a,b` (ADR 0017, `docs/guides/scaffolding.md`).
+
+### Added
+
+- **`monk add`**: one generator per module (`postgres`, `redis`, `mail`,
+  `auth`, `jobs`, `websocket`, `live`). Each adds its dependencies first,
+  creates files and appends lines (never edits or replaces one), and
+  brings its wiring, commented examples of how to use it (tagged
+  `# monk:example`), a test in `test/`, and its sections of `SETUP.md` and
+  `AGENTS.md`. Adding a module twice does nothing. A file the module needs
+  that the app already has with other content stops the command before
+  anything is written; any other is left alone. `monk add --list`,
+  `monk help MODULE [--file PATH]`, `--dry-run`, and `--json` for agents
+  and scripts, with exit codes 0 (done), 1 (usage), 2 (a missing choice)
+  and 3 (a conflict). A missing choice is asked in a terminal, never
+  elsewhere.
+- **Redis and WebSocket are modules of their own.** `monk add redis` is for
+  any use of Redis (a cache, rate limits). `monk add websocket
+  --transport=postgres|redis` writes `config/websocket.rb`, one registry
+  (`AppWebSocket::REGISTRY`) over the chosen transport, and the new
+  `bin/websocket_server`; the transport is inferred when only one is
+  installed. Live uses websocket's registry.
+- **Every app ships its tests** (`Rakefile`, `test/test_helper.rb`,
+  `test/app_test.rb`), an `AGENTS.md` for coding agents and a `CLAUDE.md`
+  importing it; dotenv is in every `Gemfile`.
+- **Module routes live in `app/routes/`**, which `app/app.rb` loads; each
+  file reopens `class App` (amends ADR 0015). `config/load.rb` is the same
+  for every app: it requires each module's config that exists, in a fixed
+  order.
+- `Monk::Auth.configure(callback_path:)` (default `"/auth/callback"`) and
+  `Monk::Auth.login_link(token)`. `Monk::Auth::SendLoginLink`, the job that
+  creates and sends a login link, ships with Monk, once auth and jobs are
+  both loaded. `log_out!` ends the current session and clears its cookies.
+- `Monk::Mail.deliver_later` is defined once `monk/mail` and `monk/jobs`
+  are both loaded, in either order; `require "monk/mail/later"` still
+  works.
+- `<%= monk_head %>` in a layout renders the `<head>` tags of the loaded
+  modules (Live's, once `config/live.rb` has configured it).
+- `Monk::Assets.mount(prefix, dir)` serves a module's files from the gem
+  under `/_monk/`; Monk::Live's browser client is served at
+  `/_monk/live/`, so apps no longer copy it.
+- `Monk::Live::ALLOW_ALL`, a shareable rule block letting everyone in.
+- `Monk::Bin.run(__FILE__) { ... }`: a scaffolded app's `bin/` scripts end
+  with what failed and the command that fixes it (Postgres or Redis not
+  running, a missing database, refused credentials, an unset setting),
+  exit 1, instead of a backtrace.
+
+### Changed
+
+- `monk new`'s `Gemfile` asks for `gem "monkrb", "~> 0.21"`: a new app
+  needs this version's APIs (`monk_head`, `log_out!`, `Monk::Bin`), so an
+  older monkrb installed on the machine can't satisfy it.
+- `JOBS_QUEUES` defaults to `mailers,default` in `bin/jobs`, with or
+  without mail.
+- `monk add postgres` adds `gem "pg", "~> 1.6"`: 1.6+ installs precompiled
+  with its own libpq, so the one `Dockerfile` needs no system packages.
+- `config/persistence.rb` loads `Monk::Persistence::Pg::Model`, so an app
+  with only Postgres can define models.
+- Live's demo is its own files, at `/demo/live`, in development only
+  (`--no-demo` to leave it out); it no longer replaces `app/app.rb` and the
+  home page.
+
+### Fixed
+
+- `Monk::Log` works before Boot. In `bin/console`, which never boots,
+  anything that logged raised on a nil path: `Monk::Mail.deliver` through
+  `log://`, a job's `perform`, `Monk::Log.info`. Before Boot the first
+  write now works out the same `log/<env>.log` path.
+
 ## 0.20.0 - 2026-10-05
 
 ### Fixed

data/README.md

@@ -18,13 +18,14 @@ gem install monkrb
 monk new my_app && cd my_app
 bundle install
 bin/server           # -> http://localhost:9292/hello
+monk add --list      # the modules you can add: postgres, auth, jobs, live...
 ```
 
-`monk new` scaffolds the app's own `Gemfile` with `gem "monkrb", require: "monk"`.
+`monk new` scaffolds the app's own `Gemfile` with `gem "monkrb", "~> 0.21", require: "monk"`.
 
-`monk new` writes a working skeleton (an HTML home page, a `/hello` route, a `/api/hello` JSON route, `public/`, a `SETUP.md`), with the app's own code under `app/`: `app/app.rb` for routes, `app/views/`, and one directory per role (`models/`, `presenters/`, `helpers/`, `mailers/`, `broadcasts/`, `jobs/`). Flags add Postgres, auth, email, background jobs, Redis and live updates: see [`docs/guides/scaffolding.md`](docs/guides/scaffolding.md), which also says where each kind of code goes.
+`monk new` writes a working skeleton (an HTML home page, a `/hello` route, a `/api/hello` JSON route, `public/`, its tests, a `SETUP.md` and an `AGENTS.md` for coding agents), with the app's own code under `app/`: `app/app.rb` and `app/routes/` for routes, `app/views/`, and one directory per role (`models/`, `presenters/`, `helpers/`, `mailers/`, `broadcasts/`, `jobs/`). `monk add` adds Postgres, Redis, email, auth, background jobs, WebSocket and live updates, to a new app or an old one, each with its wiring, commented examples of how to use it, and a test (`monk new my_app --with auth,jobs` does both at once): see [`docs/guides/scaffolding.md`](docs/guides/scaffolding.md), which also says where each kind of code goes.
 
-All `monk` commands and flags are listed by:
+All `monk` commands and options are listed by:
 
 ```
 monk --help
@@ -60,11 +61,11 @@ Everything beyond the core is opt-in (`require "monk"` alone loads none of it).
 | Persistence | `Monk::Persistence::Pg`: raw `pg`, per-Ractor connections, hash-based `Model` | `require "monk/persistence/pg"` (+ `.../pg/model`); needs the `pg` gem | [`persistence.md`](docs/guides/persistence.md) |
 | Migrations | plain `.sql` up/down pairs, `Migrator` | `require "monk/persistence/pg/migrator"`; needs the `pg` gem | [`migrations.md`](docs/guides/migrations.md) |
 | Auth and sessions | `Monk::Auth`: passwordless tokens, Bearer or cookie + CSRF | `require "monk/auth"`; needs the `pg` gem and a registered Postgres connection | [`auth.md`](docs/guides/auth.md) |
-| Email | `Monk::Mail`: text/HTML email over SMTP or a local relay, one `MAIL_URL`, sent from any worker Ractor, or from a background job with `deliver_later` | `require "monk/mail"` (+ `require "monk/mail/later"` for `deliver_later`, which needs background jobs); SMTP needs the `net-smtp` gem | [`mail.md`](docs/guides/mail.md) |
+| Email | `Monk::Mail`: text/HTML email over SMTP or a local relay, one `MAIL_URL`, sent from any worker Ractor, or from a background job with `deliver_later` | `require "monk/mail"`; `deliver_later` is there once `monk/jobs` is loaded too; SMTP needs the `net-smtp` gem | [`mail.md`](docs/guides/mail.md) |
 | Background jobs | `Monk::Jobs`: a queue in Postgres, run by `bin/jobs` on worker Ractors; retries with backoff, scheduled jobs, enqueue inside the app's own transaction, `drain!` for tests | `require "monk/jobs"` (+ `require "monk/jobs/runtime"` in the job process); needs the `pg` gem and a registered Postgres connection | [`jobs.md`](docs/guides/jobs.md) |
 | WebSocket | `Monk::WebSocket`: RFC 6455 server as its own process, Redis or Postgres fan-out | `require "monk/websocket"`; fan-out: `require "monk/websocket/redis_fanout"` (+ the `redis` gem) or `require "monk/websocket/pg_fanout"` (+ the `pg` gem) | [`websocket.md`](docs/guides/websocket.md) |
 | Live updates | `Monk::Live`: server-rendered HTML patches pushed to open tabs | `require "monk/live"`; needs the WebSocket server and, across processes, Redis or Postgres | [`live.md`](docs/guides/live.md) |
-| Scaffolding | `monk new` and its flags; retrofitting Postgres, Auth, Redis or Jobs | — (the `monk` command; flags `--postgres`, `--auth`, `--mail`, `--jobs`, `--redis`, `--live`) | [`scaffolding.md`](docs/guides/scaffolding.md) |
+| Scaffolding | `monk new` and `monk add`: one generator per module, for a new app or an existing one; text or `--json` output | — (the `monk` command: `monk new NAME --with ...`, `monk add MODULE`, `monk add --list`) | [`scaffolding.md`](docs/guides/scaffolding.md) |
 
 ## More documentation
 
@@ -87,6 +88,6 @@ More (server modes, Docker) in [`docs/development.md`](docs/development.md).
 
 ## Status
 
-Monk is **pre-1.0** (see `lib/monk/version.rb` and the [changelog](CHANGELOG.md)): the API may still change between minor versions. The core is described in [`docs/history/core-plan.md`](docs/history/core-plan.md). There's no open roadmap issue at the moment; new work is proposed and tracked as it comes up. Done so far, each with its own design doc and plan: persistence, migrations, HTML templating and static assets, auth and sessions, WebSocket with Redis fan-out, log levels, live updates (`Monk::Live`, as of 2026-09-19), deployment support (Dockerfile scaffolding, `docs/guides/deploying.md`), the RubyGems release as `monkrb` (both 2026-09-22), and `Monk::WebSocket::PgFanout`/`monk new --live --postgres` — the same cross-process fan-out over Postgres `LISTEN`/`NOTIFY` instead of Redis, for an app that doesn't want a second piece of infrastructure (`docs/design/live-pg-fanout.md`, 2026-09-24), the built-in mailer `Monk::Mail` (0.17, 2026-09-26, ADR 0012), and background jobs on Postgres, `Monk::Jobs`, with mail sent from jobs (0.18, 2026-09-29, ADRs 0013 and 0014). In 0.19 (2026-10-01): `monk new` lays the app out under `app/`, one directory per role (ADR 0015); a WebSocket fanout listens only in the process that holds the sockets (`#listen!`); `authenticate: :optional` lets visitors' sockets in anonymously, for Live's rules to decide; and the WebSocket server stops cleanly on `TERM` (`docs/design/websocket.md`). In 0.20 (2026-10-05): Monk recovers from a dropped database connection (a Postgres restart, a failover) without a process restart. `checkout` reconnects a dead connection before running its block, never retrying the block itself; both fanouts' listeners reconnect and then make every open page resync; and a route that raises logs why (`docs/history/plan-pg-reconnect.md`). Also new: connection pools for Ractors that shouldn't each hold a connection (`Monk::Persistence::Pg.pool`). The WebSocket server's session checks, Live's subscribe rules and `PgFanout`'s publisher can run through one, so open pages share a few connections instead of holding one each: 1,000 open sockets on 4 connections (`docs/guides/persistence.md`, "Pools"; `docs/history/plan-pg-pool.md`).
+Monk is **pre-1.0** (see `lib/monk/version.rb` and the [changelog](CHANGELOG.md)): the API may still change between minor versions. The core is described in [`docs/history/core-plan.md`](docs/history/core-plan.md). Features to add are listed in [`docs/roadmap.md`](docs/roadmap.md). Done so far, each with its own design doc and plan: persistence, migrations, HTML templating and static assets, auth and sessions, WebSocket with Redis fan-out, log levels, live updates (`Monk::Live`, as of 2026-09-19), deployment support (Dockerfile scaffolding, `docs/guides/deploying.md`), the RubyGems release as `monkrb` (both 2026-09-22), and `Monk::WebSocket::PgFanout`/`monk new --live --postgres` — the same cross-process fan-out over Postgres `LISTEN`/`NOTIFY` instead of Redis, for an app that doesn't want a second piece of infrastructure (`docs/design/live-pg-fanout.md`, 2026-09-24), the built-in mailer `Monk::Mail` (0.17, 2026-09-26, ADR 0012), and background jobs on Postgres, `Monk::Jobs`, with mail sent from jobs (0.18, 2026-09-29, ADRs 0013 and 0014). In 0.19 (2026-10-01): `monk new` lays the app out under `app/`, one directory per role (ADR 0015); a WebSocket fanout listens only in the process that holds the sockets (`#listen!`); `authenticate: :optional` lets visitors' sockets in anonymously, for Live's rules to decide; and the WebSocket server stops cleanly on `TERM` (`docs/design/websocket.md`). In 0.20 (2026-10-05): Monk recovers from a dropped database connection (a Postgres restart, a failover) without a process restart. `checkout` reconnects a dead connection before running its block, never retrying the block itself; both fanouts' listeners reconnect and then make every open page resync; and a route that raises logs why (`docs/history/plan-pg-reconnect.md`). Also new: connection pools for Ractors that shouldn't each hold a connection (`Monk::Persistence::Pg.pool`). The WebSocket server's session checks, Live's subscribe rules and `PgFanout`'s publisher can run through one, so open pages share a few connections instead of holding one each: 1,000 open sockets on 4 connections (`docs/guides/persistence.md`, "Pools"; `docs/history/plan-pg-pool.md`). In 0.21 (2026-10-09): scaffolding by module. `monk new` makes the core app, and `monk add` adds a module (Postgres, Redis, mail, auth, jobs, WebSocket, Live) to any app, new or existing, with its wiring, commented examples, a test, and its sections of `SETUP.md` and an `AGENTS.md` for coding agents; `--json` for agents and scripts. Redis and WebSocket become modules of their own, the WebSocket transport is chosen once per app, and `monk new`'s module flags are gone (ADR 0017, `docs/guides/scaffolding.md`, `docs/history/plan-scaffold.md`).
 
 [Made with Love ❤️, Ruby 💎 and AI 🤖](docs/ai_usage_disclaimer.md)

data/exe/monk

@@ -1,183 +1,5 @@
 #!/usr/bin/env ruby
-require_relative "../lib/monk/scaffold"
+# monk new / monk add / monk help: docs/guides/scaffolding.md.
+require_relative "../lib/monk/cli"
 
-USAGE = "Usage: monk new APP_NAME [--postgres] [--auth] [--mail] [--redis] [--live] [--jobs]".freeze
-
-HELP = <<~TEXT.freeze
-  #{USAGE}
-
-  Creates a new Monk project at APP_NAME from a static skeleton -- refuses
-  to run if APP_NAME already exists.
-
-  Base skeleton: Gemfile, config.ru, .ruby-version, bin/server,
-  bin/websocket_server, SETUP.md -- WebSocket support needs no external
-  service, so unlike Postgres/Redis below it isn't gated behind a flag:
-  bin/websocket_server auto-authenticates if --auth's config/auth.rb is
-  present, and fans out across processes over Redis if --redis's
-  REDIS_URL is set, adapting at boot either way. SETUP.md is generated
-  for every flag combination, walking through dev-then-test setup for
-  this exact project -- including, since monk new scaffolds no test
-  framework itself, the minimum Minitest wiring to get a working
-  `bundle exec rake test`.
-
-  Options:
-      --postgres      Also scaffold Postgres persistence/migrations support:
-                       config/persistence.rb, bin/console, bin/setup_db,
-                       bin/migrate, db/migrate/. Also wires config.ru to
-                       require it, writes .env/.env.test/.env.example
-                       (DB_NAME defaulting to APP_NAME_development/_test,
-                       not the generic app_development fallback baked into
-                       config/persistence.rb itself), and uncomments
-                       gem "dotenv" in the Gemfile so .env actually loads
-                       (config/settings.rb's require "dotenv/load" is a
-                       no-op with it left commented). SETUP.md's dev/test
-                       steps grow to cover Postgres containers, database
-                       creation, and migrations.
-      --auth          Also scaffold Monk::Auth (passwordless token auth).
-                       Implies --postgres -- Auth is Postgres-only, so this
-                       always brings the persistence scaffold with it. Adds
-                       config/auth.rb and a migration creating the
-                       login_tokens/sessions tables it needs. config.ru
-                       requires config/auth instead of config/persistence
-                       (config/auth.rb itself requires persistence), and
-                       .env/.env.test/.env.example get an AUTH_SECRET line.
-                       Also implies --mail, below: config/auth.rb sends the
-                       magic link through Monk::Mail, with an HTML part in
-                       views/mail/magic_link.erb.
-      --mail          Also scaffold Monk::Mail (text/HTML email over SMTP),
-                       no Postgres needed: config/mail.rb, required by
-                       config.ru, plus gem "net-smtp" in the Gemfile.
-                       .env/.env.test/.env.example get MAIL_FROM, and
-                       MAIL_URL where it matters: log:// in .env.test, an
-                       smtp:// placeholder in .env.example. Unset in
-                       development, MAIL_URL means log:// (messages printed,
-                       not sent); anywhere else it must be set.
-      --redis        Add the redis gem to the Gemfile, for
-                       bin/websocket_server's cross-process fan-out. Fully
-                       independent -- doesn't imply, and isn't implied by,
-                       --postgres or --auth. Writes/extends .env and
-                       .env.example with a REDIS_URL line (deliberately
-                       never .env.test -- only a test that exercises
-                       RedisFanout needs it) and uncomments gem "dotenv"
-                       if it isn't already (same reasoning as --postgres
-                       above), same whether or not --postgres is also set.
-
-      --live          Also scaffold Monk::Live: a demo counter whose open tabs
-                       update by themselves, pushed as HTML over a WebSocket.
-                       Requires --redis or --postgres: bin/server and
-                       bin/websocket_server are always separate processes, so
-                       one of the two has to carry a publish between them --
-                       with --redis, the usual Redis wiring; with --postgres
-                       (and not --redis), Monk::WebSocket::PgFanout over
-                       LISTEN/NOTIFY instead, reusing --postgres's own DB_*
-                       settings, so there's no Redis to run. Passing both
-                       picks --redis; passing neither is an error, since
-                       there's no way to tell whether Postgres is available.
-                       Adds
-                       config/live.rb, views/live/_hits.erb and the browser
-                       runtime under public/js/monk_live/, replaces config.ru,
-                       views/index.erb and bin/websocket_server with live
-                       versions, and adds the runtime's <meta>/<script> tags
-                       to the layout.
-      --jobs          Also scaffold Monk::Jobs (background jobs on Postgres).
-                       Implies --postgres, where the queue lives. Adds
-                       config/jobs.rb (required by config.ru, after
-                       persistence/auth/mail), jobs/hello_job.rb (a demo
-                       job, enqueued by a POST /jobs/hello route added to
-                       config.ru), bin/jobs (the job process, run beside
-                       bin/server), and the migration creating the queue's
-                       tables. .env/.env.example get JOBS_WORKERS and
-                       JOBS_QUEUES (not .env.test: tests run jobs with
-                       Monk::Jobs.drain!).
-
-  How flags combine -- a flag is implied when there's only one right
-  answer, and required when there's a real choice:
-
-      Flag         Implies               Requires
-      --auth       --postgres, --mail    -
-      --jobs       --postgres            -
-      --live       -                     --redis or --postgres (Live's
-                                         transport: a choice, so it's yours)
-      --postgres, --mail, --redis stand alone.
-
-  Some pairs also change what gets generated:
-
-      --auth + --jobs      jobs/send_login_link.rb: login links sent from a job
-      --mail + --jobs      config/jobs.rb loads Monk::Mail.deliver_later;
-                           JOBS_QUEUES serves mailers first
-      --live + --redis     config/live.rb fans out over Redis
-      --live + --postgres  config/live.rb fans out over Postgres (without --redis)
-
-  `monk new` prints which flags it turned on, and why, after creating the
-  project.
-
-  Commands:
-      new APP_NAME    Create a new project (see Options above)
-      help            Show this help (also --help, -h)
-
-  After creating a project:
-      cd APP_NAME
-      bundle install
-
-  See the generated SETUP.md for a full dev-then-test walkthrough, tailored
-  to whichever flags were passed. With --postgres (or --auth, which implies
-  it), short version, once a reachable Postgres exists (.env/.env.test have
-  the connection details):
-      bin/setup_db    Apply pending migrations
-      bin/migrate     migrate | rollback [N] | status
-      bin/console     IRB with persistence loaded
-
-  With --auth, .env/.env.test ship a placeholder AUTH_SECRET -- change it
-  before relying on it; config/auth.rb reads it via ENV.fetch and raises
-  if it's missing entirely.
-
-  With --redis, .env ships a placeholder REDIS_URL to turn
-  bin/websocket_server's cross-process fan-out on; unset (as in .env.test),
-  it runs in-process only, same as without --redis.
-TEXT
-
-def usage_error!
-  warn USAGE
-  exit 1
-end
-
-command, *rest = ARGV
-
-case command
-when nil, "help", "--help", "-h"
-  puts HELP
-when "new"
-  app_name = rest.find { |arg| !arg.start_with?("-") }
-  usage_error! if app_name.nil?
-
-  # Flags as typed: Monk::Scaffold resolves what they imply, and reports it.
-  auth = rest.include?("--auth")
-  mail = rest.include?("--mail") || auth # for the next-steps lines below
-  redis = rest.include?("--redis")
-  live = rest.include?("--live")
-  jobs = rest.include?("--jobs")
-  scaffold = Monk::Scaffold.new(
-    app_name, postgres: rest.include?("--postgres"), auth: auth, mail: rest.include?("--mail"), redis: redis,
-    live: live, jobs: jobs,
-  )
-  scaffold.write!
-
-  puts "Created #{app_name}."
-  puts scaffold.summary
-  puts "Next steps:"
-  puts "  cd #{app_name}"
-  puts "  bundle install"
-  puts "  see SETUP.md for the full dev-then-test walkthrough"
-  puts "  change the placeholder AUTH_SECRET in .env/.env.test before relying on it" if auth
-  puts "  set MAIL_URL and MAIL_FROM outside development (see config/mail.rb)" if mail
-  puts "  run bin/jobs beside bin/server to process background jobs (see SETUP.md)" if jobs
-  if live
-    if redis
-      puts "  Monk::Live needs Redis running, bin/server and bin/websocket_server (see SETUP.md)"
-    else
-      puts "  Monk::Live needs bin/server and bin/websocket_server running, sharing Postgres (see SETUP.md)"
-    end
-  end
-else
-  usage_error!
-end
+exit Monk::CLI.new.run(ARGV)

data/lib/monk/assets.rb

@@ -65,9 +65,28 @@ module Monk
       # hazard (Monk.env resolves this the same way, through Settings'
       # own frozen-at-Boot snapshot). `assets false` sets root to false
       # and disables serving.
-      attr_reader :root, :manifest
+      attr_reader :root, :manifest, :mounts
       attr_writer :root
 
+      # Serves a module's own static files from inside the gem, under a
+      # /_monk/ prefix, next to the app's public/: Monk::Live mounts its
+      # browser client at /_monk/live, so no app has to copy it
+      # (docs/adr/0017). Called when the module is required, before Boot;
+      # mounted files go in the same manifest, so they're served, stamped
+      # and cached exactly like the app's own.
+      def mount(prefix, dir)
+        prefix = prefix.chomp("/")
+        raise ArgumentError, "Monk::Assets.mount prefix must start with /_monk/, got #{prefix.inspect}" unless
+          prefix.start_with?("/_monk/")
+
+        @mounts = mounts.merge(prefix.freeze => File.expand_path(dir).freeze)
+      end
+
+      # Test-only.
+      def unmount(prefix)
+        @mounts = mounts.except(prefix)
+      end
+
       def enabled?
         !!root
       end
@@ -117,6 +136,7 @@ module Monk
       # Called from Base#freeze! (Seam B), via Monk.freeze_hooks.
       def freeze_registry!
         @production = !Monk.env.development?
+        @mounts = Ractor.make_shareable(mounts)
         @manifest = Ractor.make_shareable(build_manifest)
         # #root is read on every request (#enabled?, and the disk lookup
         # in development). Left unfrozen, reading it from a worker Ractor
@@ -125,7 +145,7 @@ module Monk
         @root = root.freeze
       end
 
-      # Test-only.
+      # Test-only. Mounts stay: a module mounts once, when it's required.
       def reset!
         @root = DEFAULT_ROOT
         @manifest = {}
@@ -142,29 +162,38 @@ module Monk
       private
 
       def build_manifest
-        return {} unless enabled? && Dir.exist?(root)
+        return {} unless enabled?
+
+        manifest = Dir.exist?(root) ? files_under(root, "") : {}
+        mounts.each { |prefix, dir| manifest.merge!(files_under(dir, prefix)) }
+        manifest
+      end
 
-        Dir.glob("**/*", base: root).each_with_object({}) do |relative, manifest|
-          path = File.join(root, relative)
+      def files_under(dir, prefix)
+        Dir.glob("**/*", base: dir).each_with_object({}) do |relative, files|
+          path = File.join(dir, relative)
           next unless File.file?(path)
 
-          manifest["/#{relative}"] = entry_for(relative, File.binread(path))
+          files["#{prefix}/#{relative}"] = entry_for(relative, File.binread(path))
         end
       end
 
       def lookup(path)
         return manifest[path] if production?
 
-        disk_entry(path)
+        prefix, dir = mounts.find { |mount_prefix, _| path.start_with?("#{mount_prefix}/") }
+        return disk_entry(dir, path.delete_prefix(prefix)) if prefix
+
+        disk_entry(root, path)
       end
 
       # Development only. PATH_INFO is not un-escaped here on purpose: an
       # encoded "%2e%2e" stays a literal, nonexistent filename, and a
       # decoded ".." is caught by the containment check below.
-      def disk_entry(path)
+      def disk_entry(dir, path)
         return nil if path.empty? || path.include?("\0")
 
-        root_path = File.expand_path(root)
+        root_path = File.expand_path(dir)
         full = File.expand_path(File.join(root_path, path.delete_prefix("/")))
         return nil unless full.start_with?("#{root_path}#{File::SEPARATOR}")
         return nil unless File.file?(full)
@@ -190,6 +219,7 @@ module Monk
 
     @root = DEFAULT_ROOT
     @manifest = {}
+    @mounts = {}
     @production = false
 
     Monk.freeze_hooks << self

data/lib/monk/auth/errors.rb

@@ -8,6 +8,9 @@ module Monk
   class MissingAuthConfigError < StandardError
   end
 
+  class InvalidAuthConfigError < StandardError
+  end
+
   class MissingAuthDeliveryError < StandardError
   end
 end

data/lib/monk/auth/helpers.rb

@@ -42,6 +42,17 @@ module Monk
         add_response_cookie("csrf_token", "", http_only: false, max_age: 0)
       end
 
+      # Ends the current session: revokes it, whether its token came as a
+      # Bearer header or the session cookie, and clears the cookies -- with
+      # or without a session to end. On a cookie-authenticated route, call
+      # require_csrf! first.
+      def log_out!
+        token = bearer_token || session_cookie_token
+        Monk::Auth.revoke(token) if token
+        clear_session_cookie
+        nil
+      end
+
       private
 
       def bearer_token

data/lib/monk/auth/send_login_link.rb

@@ -0,0 +1,36 @@
+# Monk::Auth::SendLoginLink. Loaded at the end of whichever of monk/auth
+# and monk/jobs is required second, once both are defined
+# (docs/adr/0017), so it requires neither itself.
+
+module Monk
+  module Auth
+    # Sends a magic link from bin/jobs instead of the login request. The
+    # token is created here, right before it's sent, so the raw token is
+    # never stored anywhere -- not even in the job queue, which pointing
+    # deliver: at Monk::Mail.deliver_later would do
+    # (docs/adr/0014-mail-from-jobs-and-login-links-created-in-the-job.md).
+    # Enqueue it from the app's login route, after its own per-email rate
+    # limit:
+    #
+    #   post("/auth/request") do
+    #     Monk::Auth::SendLoginLink.enqueue(params[:email])
+    #     json(sent: true)
+    #   end
+    #
+    # The link is Monk::Auth.login_link (public_url + callback_path:), and
+    # it's sent through configure's deliver:, synchronously, in the job.
+    # Subclass it to change the queue or the retries.
+    class SendLoginLink < Monk::Job
+      queue "mailers"
+      # About 50 seconds of retries: a login email minutes late, after the
+      # user has likely asked for another, is worse than none.
+      max_attempts 3
+      never_retry Monk::InvalidRedirectError
+
+      def self.perform(email, redirect_to = nil)
+        token = Monk::Auth.request_login(email, redirect_to: redirect_to)
+        Monk::Auth.deliver_link(email: email, link: Monk::Auth.login_link(token), token: token)
+      end
+    end
+  end
+end

data/lib/monk/auth.rb

@@ -34,13 +34,18 @@ module Monk
         freeze_rqrcode!
       end
 
+      # callback_path: is where the app's own callback route redeems a
+      # token (GET "#{callback_path}/:token"). Monk doesn't define that
+      # route, but builds links to it: login_link below, and so
+      # Monk::Auth::SendLoginLink.
       def configure(
         db_name: nil, secret: nil, login_ttl: nil, session_ttl: nil, redirect_allowlist: [], secure: true,
-        deliver: nil
+        deliver: nil, callback_path: "/auth/callback"
       )
         config = {
           db_name: db_name, secret: secret, login_ttl: login_ttl, session_ttl: session_ttl,
           redirect_allowlist: redirect_allowlist, secure: secure, deliver: deliver,
+          callback_path: checked_callback_path(callback_path),
         }
 
         REQUIRED_CONFIG_KEYS.each do |key|
@@ -81,6 +86,17 @@ module Monk
         raw
       end
 
+      # The magic link for a raw token: the app's public_url
+      # (config/settings.rb, a trusted origin -- never request headers like
+      # X-Forwarded-Host, which any direct client can spoof), then
+      # callback_path:, then the token.
+      #
+      #   Monk::Auth.login_link(token) # => "https://app.example/auth/callback/<token>"
+      def login_link(token)
+        ensure_configured!
+        "#{Monk::Settings[:public_url]}#{config[:callback_path]}/#{token}"
+      end
+
       # The single place an app's login-request handler calls to get a
       # magic link to its owner: uses the `deliver:` callable passed to
       # `configure` (e.g. wrapping a mailer or a provider's HTTP API) when
@@ -94,10 +110,8 @@ module Monk
       # that Monk::Mail exists (docs/adr/0012-minimal-built-in-mailer.md):
       # it's usually a one-line Monk::Mail.deliver, but can be any channel.
       #
-      # `link` is the app's own job to build (Monk doesn't own routing, so
-      # it can't know the callback path) -- from a trusted origin, e.g.
-      # Monk::Settings[:public_url], never from request headers like
-      # X-Forwarded-Proto/Host, which any direct client can spoof.
+      # `link` is usually login_link(token), above. An app may build its
+      # own instead, from a trusted origin, never from request headers.
       # `token` is passed through for a deliver: that wants it (an SMS
       # body instead of a link, say); most won't need it.
       def deliver_link(email:, link:, token: nil)
@@ -254,6 +268,17 @@ module Monk
           "Monk::Auth is not configured -- call Monk::Auth.configure first" unless @config
       end
 
+      # An absolute path, kept without a trailing slash so login_link
+      # adds exactly one before the token.
+      def checked_callback_path(path)
+        unless path.is_a?(String) && path.start_with?("/")
+          raise Monk::InvalidAuthConfigError,
+            "Monk::Auth.configure(callback_path:) must be an absolute path like \"/auth/callback\", got #{path.inspect}"
+        end
+
+        path.chomp("/").freeze
+      end
+
       def hash_token(raw)
         Digest::SHA256.hexdigest(raw)
       end
@@ -299,3 +324,7 @@ module Monk
     Monk.freeze_hooks << self
   end
 end
+
+# Monk::Auth::SendLoginLink, when jobs are loaded too -- either order works
+# (lib/monk/jobs.rb ends the same way, docs/adr/0017).
+require_relative "auth/send_login_link" if Monk.const_defined?(:Jobs)