trek 2.2.0 → 2.3.1

data/app/models/concerns/trek/sectionable.rb

@@ -9,6 +9,11 @@ module Trek
     end
 
     included do
+      # Sections are the host app's own `Section` model, which Trek doesn't generate: without one, a
+      # record has no sections, and declaring the association anyway would make `destroy` raise
+      # (`dependent: :destroy`). `const_defined?` also sees a model Zeitwerk hasn't loaded yet.
+      next unless Object.const_defined?(:Section)
+
       has_many :sections,
         -> { ordered },
         as: :sectionable,

data/app/models/concerns/trek/users/validations.rb

@@ -4,14 +4,23 @@ module Trek
       extend ActiveSupport::Concern
 
       included do
-        validates :password,
-          length: { minimum: 8 },
-          if: -> { new_record? || changes[:crypted_password] },
-          allow_blank: true
+        # Also applies to lookups (`find_by(email:)`, `authenticate_by`), so signing in and asking
+        # for a password reset work whatever the case typed.
+        normalizes :email, with: ->(email) { email.strip.downcase }
+
         validates :email,
           presence: true,
-          uniqueness: true,
-          format: { with: URI::MailTo::EMAIL_REGEXP }
+          uniqueness: { case_sensitive: false },
+          email: { mode: :strict }
+        # Only when a password was assigned: `password` is nil otherwise.
+        validates :password, length: { minimum: 8 }, allow_nil: true
+        validate :password_not_only_spaces
+      end
+
+      private
+
+      def password_not_only_spaces
+        errors.add(:password, :blank) if password&.strip&.empty?
       end
     end
   end

data/app/uploaders/audio_uploader.rb

@@ -0,0 +1,11 @@
+class AudioUploader < Shrine
+  plugin :determine_mime_type
+  plugin :validation_helpers
+  # The admin's sound field accepts files up to 200 MB (`Trek::Form::SoundFieldComponent`), above
+  # the 20 MB the Shrine initializer allows images.
+  plugin :upload_endpoint, url: true, max_size: 200.megabytes
+
+  Attacher.validate do
+    validate_mime_type %w[audio/mpeg audio/mp4 audio/aac audio/ogg audio/wav audio/x-wav audio/webm audio/flac]
+  end
+end

data/app/uploaders/record_image_uploader.rb

@@ -1,3 +1,6 @@
 class RecordImageUploader < ImageUploader
   plugin :activerecord
+  # Keeps a file attached during a save that reloads the record (closure_tree reorders siblings
+  # that way) pending, so it is still promoted out of the cache storage on commit.
+  plugin Trek::SavedAttachmentsReload
 end

data/config/locales/trek.en.yml

@@ -69,8 +69,8 @@ en:
           self: the same tab
       prompt:
         targets:
-          blank: un nouvel onglet
-          self: le même onglet
+          blank: a new tab
+          self: the same tab
     contents: Contents
     dashboard: Dashboard
     dashboards:
@@ -264,3 +264,4 @@ en:
   notices:
     authentication_needed: Please log in
     rate_limited: Too many attempts, please try again later
+    unauthorized: You are not allowed to do that

data/config/locales/trek.fr.yml

@@ -273,3 +273,4 @@ fr:
   notices:
     authentication_needed: Veuillez vous connecter
     rate_limited: Trop de tentatives, veuillez réessayer plus tard
+    unauthorized: Vous n'êtes pas autorisé·e à faire cela

data/docs/.vitepress/config.mjs

@@ -1,5 +1,9 @@
 import { defineConfig } from 'vitepress'
 import llmstxt from 'vitepress-plugin-llms'
+import { readFileSync } from 'node:fs'
+
+// The released version: `make release` keeps package.json in sync with lib/trek/version.rb.
+const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
 
 
 // https://vitepress.dev/reference/site-config
@@ -11,6 +15,13 @@ export default defineConfig({
   description: "A modern content management & back-office system for Ruby on Rails",
   lang: 'en-US',
   lastUpdated: true,
+  // The header logo doubles as the favicon (PNG versions for older browsers and iOS home screens,
+  // favicon.ico for clients that only request /favicon.ico).
+  head: [
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }],
+    ['link', { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/favicon.png' }],
+    ['link', { rel: 'apple-touch-icon', href: '/apple-touch-icon.png' }],
+  ],
   themeConfig: {
     logo: { src: '/logo.svg', width: 24, height: 24 },
 
@@ -18,7 +29,15 @@ export default defineConfig({
     nav: [
       { text: 'Home', link: '/' },
       { text: 'Guide', link: '/what-is-trek' },
-      { text: 'Reference', link: '/reference/' }
+      { text: 'Reference', link: '/reference/' },
+      {
+        text: `v${version}`,
+        items: [
+          { text: 'Changelog', link: '/changelog' },
+          { text: 'RubyGems', link: `https://rubygems.org/gems/trek/versions/${version}` },
+          { text: 'npm', link: `https://www.npmjs.com/package/trek/v/${version}` }
+        ]
+      }
     ],
 
     sidebar: {

data/docs/.vitepress/theme/style.css

@@ -75,15 +75,18 @@
  * -------------------------------------------------------------------------- */
 
 :root {
+  /* The violet end of the hero name gradient, a step darker on hover and when pressed */
+  --trek-button-brand: #7a4df0;
+
   --vp-button-brand-border: transparent;
   --vp-button-brand-text: var(--vp-c-white);
-  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-bg: var(--trek-button-brand);
   --vp-button-brand-hover-border: transparent;
   --vp-button-brand-hover-text: var(--vp-c-white);
-  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-hover-bg: color-mix(in srgb, var(--trek-button-brand) 88%, black);
   --vp-button-brand-active-border: transparent;
   --vp-button-brand-active-text: var(--vp-c-white);
-  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+  --vp-button-brand-active-bg: color-mix(in srgb, var(--trek-button-brand) 76%, black);
 }
 
 /**
@@ -91,19 +94,44 @@
  * -------------------------------------------------------------------------- */
 
 :root {
+  --trek-green: #63e0a6;
+  --trek-purple: #9b7bff;
+
   --vp-home-hero-name-color: transparent;
-  --vp-home-hero-name-background: -webkit-linear-gradient(
+  /* Darker stops on the light background, the brand colors themselves on the dark one */
+  --vp-home-hero-name-background: linear-gradient(
     120deg,
-    #bd34fe 30%,
-    #41d1ff
+    #1fa971 15%,
+    #7a4df0 100%
   );
 
   --vp-home-hero-image-background-image: linear-gradient(
     -45deg,
-    #bd34fe 50%,
-    #47caff 50%
+    var(--trek-purple) 50%,
+    var(--trek-green) 50%
   );
   --vp-home-hero-image-filter: blur(44px);
+
+  /* Feature icons (docs/index.md): the ink follows the text color, light or dark */
+  --trek-icon-ink: currentColor;
+  --trek-icon-accent: var(--trek-green);
+}
+
+/* Text selection in the brand violet rather than the browser's default blue */
+::selection {
+  background-color: color-mix(in srgb, var(--trek-purple) 30%, transparent);
+}
+
+.dark ::selection {
+  background-color: color-mix(in srgb, var(--trek-purple) 45%, transparent);
+}
+
+.dark {
+  --vp-home-hero-name-background: linear-gradient(
+    120deg,
+    var(--trek-green) 15%,
+    var(--trek-purple) 100%
+  );
 }
 
 @media (min-width: 640px) {

data/docs/changelog.md

@@ -0,0 +1,9 @@
+---
+outline: 2
+---
+
+# Changelog
+
+What changed in each release of Trek, newest first, with upgrade notes when an app needs to act. **Unreleased** lists what's merged but not yet published.
+
+<!--@include: ../CHANGELOG.md-->

data/docs/customize.md

@@ -27,7 +27,21 @@ Replace Trek's favicon with your own:
 Trek's UI components accept options where it matters:
 
 - **`Trek::Form::ActionsComponent`** — pick an `aspect` and add your own `classnames` to restyle form action bars.
-- **`Trek::DialogComponent`** — set the `title` and the buttons of modal dialogs.
+- **`Trek::DialogComponent`** — set the `title` and the buttons of modal dialogs. The confirm dialog wired to `data-turbo-confirm` can also be customized per action from the confirming element's data attributes, with the delete wording as fallback:
+
+```slim
+= render Trek::ButtonComponent.new(
+  text: "Run the prize draw",
+  to: admin_event_draw_path(event), method: :post,
+  data: {
+    turbo_confirm: "Run the prize draw now? Winners will be picked and emails sent.",
+    turbo_confirm_title: "Prize draw",
+    turbo_confirm_button: "Run the draw",
+    turbo_confirm_color: "grass",
+  },
+)
+```
+
 - **`Trek::Form::ContentEditorComponent`** — toggle the `nodes`, `blocks` and `floating` options to slim down the editor where full rich text isn't needed:
 
 ```ruby
@@ -62,9 +76,11 @@ Each scaffolded resource gets its own policy in `app/policies/admin`. Adjust the
 
 Trek's admin supports light, dark and auto themes, selectable per user. The design tokens are based on [Radix colors](https://www.radix-ui.com/colors); override the CSS custom properties in your own stylesheet to adapt the palette.
 
+The auto theme follows the system setting (`prefers-color-scheme`). The `autoDarkTheme` plugin in the generated `postcss.config.js` copies every rule targeting `.dark-theme` into a `@media (prefers-color-scheme: dark)` block, with `.auto-theme` in its place, so dark overrides in your own stylesheets (`.dark-theme { --accent-9: … }`, `.dark-theme .card { … }`) apply to the auto theme too.
+
 ## Dependencies configuration
 
-The installer configures Shrine, Postmark, Sorcery, ActionPolicy, Mobility and friends with sensible defaults — through initializers generated **in your app**. You can edit them at any time:
+The installer configures Shrine, Postmark, ActionPolicy, Mobility and friends with sensible defaults — through initializers generated **in your app**. You can edit them at any time:
 
 - `config/initializers/shrine.rb` — storage backends, upload limits
 - `config/credentials.yml.enc` — Postmark API token (`EDITOR="code --wait" bin/rails credentials:edit`)

data/docs/deploy.md

@@ -20,14 +20,19 @@ Generate the Scalingo files (an `Aptfile` and a `Procfile` with the web process
 rails g trek:install:scalingo
 ```
 
-Then configure the Scalingo app's environment, pinning the buildpack to a release tag:
+Then configure the Scalingo app's environment, pinning the buildpack to a release through its archive:
 
 ```sh
-scalingo --app <app> env-set BUILDPACK_URL=https://github.com/etaminstudio/trek-buildpack#v0.1.0
+scalingo --app <app> env-set BUILDPACK_URL=https://github.com/etaminstudio/trek-buildpack/archive/refs/tags/v0.1.0.tar.gz
 scalingo --app <app> env-set 'DATABASE_URL=$SCALINGO_POSTGRESQL_URL'
 scalingo --app <app> env-set RAILS_MASTER_KEY=$(cat config/master.key)
 ```
 
+> Pin through the archive, not a `#tag` suffix: Scalingo reads `#ref` on `BUILDPACK_URL` as a **branch**, so
+> `…/trek-buildpack#v0.1.0` asks for a branch named `v0.1.0`, which does not exist, and the build fails with
+> `fail to download and extract the custom buildpack: Invalid status code: 404 Not Found`. The `.tar.gz` form above is
+> downloaded as is and stays pinned to the release.
+
 Make sure `config/database.yml` reads `DATABASE_URL` in production — the section `rails new` generates targets a local socket with a password variable instead:
 
 ```yml

data/docs/getting-started.md

@@ -68,7 +68,7 @@ The installer will:
 - create the `Fragment` model and include Trek's concerns
 - create the relevant policies
 - generate and run the relevant migrations
-- set up authentication (Sorcery), authorization (ActionPolicy), uploads (Shrine), emails (Postmark), i18n, linting, CI and more
+- set up authentication (`has_secure_password` with database-backed sessions), authorization (ActionPolicy), uploads (Shrine), emails (Postmark), i18n, linting, CI and more
 
 ### Configure Postmark (optional)
 

data/docs/index.md

@@ -7,7 +7,7 @@ hero:
   text: "Take the easy path"
   tagline: "A modern content management & back-office system for Ruby on Rails"
   image:
-    src: /logo.svg
+    src: /trek-mark.webp
     alt: Trek
   actions:
     - theme: brand
@@ -18,22 +18,22 @@ hero:
       link: /getting-started
 
 features:
-  - icon: 🚀
+  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M16 14A8 8 0 0 1 32 14V38H16ZM21 18A3 3 0 1 0 27 18A3 3 0 1 0 21 18ZM16 26V38H4A12 12 0 0 1 16 26ZM32 26A12 12 0 0 1 44 38H32Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M18 40H30A6 6 0 0 1 18 40Z"/></svg>'
     title: Ready out of the box
     details: One installer sets up authentication, authorization, file uploads, emails, i18n and a polished admin UI — with sensible conventions you can override later.
-  - icon: 📝
+  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M6 6H30V30A12 12 0 0 1 18 42H6ZM12 14H24V18H12ZM12 22H20V26H12Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M34 6H42V32A4 4 0 0 1 34 32Z"/></svg>'
     title: Modern content editing
     details: A Tiptap-based rich text editor, hierarchical pages with versioning and SEO-friendly paths, plus reusable content fragments.
-  - icon: 🛠
+  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M6 18H30V30H42V42H6Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M6 18V6A12 12 0 0 1 18 18Z"/></svg>'
     title: Scaffold-driven development
     details: One command generates the model, admin panel, views, policy, routes and locales for any resource — just like Rails scaffolding, but for your back-office.
-  - icon: 🌍
+  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M22 22H5A17 17 0 0 1 22 5ZM22 26V43A17 17 0 0 1 5 26ZM26 26H43A17 17 0 0 1 26 43Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M26 22V5A17 17 0 0 1 43 22Z"/></svg>'
     title: Multilingual by default
     details: Content and admin UI translations powered by Mobility and i18n-tasks, with optional automatic translation via DeepL.
-  - icon: 🔐
+  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M14 22V16A10 10 0 0 1 34 16V22H28V16A4 4 0 0 0 20 16V22ZM8 22H24V42H16A8 8 0 0 1 8 34Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M24 22H40V34A8 8 0 0 1 32 42H24Z"/></svg>'
     title: Roles & policies built in
-    details: Sorcery authentication and ActionPolicy authorization with admin, editor, user, reader and guest roles, enforced across every panel.
-  - icon: 🧩
+    details: Authentication on Rails' own has_secure_password and ActionPolicy authorization with admin, editor, user, reader and guest roles, enforced across every panel.
+  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M6 6H22V22H6ZM26 22V6A16 16 0 0 1 42 22ZM6 26H22V42A16 16 0 0 1 6 26Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M26 26H42V42H26Z"/></svg>'
     title: Hotwire-native UI
     details: ViewComponents, Stimulus and Turbo under the hood, with light & dark themes, Radix colors and a customizable design system.
 ---

data/docs/reference/components.md

@@ -22,6 +22,21 @@ The main building blocks, all in the `Trek::` namespace:
 | `HeadingComponent` | headings |
 | `GateComponent` | authorization-based visibility gate |
 | `IconComponent` | SVG [icon](/reference/icons) renderer |
+| `Dashboard::SectionComponent` / `Dashboard::TileComponent` | dashboard sections of shortcut tiles |
+
+## Dashboard tiles
+
+A tile is a link by default. With `method:`, it issues another HTTP method through Turbo (as a `data-turbo-method` link), so a tile can create a record in one click rather than open a form; `data:` adds attributes to the link, such as a confirmation:
+
+```ruby
+s.with_tile(
+  text: "New weekly draft",
+  icon: "trek/add",
+  href: [:draft_current_week, :admin, :newsletters],
+  method: :post,
+  data: { turbo_confirm: "Create this week's draft?" }
+)
+```
 
 ## Form components
 

data/docs/reference/concerns/phonable.md

@@ -13,11 +13,37 @@ end
 
 For each declared attribute:
 
-- a validation (`phone: { possible: true, allow_blank: true }`)
+- a validation (`phone: { possible: true, allow_blank: true }`, see [Strictness](#strictness))
 - normalization to E.164 international format on save
 - `formatted_{attr}` — national format (`"01 23 45 67 89"`)
 - `{attr}_with_country_code` — E.164 (`"+33123456789"`)
 
+## Strictness
+
+`strictness:` picks how hard Phonelib looks at a number. It applies to every attribute of the call.
+
+| value | what is accepted |
+| --- | --- |
+| `:possible` (default) | the digits **could** form a number for the country — right length and shape |
+| `:valid` | the digits fall in a range the regulator has actually **assigned** |
+
+```ruby
+class Organization < ApplicationRecord
+  include Trek::Phonable
+  phonable_attributes :phone, strictness: :valid
+end
+```
+
+The gap between the two is worth knowing before leaving the default in place. With
+`Phonelib.default_country = "FR"`, `"0012345678"` is *possible*: under `:possible` it is accepted and
+normalized to `"+12345678"` — the stray leading zero read as an international prefix, the number
+silently rehomed to country code +1, and the original input gone, since normalization happens on
+save. Under `:valid` the same input is rejected and the person is asked to correct it.
+
+`:possible` is the right default for a number stored as a way to reach someone, where a false
+rejection is worse than a number that never gets dialled. Choose `:valid` when the application
+intends to actually call or text what it collects.
+
 ## Usage
 
 ```ruby

data/docs/reference/controllers.md

@@ -26,9 +26,10 @@ end
 
 ### Filters
 
-`Trek::Filters` lets users narrow an index by attribute values. Call `apply_filters!` in your `index` action — it
-rewrites `@objects` from `params[:filters]`, applying a `where(column => value)` per non-blank filter (a value of
-`"nil"` matches `NULL`):
+`Trek::Filters` lets users narrow an index by attribute values. Declare the columns users may filter on via
+`available_filters`, then call `apply_filters!` in your `index` action — it rewrites `@objects` from
+`params[:filters]`, applying a `where(column => value)` per non-blank filter (a value of `"nil"` matches `NULL`). The filters are read
+through strong params (`filter_params`): any other key, and any value that isn't a single value, is ignored:
 
 ```ruby
 module Admin
@@ -44,6 +45,10 @@ module Admin
 
     private
 
+    def available_filters
+      %i[country_code]
+    end
+
     def countries
       City.distinct.pluck(:country_code).index_with { |code| I18n.t("countries.#{code}") }
     end

data/docs/reference/environment-variables.md

@@ -4,6 +4,8 @@
 | --- | --- |
 | `ADMIN_EMAIL` / `ADMIN_PASSWORD` | credentials used by [`trek:admin:user`](/reference/generators/admin-user) |
 | `POSTMARK_API_TOKEN` | Postmark email delivery (auto-injected into credentials by the [installer](/reference/generators/install)) |
+| `APPSIGNAL_PUSH_API_KEY` | AppSignal error tracking and performance monitoring (auto-injected into credentials by the [installer](/reference/generators/install)) |
+| `APPSIGNAL_APP_ENV` | environment name reported to AppSignal (optional, defaults to `RAILS_ENV`) |
 | `DEEPL_AUTH_KEY` | automatic locale translation in the [scaffold generator](/reference/generators/scaffold) |
 | `FEATURE_STORAGE` | `local` (development) or `s3` (production) |
 | `S3_BUCKET`, `S3_REGION`, `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BASE_URL` | S3 storage configuration for [uploads](/reference/uploaders) |

data/docs/reference/forms.md

@@ -13,6 +13,8 @@ Trek ships `Trek::FormBuilder`, an extension of [`ViewComponent::Form`](https://
 
 Each helper renders the matching component from the [`Trek::Form` namespace](/reference/components#form-components).
 
+Standard helpers are styled too: a plain `f.file_field` inside an `f.group` gets its native `::file-selector-button` styled like a narrow `Trek::ButtonComponent` (following the current `data-accent-color`), keeping the browser's built-in "file chosen" feedback with no JS — handy for one-off uploads like a spreadsheet import.
+
 ```slim
 = form_with model: [:admin, @book] do |f|
   = f.group :title

data/docs/reference/generators/install.md

@@ -21,7 +21,7 @@ The installer orchestrates dedicated sub-generators, all under the `trek:install
 
 | Area | What gets set up |
 | --- | --- |
-| Authentication | Sorcery, the `UserSession` form model, login/logout & password reset panels |
+| Authentication | bcrypt and `has_secure_password` on `User`, the `UserSession` model (one per signed-in browser, found through a signed `session_id` cookie), the `Trek::Authentication` controller concern, login/logout & password reset panels |
 | Authorization | ActionPolicy and the base policies |
 | Models | `User`, `Page`, `PagePath`, `PageVersion`, `Fragment`, `MenuNode`, `ExternalLink`, `Current` — with migrations |
 | Attachments | Shrine configuration and the uploaders |
@@ -32,6 +32,8 @@ The installer orchestrates dedicated sub-generators, all under the `trek:install
 | Tooling | esbuild, PostCSS, EditorConfig, Procfiles, Makefile, health check endpoint |
 | Linting | Standard, ESLint, Stylelint, Prettier, Slim Lint, Lefthook git hooks |
 | Security | Brakeman, bundler-audit, ruby_audit |
+| Monitoring | AppSignal error tracking and performance monitoring — `config/appsignal.rb`, the push API key in the credentials, and the `AppsignalContext` concern tagging transactions per area and user |
+| Specs | RSpec, and specs for the models Trek installs (`trek:install:model_specs`): `spec/models/page_spec.rb` and `spec/models/user_spec.rb`, with their test data as [Oaken](https://github.com/kaspth/oaken) seed scripts — defaults in `db/seeds/setup/`, scenarios in `db/seeds/test/cases/` loaded with `seed "cases/…"`. They check Trek's behaviour in your app — slugs and paths, user validations and roles — so a customization that breaks it fails your suite; edit or remove the ones you deliberately change. Trek's own suite runs the same files |
 | N+1 detection | Prosopite (development/test), scanning every request — see [Controllers › N+1 detection](/reference/controllers#n-1-detection) |
 | CI | GitLab CI configuration |
 | Deployment | Scalingo files (`trek:install:scalingo`, run on demand) — see [Deploying to Scalingo](/deploy) |
@@ -41,4 +43,5 @@ The installer orchestrates dedicated sub-generators, all under the `trek:install
 Define these **before** running the installer to have them injected automatically:
 
 - `POSTMARK_API_TOKEN` — injected into the Rails credentials for email delivery
+- `APPSIGNAL_PUSH_API_KEY` — injected into the Rails credentials for error tracking and performance monitoring
 - `DEEPL_AUTH_KEY` — enables automatic locale translation in the [scaffold generator](/reference/generators/scaffold)

data/docs/reference/icons.md

@@ -6,6 +6,6 @@ Trek bundles ~40 SVG icons, rendered with `Trek::IconComponent`:
 render Trek::IconComponent.new(:search)
 ```
 
-Available keys include: `add`, `arrow-bar-left`, `arrow-bar-right`, `bold`, `check`, `chevron-left`, `chevron-right`, `chevron-double`, `close`, `cursor`, `danger`, `download`, `eraser`, `eye`, `grid`, `hr`, `italic`, `layout`, `link`, `list`, `logout`, `paragraph`, `pic`, `profile`, `quotation`, `rating`, `redo`, `undo`, `search`…
+Available keys include: `add`, `arrow-bar-left`, `arrow-bar-right`, `bold`, `check`, `chevron-left`, `chevron-right`, `chevron-double`, `close`, `cursor`, `danger`, `download`, `eraser`, `external`, `eye`, `grid`, `hr`, `italic`, `layout`, `link`, `list`, `logout`, `paragraph`, `pic`, `profile`, `quotation`, `rating`, `redo`, `undo`, `search`…
 
 [MenuNode](/reference/models/menu-node) records can reference an icon via their `icon_key` to display it in the admin sidebar.

data/docs/reference/models/tag.md

@@ -12,7 +12,7 @@ The taxonomy models, installed by the [taxonomies generator](/reference/generato
 | `position` | integer | ordering within the category |
 | `taggings_count` | integer | counter cache |
 
-- `belongs_to :category`, `has_many :taggings`, `has_many :taggables, through: :taggings`
+- `belongs_to :category`, `has_many :taggings`, and `taggables`, the tagged records of any model
 - Scopes: `ordered`, `in_category(key)`, `in_categories(keys)`
 
 ## TagCategory

data/docs/reference/models/user.md

@@ -1,6 +1,6 @@
 # User
 
-The host application's `User` model, into which Trek injects authentication (Sorcery), roles, theme & locale preferences and the invitation workflow.
+The host application's `User` model, into which Trek injects authentication (`has_secure_password` and database-backed sessions), roles, theme & locale preferences and the invitation workflow.
 
 ## Columns added by Trek
 
@@ -10,8 +10,10 @@ The host application's `User` model, into which Trek injects authentication (Sor
 | `role` | integer | enum, default `guest` |
 | `theme` | integer | enum, default `auto` |
 | `locale` | string | admin UI language |
+| `password_digest` | string | `has_secure_password` (bcrypt), required |
+| `last_activity_at` | datetime | updated after each signed-in admin request |
 
-Plus the Sorcery authentication columns (`email`, `crypted_password`, reset tokens…).
+When the app has no `User` model yet, Trek creates the `users` table with its `email` column. Signed-in browsers are `UserSession` records (`user_agent`, `ip_address`) in a `user_sessions` table, found through a signed `session_id` cookie. Password reset (15 minutes) and invitation (1 week) links carry tokens from `generates_token_for`, so no column stores them.
 
 ## Roles
 
@@ -50,8 +52,8 @@ User.create(email: "new@example.com", role: :editor, send_invite: true)
 
 `Trek::Users::Validations` enforces:
 
-- `email` — presence, uniqueness, valid format
-- `password` — minimum 8 characters (on creation or password change)
+- `email` — stored stripped and in lower case (lookups too, so sign-in and password resets ignore case), present, unique whatever its case, and well-formed by [`email_validator`](https://github.com/K-and-R/email_validator)'s strict mode (no consecutive or leading/trailing dots, a domain with a TLD)
+- `password` — when one is assigned: at least 8 characters, and not spaces only. A blank password is ignored by `has_secure_password` (the current one is kept); the password reset form refuses it
 
 ## Scopes
 

data/docs/reference/uploaders.md

@@ -5,15 +5,40 @@ File uploads are handled by [Shrine](https://shrinerb.com), with Uppy on the fro
 - `ImageUploader` — base image uploader
 - `RecordImageUploader` — attach an image to any record: `include RecordImageUploader::Attachment(:image)`
 - `ModelImageUploader` — model-level image uploader (used by content editor images)
+- `AudioUploader` — sounds for `f.sound_field` (MP3, AAC/M4A, Ogg, WAV, WebM, FLAC): `include AudioUploader::Attachment(:audio)` on a record with an `audio_data` jsonb column
 
 ## Storage
 
 Configured per environment in the generated Shrine initializer (`config/initializers/shrine.rb`):
 
-| Environment | Storage |
-| --- | --- |
-| production | S3 (via the [`S3_*` ENV variables](/reference/environment-variables)) |
-| development | local filesystem (`public/uploads/`) |
-| test | in-memory |
+| Environment | Storage                                                               |
+| ----------- | --------------------------------------------------------------------- |
+| production  | S3 (via the [`S3_*` ENV variables](/reference/environment-variables)) |
+| development | local filesystem (`public/uploads/`)                                  |
+| test        | in-memory                                                             |
 
-Image processing uses libvips, blurhash placeholders are generated for progressive loading, and direct uploads go through the Shrine `upload_endpoint` (20 MB max).
+Image processing uses libvips, blurhash placeholders are generated for progressive loading, and direct uploads go through the Shrine `upload_endpoint`: `POST /admin/upload/image` (20 MB max) and `POST /admin/upload/audio` (200 MB max), handled by the generated `Admin::UploadsController`. The endpoint only checks the size; each uploader validates the file type when it is attached to a record.
+
+## Attachments and records reloaded mid-save
+
+`RecordImageUploader` loads `Trek::SavedAttachmentsReload` on top of Shrine's `activerecord` plugin:
+
+```ruby
+class RecordImageUploader < ImageUploader
+  plugin :activerecord
+  plugin Trek::SavedAttachmentsReload
+end
+```
+
+Shrine resets every attacher when a record is reloaded, which is right for an explicit reload but loses a pending attachment when something reloads the record _during_ the save — closure_tree does exactly that in its `after_save` callback when it reorders the siblings of a numerically ordered tree, as the generated `Page` is. The file would then never be promoted out of the `cache` storage. The plugin keeps, across such a reload, the attachers whose file was saved with the record; an attachment assigned but not saved is still discarded.
+
+## Files left in the cache storage
+
+An uploaded file first lands in the temporary `cache` storage, and is promoted to the permanent `store` after the record is committed. A record whose promotion was skipped keeps pointing to the cache, and its file breaks as soon as the cache is cleaned up. To find those records, for every model and attachment, and promote the ones whose file still exists:
+
+```bash
+DRY_RUN=1 bin/rails trek:attachments:promote_cached # only lists them
+bin/rails trek:attachments:promote_cached
+```
+
+Each line gives the status (`promoted`, `promotable` on a dry run, `missing` when the cached file is gone, `changed` when the record changed meanwhile), the record and attachment, and the file id. Missing files have to be uploaded again.

data/docs/what-is-trek.md

@@ -10,7 +10,7 @@ Trek ships as a Rails engine (a gem plus an NPM package) that integrates into yo
 - **Pages** — hierarchical, translatable pages with version history, SEO metadata and stable, redirect-aware URL paths.
 - **Fragments** — reusable chunks of content (a footer text, a hero tagline…) editable from the admin and usable anywhere in your views.
 - **A rich text editor** — based on [Tiptap](https://tiptap.dev), with image uploads (Uppy), link insertion and content stored as structured ProseMirror JSON.
-- **Authentication & authorization** — [Sorcery](https://github.com/Sorcery/sorcery)-based sign in, password resets, invitations, and [ActionPolicy](https://actionpolicy.evilmartians.io) policies with `admin`, `editor`, `user`, `reader` and `guest` roles.
+- **Authentication & authorization** — sign in built on Rails' [`has_secure_password`](https://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html) with database-backed sessions, password resets, invitations, and [ActionPolicy](https://actionpolicy.evilmartians.io) policies with `admin`, `editor`, `user`, `reader` and `guest` roles.
 - **Internationalization** — content translations with [Mobility](https://github.com/shioyama/mobility), locale management with [i18n-tasks](https://github.com/glebm/i18n-tasks), and optional automatic translation through DeepL.
 - **File uploads** — [Shrine](https://shrinerb.com)-backed attachments with S3 or local storage, image processing via libvips, and blurhash placeholders.
 - **Generators** — an installer that sets up everything above, and a scaffold generator that creates a full admin panel for any model in one command.

data/lib/generators/trek/install/admin/routes_generator.rb

@@ -14,7 +14,13 @@ module Trek
           end
 
           def upload_image
-            route 'post "upload", to: "uploads#image", namespace: :admin'
+            # The endpoint `Trek::Form::ImageFieldComponent` uploads to: /admin/upload/image
+            route 'post "upload/image", to: "uploads#image"', namespace: :admin
+          end
+
+          def upload_audio
+            # The endpoint `Trek::Form::SoundFieldComponent` uploads to: /admin/upload/audio
+            route 'post "upload/audio", to: "uploads#audio"', namespace: :admin
           end
 
           def lookbook