trek 0.1.23 → 0.1.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c441a015bd63b8e650c1f39c225b2a40f6a6beebeff6db95d295a84a2c22eae2
-  data.tar.gz: 2f7543789a5cb718fdb9a69e6c6f4b9143164a525ea7d5620c5b8816e9d35e01
+  metadata.gz: 71867750da0cef4ae1928a4245e69742d7d32c6614c54da4d107f992da5e0e23
+  data.tar.gz: 71cb0d0b2ce4098030705245aaf92b50eefec11b4491bc0180e145eeb2f6a8e3
 SHA512:
-  metadata.gz: 1086f69da18c67aa88915c9556c511bca3f30eb981d768078d7f962f8ebf340769be08b0b131f8e873544cd4a152b715a28d7baacabaf19993a685e1c090083c
-  data.tar.gz: 8507af27451b4ed7445fe1748e00a246392631d20c2804f213826356fa898a8b29aaf77a716a64233470022e7817209fbd103fbaa98b8482335f59b1279a0f33
+  metadata.gz: 0e3a672cb3ebf8abee38d436832d92d3cc5c8bd5502f37344bda47275d4bd090a7326920cd823ed84e30990cd9feb453dddc2e62bfc1d43967de230498fd8287
+  data.tar.gz: aa4c5e9ee652804fc0361b8ac9e459863f67ff42441484e26fd8387312d8ba70517809b04d81fb68d9b9cab0ea6e6c7a27b943486c80c94b1544678841806fab

data/AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository. Keep it accurate — update it when commands or conventions change.
+
+## What is Trek
+
+Trek is a customizable CMS for Ruby on Rails, shipped as a **Ruby gem** (`trek`) plus a companion **NPM package** (`@etaminstudio/trek`). It's a Rails **engine** (`lib/trek/engine.rb`) that installs a back-office/admin into a host app. Installation and features are driven by Rails generators (`rails g trek:install`, `trek:scaffold`, `trek:admin:user`, …). Authored by Etamin Studio. Private gem hosted on self-hosted GitLab (`git.etaminstud.io`), not public RubyGems.
+
+## Tech stack
+
+- **Ruby** `>= 3.1` (RuboCop targets 3.4) · **Rails** `>= 6.0, < 8.2` (lockfile 8.1.3; host apps need 7.0+)
+- **Node** 22.21.1 (`.node-version`) · **Yarn** 3.8.0 (berry) · **PostgreSQL** 12+ · **libvips** for images
+- Backend: `action_policy`, `closure_tree`, `acts_as_list`, `mobility` + `i18n-tasks`, `shrine` (+ blurhash/image_processing/aws-sdk-s3), `view_component` + `slim-rails` + `lookbook`, `kaminari`, `deepl-rb`
+- Frontend: **esbuild** (`esbuild.config.js`) + **PostCSS** (`postcss.config.js`); Stimulus/Turbo, TipTap, Uppy, Tom Select, SortableJS
+- Tests: **RSpec** (`rspec-rails`, capybara, simplecov) · Docs: **VitePress** (`docs/`)
+
+## Commands
+
+```bash
+bin/setup                 # bundle install + yarn install (dev setup)
+bin/console               # IRB with trek loaded
+rake                      # default: spec + rubocop
+rake spec                 # run tests (or: bundle exec rspec)
+make release              # bump version (version.rb + package.json), stamp CHANGELOG, tag, push gem + npm
+yarn docs:dev             # VitePress docs locally
+```
+
+Linters (also run automatically via lefthook on pre-commit):
+
+```bash
+bundle exec rubocop
+bundle exec slim-lint "app/**/*.slim"
+yarn eslint "app/**/*.js"
+yarn stylelint "app/**/*.css"
+yarn prettier --check "{app,config,lib,spec}/**/*.{css,js,json,md,yml}"
+```
+
+Security: `bundle exec brakeman` · `bundle exec bundle-audit check --update`
+
+## Structure
+
+- `app/` — engine code, namespaced under `trek/`: `components/` (ViewComponents), `controllers/`, `forms/`, `models/`, `policies/` (ActionPolicy), `uploaders/` (Shrine), `views/`, `javascript/` (Stimulus)
+- `lib/generators/trek/` — the heart of the gem: `install/` (~30 generators), `scaffold_generator.rb`, `admin/`, `templates/`
+- `lib/trek/` — `engine.rb`, `version.rb`, `i18n_keys_resolver.rb`, `typography_formatter.rb`
+- `config/locales/` — `trek.en.yml`, `trek.fr.yml`
+- `spec/` — RSpec suite · `docs/` — VitePress site
+
+## Conventions
+
+- **Ruby**: rubocop-rails-omakase + rubocop-rspec (`.rubocop.yml`) — double-quoted strings, line length 120, target 3.4
+- **Slim** linted via slim_lint; **JS/CSS** via ESLint + Stylelint + Prettier 2.8.8
+- **i18n**: keep English + French locales in sync (`config/locales/trek.*.yml`); DeepL auto-translation via `DEEPL_AUTH_KEY`
+- **Versioning**: version lives in both `lib/trek/version.rb` and `package.json` — keep in sync via `make release`
+- **CHANGELOG.md**: Keep-a-Changelog format. **Every MR must add an `[Unreleased]` entry.** When the change requires action in the host app on upgrade, add an "Upgrade note" describing what to do. When the change lets host apps remove or simplify existing patches or custom implementations, mention that too (e.g. "you can now drop your custom …").
+- **CI**: GitLab CI (`.gitlab-ci.yml`), stages build → lint → security → test → deploy; docs deploy to Netlify; deps via Renovate

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.1.25] - 2026-07-01
+
+### Added
+
+- Invitation and password-reset emails now tell the recipient when the link expires. Invitations get their own `:invite` token purpose (1 week) — distinct from the 15-minute `:password_reset` token — and the generated `Admin::UserPasswordResetsController` accepts either purpose, so the shared "set your password" form works from both emails. Each mailer reads its window from the model's token definition (`User.token_definitions[:purpose].expires_in`) rather than a hardcoded constant. **Upgrade note:** add `generates_token_for :invite, expires_in: 1.week do password_salt&.last(10) end` to your `User`; have `AdminMailer#invite` issue an `:invite` token (and `include ActionView::Helpers::DateHelper`); and update `Admin::UserPasswordResetsController#set_user_by_token` to try both purposes, e.g. `User.privileged.find_by_token_for(:invite, @token) || User.privileged.find_by_token_for!(:password_reset, @token)`.
+- `trek:install` now generates an `AGENTS.md` (onboarding guidance for AI coding agents: commands, conventions, and a "read the changelog on every upgrade" checklist) plus a `CLAUDE.md` that imports it via `See @AGENTS.md`, so Claude Code and other agents share one source of truth. **Upgrade note:** existing apps can add both files by running `rails g trek:install:agents`.
+- `Trek::Filters` controller concern: filter the index by `params[:filters]` (attribute equality via `where`). Call `apply_filters!` in your `index`.
+- Pedagogical `NotAppliedError` guard on `Trek::Filters` and `Trek::Scopes`: raises (outside production) when the concern is included but `index` never calls `apply_filters!` / `apply_scopes!`.
+- `trek:install:scalingo` now adds `libjemalloc2` to the generated `Aptfile`, enabling the jemalloc allocator to reduce Ruby memory usage on Scalingo.
+
+### Fixed
+
+- The generated dashboard's "search a user" tile now links to the users index (`href: %i[admin users]`) instead of a dead `#`, and gates on `allowed_to: allowed_to?(:index?, User)` so roles that can't reach user management no longer see it (matching the sidebar's Users entry). **Upgrade note:** existing apps can set `href: %i[admin users]` and add `allowed_to: allowed_to?(:index?, User)` on that tile in `app/views/admin/dashboards/index.html.slim`.
+- `trek:install` now points Action Mailer at the same host as the routes' `default_url_options` (driven by `DEFAULT_HOSTNAME`) in the generated `config/initializers/host.rb`, in production only (development and test keep the host from their environment files). Previously the mailer kept Rails' `example.com` default, so invitation and password-reset email links pointed to `https://example.com/...` in production. **Upgrade note:** existing apps can add `ActionMailer::Base.default_url_options = Rails.application.routes.default_url_options if Rails.env.production?` to their `config/initializers/host.rb` (and drop any hardcoded `config.action_mailer.default_url_options` host).
+- The generated `Admin::UsersController` (`trek:install`) seeds a random password in `create_hook`, so users created via the admin form — which never collects one — satisfy `has_secure_password` and the non-null `password_digest` column. Invitees set their real password via the invite email; others via password reset. (Password seeding lives in the controller rather than `Trek::Users::Invitable` so it also covers users created without an invite.) **Upgrade note:** ensure your `Admin::UsersController#create_hook` seeds a password when blank: `@object.password = SecureRandom.alphanumeric(24) if @object.password.blank?`.
+- `trek:install:ci` now sets `POSTGRES_DB` in `.gitlab-ci.yml` from the application name (e.g. `myapp_test`) instead of the hardcoded `project_test`.
+- `trek:install:yarn` now rewrites `bin/setup`'s `yarn install --check-files` to `yarn install`, since `--check-files` is not a valid flag under Yarn berry and was breaking `bin/setup` (and therefore CI).
+- `trek:install` now adds a `!/.env.example` exception to `.gitignore` so the generated `.env.example` template stays tracked (Rails ignores all `/.env*` files by default).
+- `trek:install:postmark` now matches the production.rb SMTP comment with or without the `bin/` prefix, so the Postmark config is injected on Rails 8.0 as well as 8.1 (previously the injection silently did nothing when the anchor did not match).
+
 ## [0.0.1] - 2023-01-24
 
 - Initial release

data/CLAUDE.md

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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    trek (0.1.23)
+    trek (0.1.25)
       action_policy (~> 0.6)
       actioncable
       acts_as_list (~> 1.1)
@@ -158,10 +158,10 @@ GEM
       activerecord (>= 7.2.0)
       with_advisory_lock (>= 7.0.0)
       zeitwerk (~> 2.7)
-    concurrent-ruby (1.3.6)
+    concurrent-ruby (1.3.7)
     connection_pool (3.0.2)
     content_disposition (1.0.0)
-    crass (1.0.6)
+    crass (1.0.7)
     css_parser (3.0.0)
       addressable
       ssrf_filter (~> 1.5)
@@ -298,9 +298,9 @@ GEM
     net-smtp (0.5.1)
       net-protocol
     nio4r (2.7.5)
-    nokogiri (1.19.3-arm64-darwin)
+    nokogiri (1.19.4-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.3-x86_64-darwin)
+    nokogiri (1.19.4-x86_64-darwin)
       racc (~> 1.4)
     parallel (1.27.0)
     parser (3.3.10.0)
@@ -516,7 +516,7 @@ GEM
       zeitwerk (>= 2.7)
     xpath (3.2.0)
       nokogiri (~> 1.8)
-    yard (0.9.43)
+    yard (0.9.44)
     zeitwerk (2.7.5)
 
 PLATFORMS

data/Makefile

@@ -5,6 +5,7 @@ release:
 	if [ -z "$$version" ]; then echo "Version cannot be empty"; exit 1; fi; \
 	sed -i '' "s/VERSION = \".*\"/VERSION = \"$$version\"/" lib/trek/version.rb; \
 	sed -i '' "s/\"version\": \".*\"/\"version\": \"$$version\"/" package.json; \
+	awk -v v="$$version" -v d="$$(date +%F)" '!done && /^## \[Unreleased\]/ {print; print ""; print "## [" v "] - " d; done=1; next} {print}' CHANGELOG.md > CHANGELOG.md.tmp && mv CHANGELOG.md.tmp CHANGELOG.md; \
 	bundle; \
 	git add -A; \
 	git commit -m "Version $$version"; \

data/app/components/trek/form/actions_component/actions_component.css

@@ -7,9 +7,9 @@
   display: flex;
   max-width: 120rem;
   padding: 4rem 0;
-  position: fixed;
+  position: sticky;
   width: 100%;
-  z-index: 1;
+  z-index: 2;
 }
 
 .buttons {

data/app/controllers/concerns/trek/authentication.rb

@@ -11,7 +11,7 @@ module Trek
     private
 
     def current_attribute_user
-      current_user
+      Current.user
     end
 
     def not_authenticated

data/app/controllers/concerns/trek/filters.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Trek
+  module Filters
+    extend ActiveSupport::Concern
+
+    # Raised when a controller includes Trek::Filters but its #index never
+    # calls apply_filters! — to teach the developer to wire up filtering.
+    class NotAppliedError < StandardError
+      DEFAULT_MESSAGE = <<~MSG.squish
+        Trek::Filters is included but #index never called `apply_filters!`.
+        Add `apply_filters!` to your index action (or `@objects = apply_filters(@objects, params[:filters])`).
+        See https://trek.etamin.studio/reference/controllers#mixins
+      MSG
+
+      def initialize(message = DEFAULT_MESSAGE) = super
+    end
+
+    included do
+      # rubocop:disable Rails/LexicallyScopedActionFilter
+      after_action :ensure_filters_applied, only: :index
+      # rubocop:enable Rails/LexicallyScopedActionFilter
+    end
+
+    def apply_filters(scope, filters)
+      return scope if filters.blank?
+
+      filters.each do |filter, value|
+        next if value.blank?
+        value = nil if value == "nil"
+
+        scope = scope.where(filter => value)
+      end
+
+      scope
+    end
+
+    def apply_filters!
+      @filters_applied = true
+      @objects = apply_filters(@objects, params[:filters])
+    end
+
+    private
+
+    def ensure_filters_applied
+      return if @filters_applied
+      return if Rails.env.production?
+
+      raise NotAppliedError
+    end
+  end
+end

data/app/controllers/concerns/trek/localization.rb

@@ -22,7 +22,7 @@ module Trek
     end
 
     def locale_from_current_user
-      current_user&.locale
+      Current.user&.locale
     end
 
     def locale_from_headers

data/app/controllers/concerns/trek/scopes.rb

@@ -4,6 +4,18 @@ module Trek
   module Scopes
     extend ActiveSupport::Concern
 
+    # Raised when a controller includes Trek::Scopes but its #index never
+    # calls apply_scopes! — to teach the developer to wire up scoping.
+    class NotAppliedError < StandardError
+      DEFAULT_MESSAGE = <<~MSG.squish
+        Trek::Scopes is included but #index never called `apply_scopes!`.
+        Add `apply_scopes!` to your index action.
+        See https://trek.etamin.studio/reference/controllers#mixins
+      MSG
+
+      def initialize(message = DEFAULT_MESSAGE) = super
+    end
+
     def apply_scopes(scope, filters)
       return scope if filters.blank?
 
@@ -17,12 +29,17 @@ module Trek
     end
 
     def apply_scopes!
+      @scopes_applied = true
       @unscoped_objects = @objects
       @objects = apply_scopes(@objects, params[:scopes])
       scope_counts
     end
 
     included do
+      # rubocop:disable Rails/LexicallyScopedActionFilter
+      after_action :ensure_scopes_applied, only: :index
+      # rubocop:enable Rails/LexicallyScopedActionFilter
+
       helper_method :available_scopes
       helper_method :scope_params
       helper_method :unscoped_objects
@@ -51,5 +68,12 @@ module Trek
     def scope_params
       params[:scopes]&.permit(*available_scopes)
     end
+
+    private def ensure_scopes_applied
+      return if @scopes_applied
+      return if Rails.env.production?
+
+      raise NotAppliedError
+    end
   end
 end

data/app/helpers/trek/theme_helper.rb

@@ -1,8 +1,8 @@
 module Trek
   module ThemeHelper
     def class_for_theme
-      if logged_in?
-        "#{current_user.theme}-theme"
+      if authenticated?
+        "#{Current.user.theme}-theme"
       else
         "light-theme"
       end

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

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 module Trek
   module Users
     module Invitable
       extend ActiveSupport::Concern
 
       included do
-        attr_accessor :send_invite
+        attribute :send_invite, :boolean
 
         after_create :send_invite_email, if: :send_invite
       end
@@ -12,8 +14,7 @@ module Trek
       private
 
       def send_invite_email
-        generate_reset_password_token!
-        UserMailer.invite_email(self).deliver_later
+        AdminMailer.invite(self).deliver_later
       end
     end
   end

data/config/locales/trek.en.yml

@@ -149,17 +149,20 @@ en:
           success: Action added
         form:
           title: Action
+    passwords_mailer:
+      reset:
+        subject: Reset your password
     search_component:
       search: Search
       search_user: Search for a user with an email
     seo: SEO
     settings: Settings
     user_password_resets:
+      not_found: Invalid or expired password reset link.
       create:
         success: A password recovery email has been sent to you
       new:
         remembered_password: I found my password!
-        title: Reset password
       update:
         success: Your password has been changed
     user_sessions:
@@ -170,7 +173,6 @@ en:
         success: You are now logged out
       new:
         forgot_password: I forgot my password
-        title: Log in
     users:
       create:
         success: User added
@@ -248,8 +250,9 @@ en:
       auto: auto
       dark: dark
       light: light
-  user_mailer:
-    invite_email:
+  admin_mailer:
+    invite:
       subject: Your invitation
-    reset_password_email:
-      subject: Reset your password
+  notices:
+    authentication_needed: Please log in
+    rate_limited: Too many attempts, please try again later

data/config/locales/trek.fr.yml

@@ -143,6 +143,9 @@ fr:
           success: Action ajoutée
         form:
           title: Action
+    passwords_mailer:
+      reset:
+        subject: Nouveau mot de passe
     search_component:
       search: Rechercher
       search_user: Rechercher un utilisateur par e-mail
@@ -157,11 +160,11 @@ fr:
     seo: SEO
     settings: Paramètres
     user_password_resets:
+      not_found: Lien de réinitialisation de mot de passe invalide ou expiré.
       create:
         success: Un e-mail de récupération de mot de passe vous a été envoyé
       new:
         remembered_password: J'ai retrouvé mon mot de passe !
-        title: Mot de passe oublié
       update:
         success: Votre mot de passe a été modifié
     user_sessions:
@@ -172,7 +175,6 @@ fr:
         success: Vous êtes maintenant déconnecté·e
       new:
         forgot_password: J'ai oublié mon mot de passe
-        title: Connexion
     users:
       create:
         success: Utilisateur ajouté
@@ -250,8 +252,9 @@ fr:
       auto: auto
       dark: sombre
       light: clair
-  user_mailer:
-    invite_email:
+  admin_mailer:
+    invite:
       subject: Votre invitation
-    reset_password_email:
-      subject: Nouveau mot de passe
+  notices:
+    authentication_needed: Veuillez vous connecter
+    rate_limited: Trop de tentatives, veuillez réessayer plus tard

data/docs/.vitepress/config.mjs

@@ -1,7 +1,12 @@
 import { defineConfig } from 'vitepress'
+import llmstxt from 'vitepress-plugin-llms'
+
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
+  vite: {
+    plugins: [llmstxt()],
+  },
   title: "Trek",
   description: "A modern content management & back-office system for Ruby on Rails",
   lang: 'en-US',

data/docs/reference/controllers.md

@@ -21,3 +21,75 @@ end
 
 - `include Trek::Pagination` — paginates the index with Kaminari
 - `include Trek::Search` — filters the index by `params[:search]` when the model is [Searchable](/reference/concerns/searchable)
+- `include Trek::Filters` — filters the index by attribute equality (`where(column => value)`) from `params[:filters]`
+- `include Trek::Scopes` — filters the index by **named scopes** from `params[:scopes]`
+
+### 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`):
+
+```ruby
+module Admin
+  class CitiesController < Trek::ResourceController
+    include Trek::Filters
+
+    helper_method :countries
+
+    def index
+      super
+      apply_filters!
+    end
+
+    private
+
+    def countries
+      City.distinct.pluck(:country_code).index_with { |code| I18n.t("countries.#{code}") }
+    end
+  end
+end
+```
+
+Render the choices with a [`ButtonGroupComponent`](/reference/components), each button linking back to the index
+with the chosen filter:
+
+```slim
+= render Trek::ButtonGroupComponent.new do |g|
+  - g.with_button text: t("admin.actions.all"), \
+      href: [:admin, model], active: params.dig(:filters, :country_code).nil?
+  - countries.each do |code, name|
+    - g.with_button text: name, \
+        href: polymorphic_path([:admin, model], filters: { country_code: code }), \
+        active: code == params.dig(:filters, :country_code)
+```
+
+> If a controller includes `Trek::Filters` but its `index` never calls `apply_filters!`, an
+> `after_action` raises `Trek::Filters::NotAppliedError` (outside production) to flag the missing wiring.
+
+### Scopes
+
+`Trek::Scopes` filters by **named model scopes** rather than raw attributes. Declare the allowed scopes via
+`available_scopes`, then call `apply_scopes!` in your `index`. It also exposes `scope_counts` and
+`unscoped_objects` helpers (the per-scope match counts and the pre-scope collection) for building scope tabs:
+
+```ruby
+module Admin
+  class ArticlesController < Trek::ResourceController
+    include Trek::Scopes
+
+    def index
+      super
+      apply_scopes!
+    end
+
+    private
+
+    def available_scopes
+      %i[published draft]
+    end
+  end
+end
+```
+
+Like `Trek::Filters`, forgetting to call `apply_scopes!` raises `Trek::Scopes::NotAppliedError` outside production.

data/lib/generators/trek/helpers.rb

@@ -63,6 +63,21 @@ module Trek
       def install_npm_dependencies(dependencies, dev: false)
         run "yarn add #{dependencies.map { |name, version| "#{name}@#{version}" }.join(" ")} #{dev ? "--dev" : ""}", abort_on_failure: true
       end
+
+      # Run "bundle install" outside the parent process's bundler environment.
+      # The generators run under `bundle exec`, so the child `bundle` process
+      # would otherwise auto-load `bundler/setup` against the Gemfile we just
+      # modified and raise GemNotFound for the not-yet-installed gem.
+      #
+      # We use with_original_env (not with_unbundled_env): both restore the
+      # pre-`bundle exec` environment, but with_unbundled_env also scrubs every
+      # BUNDLE_* var, which drops the credentials (e.g. BUNDLE_GIT__ETAMINSTUD__IO)
+      # needed to fetch trek itself from its private git source.
+      def bundle_install
+        Bundler.with_original_env do
+          run "bundle install --quiet", abort_on_failure: true
+        end
+      end
     end
   end
 end

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

@@ -12,10 +12,6 @@ module Trek
 
           source_root File.expand_path("../../templates", __dir__)
 
-          def add_routes
-            route "resources :user_password_resets, only: %i[new create edit update]", namespace: :admin
-          end
-
           def copy_controller
             template "controllers/admin/user_password_resets_controller.rb",
               "app/controllers/admin/user_password_resets_controller.rb"

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

@@ -12,13 +12,6 @@ module Trek
 
           source_root File.expand_path("../../templates", __dir__)
 
-          def add_routes
-            route "resources :user_sessions, only: %i[new create destroy]", namespace: :admin
-
-            route 'get :login, to: "user_sessions#new", as: :login', namespace: :admin
-            route 'delete :logout, to: "user_sessions#destroy", as: :logout', namespace: :admin
-          end
-
           def copy_controller
             template "controllers/admin/user_sessions_controller.rb",
               "app/controllers/admin/user_sessions_controller.rb"

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

@@ -13,7 +13,11 @@ module Trek
           source_root File.expand_path("../../templates", __dir__)
 
           def add_routes
-            route "resources :users", namespace: :admin
+            route <<~RUBY, namespace: :admin
+              resources :users do
+                patch :theme, on: :collection
+              end
+            RUBY
           end
 
           def copy_controller

data/lib/generators/trek/install/agents_generator.rb

@@ -0,0 +1,26 @@
+require "rails/generators/actions"
+require "generators/trek/helpers"
+
+module Trek
+  module Generators
+    module Install
+      class AgentsGenerator < Rails::Generators::Base
+        include Trek::Generators::Helpers
+
+        desc "Create AGENTS.md and CLAUDE.md guidance files for AI coding agents."
+
+        source_root File.expand_path("../templates", __dir__)
+
+        def create_agents_md
+          copy_file "AGENTS.md", "AGENTS.md"
+        end
+
+        # CLAUDE.md imports AGENTS.md so Claude Code (which reads CLAUDE.md) and
+        # other agents (which read AGENTS.md) share a single source of truth.
+        def create_claude_md
+          create_file "CLAUDE.md", "See @AGENTS.md\n"
+        end
+      end
+    end
+  end
+end

data/lib/generators/trek/install/attachments_generator.rb

@@ -13,13 +13,15 @@ module Trek
         source_root File.expand_path("../templates", __dir__)
 
         def add_gem
+          install_needed = %w[aws-sdk-s3 blurhash fastimage image_processing shrine shrine-blurhash].any? { |name| !in_gemfile?(name) }
+
           gem "aws-sdk-s3", "~> 1.117" unless in_gemfile?("aws-sdk-s3")
           gem "blurhash", "~> 0.1.7" unless in_gemfile?("blurhash")
           gem "fastimage", "~> 2.2" unless in_gemfile?("fastimage")
           gem "image_processing", "~> 1.8" unless in_gemfile?("image_processing")
           gem "shrine", "~> 3.0" unless in_gemfile?("shrine")
           gem "shrine-blurhash", "~> 0.2.0" unless in_gemfile?("shrine-blurhash")
-          run "bundle install --quiet", abort_on_failure: true
+          bundle_install if install_needed
         end
 
         def add_initializer