renuo · cb341 · May 20, 2026
diff --git a/README.md b/README.md
@@ -5,46 +5,38 @@ We are a [Rails company](https://rubyonrails.org/foundation), so the most value
 will be found in the parts concerning Rails. But anyways you'll also find a lot about the
 inner workings of Renuo.
 
-* [Ruby on Rails – Application Setup Guide](./ruby_on_rails/README.md)
+**You are always welcome to challenge the guide and improve it with a Pull Request.**
+
+**:exclamation: Do not blindly follow this guide, always think about what you are doing and why.
+If you think something is wrong or simply outdated, improve this guide with a Pull Request.**
 
-## Some Notes on the Side
+## How to Use This Guide
 
-If you are reading this document, it means that you have to setup a new application.
-A new project started and it's now time to set everything up so that **everyone**,
-in your team, **can start working on it**.
+The guide is structured as a linear walkthrough. Follow it from top to bottom when setting up a new project.
 
-This document will try to be as minimalist as possible and provide you with all the steps to set up the application as
-fast as possible. There are things, in Renuo projects, which are mandatory, other that are suggested.
-This guide is the result of more than ten years of experience, so this means three things: it's very robust, very opinionated, and possibly very outdated.
+1. **Before You Start** — Read [Naming Conventions](naming_conventions.md), [GitFlow](gitflow.md), and [Security](security.md) to understand the ground rules.
+2. **Rails Application Setup** — Follow the [step-by-step setup](ruby_on_rails/README.md) to create, deploy, and configure your app.
+3. **Guides & Recipes** — Pick the ones you need (emails, authentication, payment, etc.).
+4. **Reference** — Use the [Checklist](checklist.md) to verify you haven't missed anything, and the [Go Live!](go_live.md) page when you're ready to launch.
 
-**You are always welcome to challenge the guide and improve it with a Pull Request.**
+## What Needs to Be Ready
 
-The basic things that need to be ready before the team can start working on a project are:
+Before the team can start working on a project, you need:
 
 * An existing *git* repository containing the project
-* Two branches: *main* and *develop*
+* Two branches: *main* and *develop* (or just *main* for internal projects)
 * A README with essential information about the application
 * Convenience-scripts: `bin/setup`, `bin/check`, `bin/fastcheck`, `bin/run`
 * One running, green test
-* Continuous integration (*CI*) ready, running and green for both branches
-* Continuous deployment (*CD*) ready and running for both branches
-* The application deployed for both branches
-
-As an appendix, you'll find a [checklist](checklist.md) you can use to follow the guide.
-
-**:exclamation: Do not blindly follow this guide, always think about what you are doing and why.
-If you think something is wrong or simply outdated, improve this guide with a Pull Request.**
-
-We want you to know exactly the reason behind each single step of this guide.
-
-Thank you for your work and have fun! :tada:
+* Continuous integration (*CI*) ready, running and green for all branches
+* Continuous deployment (*CD*) ready and running for all branches
+* The application deployed for all branches
 
 ## Serving the Documentation Locally
 
-To view this documentation on your machine, run the following commands:
+To view this documentation on your machine, run the following command:
 
 ```sh
-brew install mdbook
 mdbook serve
 ```
 

diff --git a/SUMMARY.md b/SUMMARY.md
@@ -2,65 +2,69 @@
 
 [Overview](README.md)
 
-# General
+# Before You Start
 
-- [Create a Git Repository](create_git_repository.md)
-- [GitFlow](gitflow.md)
-- [Go Live!](go_live.md)
 - [Naming Conventions](naming_conventions.md)
+- [GitFlow](gitflow.md)
 - [Security](security.md)
-- [Project Checklist](checklist.md)
 
-# Rails Application Setup Guide
+# Rails Application Setup
 
-- [Getting started](ruby_on_rails/README.md)
+- [Getting Started](ruby_on_rails/README.md)
 
-- [Setup]()
+- [Step 1: Create the App]()
     - [Initialise the Rails App](ruby_on_rails/app_initialisation.md)
+    - [Create a GitHub Repository](create_github_repository.md)
     - [Push to Git Repository](ruby_on_rails/first_git_push.md)
     - [Initialise Gitflow](ruby_on_rails/initialise_gitflow.md)
     - [Configure Git Repository](configure_git_repository.md)
-    - [Create an Application Server (Heroku)](ruby_on_rails/create_application_server_heroku.md)
+- [Step 2: Deploy the App]()
     - [Create an Application Server (Deploio)](ruby_on_rails/create_application_server_deploio.md)
+    - [Create an Application Server (Heroku)](ruby_on_rails/create_application_server_heroku.md)
     - [Configure the CI/CD](ruby_on_rails/configure_ci.md)
-- [Tools]()
+- [Step 3: Quality Tools]()
     - [RSpec](ruby_on_rails/rspec.md)
     - [Linting and automatic checks](ruby_on_rails/linting_and_automatic_check.md)
     - [Gems and libraries](ruby_on_rails/suggested_libraries.md)
     - [Cloudflare](ruby_on_rails/cloudflare.md)
-- [Additional Services]()
+- [Step 4: Monitoring & Protection]()
+    - [AppSignal](ruby_on_rails/appsignal.md)
     - [Sentry](ruby_on_rails/sentry.md)
     - [NewRelic](ruby_on_rails/newrelic.md)
     - [Robots.txt](ruby_on_rails/robots_txt.md)
     - [Percy](ruby_on_rails/configure_percy.md)
     - [Protect develop environment](ruby_on_rails/environment_protection.md)
-- [Customer Plan Services]()
+- [Step 5: Customer Plan Services]()
     - [Uptimerobot](ruby_on_rails/uptimerobot.md)
     - [Depfu Security monitoring](ruby_on_rails/depfu.md)
 
-- [Gems]()
-    - [Jest](ruby_on_rails/jest.md)
-    - [Send Emails](ruby_on_rails/send_emails.md)
-    - [Sparkpost & Mailtrap](sparkpost_and_mailtrap.md)
-    - [Devise](ruby_on_rails/devise.md)
-    - [Cucumber](ruby_on_rails/cucumber.md)
-    - [Object Storage](ruby_on_rails/object_storage.md)
-    - [Bootstrap](ruby_on_rails/bootstrap.md)
-    - [FontAwesome](ruby_on_rails/font_awesome.md)
-    - [Bullet](ruby_on_rails/bullet.md)
-    - [Lograge](ruby_on_rails/appsignal.md)
-    - [Hotjar](ruby_on_rails/hotjar.md)
-    - [Wicked PDF](ruby_on_rails/wicked_pdf.md)
-    - [Recaptcha v3](ruby_on_rails/recaptcha.md)
+# Guides & Recipes
+
+- [Send Emails](ruby_on_rails/send_emails.md)
+- [Sparkpost & Mailtrap](sparkpost_and_mailtrap.md)
+- [Devise](ruby_on_rails/devise.md)
+- [Object Storage](ruby_on_rails/object_storage.md)
+- [Jest](ruby_on_rails/jest.md)
+- [Cucumber](ruby_on_rails/cucumber.md)
+- [Bootstrap](ruby_on_rails/bootstrap.md)
+- [FontAwesome](ruby_on_rails/font_awesome.md)
+- [Bullet](ruby_on_rails/bullet.md)
+- [Hotjar](ruby_on_rails/hotjar.md)
+- [Wicked PDF](ruby_on_rails/wicked_pdf.md)
+- [Recaptcha v3](ruby_on_rails/recaptcha.md)
+- [Wallee Payment](ruby_on_rails/wallee.md)
+- [Content Security Policy](ruby_on_rails/content_security_policy.md)
+- [I18n](i18n.md)
 
 # Services
 
 - [Google Analytics](google_analytics.md)
-- [Google Apis](google_apis.md)
+- [Google APIs](google_apis.md)
 - [Slack and Notifications](slack_and_notifications.md)
 
+# Reference
 
-# Templates
-
-- [README](templates/README.md)
+- [Project Checklist](checklist.md)
+- [Go Live!](go_live.md)
+- [README Template](templates/README.md)
 - [Pull Request Template](templates/pull_requests_template.md)
diff --git a/configure_git_repository.md b/configure_git_repository.md
@@ -7,38 +7,37 @@ Please stick to it unless you have special needs.
   * Features: Remove *Wikis*, *Issues* and *Projects*
   * Pull Requests
     * Disable *Allow merge commits* and *Allow rebase merging*
-    * Always suggest updating pull request branches
     * Allow auto-merge
     * Automatically delete head branches
+    * Always suggest updating pull request branches
 * Manage access
   * Add *staff* team as a collaborator with Admin access
   * Add *security* team as collaborator with Write access
 * Branches
   * Default branch: either `main` or `develop` depending on whether you want one or two environments.
 * Rules/Rulesets
-  * `develop`
+  * We use two rulesets: one for `main` and one for everything else. This ensures that long-lived branches like `redesign` and feature branches like `feat/my-feature` share the same protection rules as `develop`.
+  * `non-main`
     * Enforcement status: `Active`
+    * Branch targeting criteria:
+      * Include all branches
+      * Exclude by pattern: `main`
     * Bypass list: add `Repository Admin` Role with *allow for pull requests only* option
-    * Branch targeting criteria: `develop`
     * Restrict deletions
     * Require linear history
     * Require a pull request before merging
     * Require status checks to pass
-      * Select `ci/semaphore/push` (AFTER SETTING UP SEMAPHORE)
+      * Select `ci/semaphore/push`
     * Block force pushes
-  * `main` (same as develop but...)
+  * `main` (same as non-main but...)
     * Branch targeting criteria: `main`
     * ❌ Require a pull request before merging
     * ❌ Require status checks to pass
-
 * Autolink references
   * Add a new Autolink reference with:
     * Reference prefix: `TICKET-`
     * Target URL: `https://redmine.renuo.ch/issues/<num>`
 
-In case you have a second long-living environment (e.g., for a design rewrite, a new major version, etc.),
-consider applying the same rules as on `develop` to it as well.
-
 ## Team
 
 Each project has a team owning it. The team is named after the project: `[team-name] = [project-name]`.

diff --git a/create_git_repository.md → create_github_repository.md b/create_git_repository.md → create_github_repository.md
@@ -1,4 +1,4 @@
-# Create a Git Repository
+# Create a GitHub Repository
 
 At Renuo we currently use [GitHub](https://github.com/) as our git repository. You should already be part of the Renuo Organisation and have permissions to do so.
 If that's not the case, double check the Laptop Setup Guide or ask wg-operations.
@@ -8,7 +8,7 @@ To create a new GitHub project you can use the tool you prefer, but it should ha
 * Should have `[project-name]` as a name
 * Should be private (unless you are creating an OpenSource project)
 
-Use the command `hub create -p renuo/[project-name]` to create the repo and add it to the origin of the current folder.
+Use the command `gh repo create renuo/[project-name] --private --source=. --remote=origin` to create the repo and add it to the origin of the current folder.
 
 ## Public repos need a license
 

diff --git a/ruby_on_rails/README.md b/ruby_on_rails/README.md
@@ -13,25 +13,37 @@ The application (and relative GitHub repo) will be named after the `[project-nam
 > Why the difference? Because we can bare the risk of having a bug in an internal project, but we cannot do that for a customer.
 > Decide with your team if you want one or two branches.
 
+> :bulb: **Tip:** Sections marked with ✨ are already set up by the Renuo Rails template or ship with Rails 8.1 by default. You only need to verify them, not install them.
+
+---
+
+## Step 1: Create the App
+
 1. [Initialise the Rails Application](app_initialisation.md)
 1. [Push to Git Repository](first_git_push.md)
 1. [Initialise Gitflow](initialise_gitflow.md)
 1. [Configure Github Repository](../configure_git_repository.md)
+
+## Step 2: Deploy the App
+
 1. [Create an Application Server for Deploio](create_application_server_deploio.md) or [Create an Application Server for Heroku](create_application_server_heroku.md)
 1. [Configure the CI / CD](configure_ci.md)
 
 Once here, your app should be up and running on all environments.
 
+## Step 3: Quality Tools
+
 It's now time to introduce some more tools which will help you and the team to keep a high quality during the project development.
 
 1. [RSpec](rspec.md)
 1. [Linting and automatic checks](linting_and_automatic_check.md)
 1. [Gems and libraries :gem:](suggested_libraries.md)
 1. [Cloudflare](cloudflare.md)
-1. [README](compile_readme.md)
 
 :tada: Finally you are ready to start working on you new project! :tada:
 
+## Step 4: Monitoring & Protection
+
 While everyone starts working there are some more things which you should setup.
 Most are not optional, but the rest of the team can start working even if those are not in place yet.
 
@@ -42,7 +54,8 @@ Most are not optional, but the rest of the team can start working even if those
 1. [Percy](configure_percy.md) (optional)
 1. [Protect develop environment](environment_protection.md)
 
-Some services should be configured accordingly to the packages bought by the customer.
+## Step 5: Customer Plan Services
+
 Once the new application is created, please add the project to the
 [monitoring list](https://docs.google.com/spreadsheets/d/1FY4jqByO-aI5sDan0hD7ULu6a2-eLsmO6kgdCFlPmuY/edit#gid=0)
 and discuss with the PO how the service should be configured.
@@ -52,30 +65,33 @@ and discuss with the PO how the service should be configured.
 1. [Depfu security monitoring](depfu.md)
 1. Depending on the monitoring list, also [Papertrail alerts](papertrail.md) need to be configured.
 
-Here you will find a series of chapters and guides on how to setup some of the gems we use most often and some other
-useful services:
-
-1. [Run Javascript tests with Jest](jest.md)
-1. [Pull Requests Template](../pull_requests_template.md)
-1. [Slack and Project Notifications](../slack_and_notifications.md)
-1. [Send emails](send_emails.md)
-1. [Sparkpost & Mailtrap](../sparkpost_and_mailtrap.md)
-1. [Devise](devise.md)
-1. [Cucumber](cucumber.md)
-1. [Object storage](object_storage.md)
-1. awesome_print `gem 'awesome_print'`
-1. [bootstrap](bootstrap.md)
-1. [font-awesome](font_awesome.md)
-1. [bullet](bullet.md) `gem 'bullet'`
-1. [lograge](appsignal.md) `gem 'lograge'`
-1. Rack Tracker (Google Analytics) `gem 'rack-tracker'` --> see [Google Analytics](../google_analytics.md)
-1. Favicons
-1. [Rack CORS](https://github.com/cyu/rack-cors)
-1. [Rack Attack](https://github.com/rack/rack-attack#installing)
-1. [:fire: Hotjar](hotjar.md)
-1. SEO
-    * redirect non-www to www
-    * Header tags
-1. [wicked pdf](wicked_pdf.md) `gem wicked_pdf`
-1. [Recaptcha v3](recaptcha.md)
-1. [Wallee Payment Integration](wallee.md)
+---
+
+## Guides & Recipes
+
+The following are not part of the sequential setup. Use them as needed for your project.
+
+* [Run Javascript tests with Jest](jest.md)
+* [Pull Requests Template](../templates/pull_requests_template.md)
+* [Slack and Project Notifications](../slack_and_notifications.md)
+* [Send emails](send_emails.md)
+* [Sparkpost & Mailtrap](../sparkpost_and_mailtrap.md)
+* [Devise](devise.md)
+* [Cucumber](cucumber.md)
+* [Object storage](object_storage.md)
+* awesome_print `gem 'awesome_print'`
+* [bootstrap](bootstrap.md)
+* [font-awesome](font_awesome.md)
+* [bullet](bullet.md) `gem 'bullet'`
+* [lograge](appsignal.md#lograge) `gem 'lograge'`
+* Rack Tracker (Google Analytics) `gem 'rack-tracker'` --> see [Google Analytics](../google_analytics.md)
+* Favicons
+* [Rack CORS](https://github.com/cyu/rack-cors)
+* [Rack Attack](https://github.com/rack/rack-attack#installing)
+* [:fire: Hotjar](hotjar.md)
+* SEO
+  * redirect non-www to www
+  * Header tags
+* [wicked pdf](wicked_pdf.md) `gem wicked_pdf`
+* [Recaptcha v3](recaptcha.md)
+* [Wallee Payment Integration](wallee.md)
diff --git a/ruby_on_rails/app_initialisation.md b/ruby_on_rails/app_initialisation.md
@@ -78,8 +78,8 @@ Check existing projects for an example of the usage.
 * Update `config/application.rb` and set the default language and timezone
 
   ```ruby
-  config.time_zone = 'Zurich'
-  config.i18n.default_locale = :de
+  config.time_zone = 'Zurich' # may vary
+  config.i18n.default_locale = :de # may vary
   ```
 
 * Update your `config/environments/production.rb` settings:
@@ -95,7 +95,9 @@ Check existing projects for an example of the usage.
   config.action_controller.action_on_unpermitted_parameters = :raise
   config.i18n.raise_on_missing_translations = :strict
 
-  config.generators.apply_rubocop_autocorrect_after_generate!
+  config.generators do |g|
+    g.apply_rubocop_autocorrect_after_generate!
+  end
   ```
 
 * Update `config/environments/test.rb` settings:
@@ -129,4 +131,4 @@ Check existing projects for an example of the usage.
 ## Finalising
 
 * Check if the following scripts run successfully: `bin/setup`, `bin/check`, `bin/run`
-* If they do, commit all your changes to the main branch with Git.
+* If they do, you're ready for the next step.
diff --git a/ruby_on_rails/compile_readme.md b/ruby_on_rails/compile_readme.md