renuo · cb341 · Jul 17, 2026 · May 20, 2026 · Jul 16, 2026 · Jul 16, 2026
diff --git a/README.md b/README.md
@@ -5,10 +5,6 @@ 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)
-
-## Some Notes on the Side
-
 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**.
@@ -19,32 +15,38 @@ This guide is the result of more than ten years of experience, so this means thr
 
 **You are always welcome to challenge the guide and improve it with a Pull Request.**
 
-The basic things that need to be ready before the team can start working on a project are:
+**: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.**
 
-* An existing *git* repository containing the project
-* Two branches: *main* and *develop*
-* 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
+Thank you for your work and have fun! :tada:
 
-As an appendix, you'll find a [checklist](checklist.md) you can use to follow the guide.
+## How to Use This 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.**
+The guide is structured as a linear walkthrough. Follow it from top to bottom when setting up a new project.
 
-We want you to know exactly the reason behind each single step of this guide.
+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.
 
-Thank you for your work and have fun! :tada:
+## What Needs to Be Ready
+
+Before the team can start working on a project, you need:
+
+* An existing *git* repository containing the project
+* 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 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)
+    - [Configure GitHub Repository](configure_github_repository.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 → configure_github_repository.md b/configure_git_repository.md → configure_github_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)
+1. [Configure Github Repository](../configure_github_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,41 +54,42 @@ 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.
-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.
+## Step 5: Customer Plan Services
+
+Bookmark the project on [Redmine](https://dashboard.renuo.ch/redmine_projects) and configure the services listed there.
 
 1. [Uptimerobot](uptimerobot.md)
-1. Depending on the monitoring list, also [Sentry notifications](sentry.md) need to be configured.
+1. [Sentry notifications](sentry.md), if requested
 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)
-1. [Sign in with Redmine](https://gist.github.com/sislr/fb7f6d8f05c96c199d9525706561902d)
+1. [Papertrail alerts](papertrail.md), if requested
+
+---
+
+## 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
@@ -95,7 +95,7 @@ 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 { |g| g.apply_rubocop_autocorrect_after_generate! }
   ```
 
 * Update `config/environments/test.rb` settings:

diff --git a/ruby_on_rails/compile_readme.md b/ruby_on_rails/compile_readme.md
diff --git a/ruby_on_rails/create_application_server_deploio.md b/ruby_on_rails/create_application_server_deploio.md
@@ -2,21 +2,13 @@
 
 ## Prerequisites
 
-Before setting up your application, ensure you have completed the following for Deploio.
-
-### Prerequisites for Deploio
-
 - You've [read about what Deploio is](https://docs.nine.ch/docs/deplo-io/getting-started-with-deploio).
 - You have a Deploio account.
 - You have installed the `renuo-cli` gem.
 - You have installed the `nctl` command.
 - You have logged in using `nctl`.
 
-## Setup Your Application
-
-### Setup Deploio Application
-
-#### Remote Configuration
+## Setup
 
 Run [the command to generate a script](https://github.com/renuo/renuo-cli/blob/main/lib/renuo/cli/commands/create_deploio_app.rb) which will create and configure all Deploio apps. `[project-name]` string length is limited to 63 characters:
 
@@ -36,7 +28,7 @@ If you think that the production database will soon reach the 10 GB, please cons
 
 If you think that the script is outdated, please open a Pull Request on the [renuo-cli](https://github.com/renuo/renuo-cli) project.
 
-For further configuration and best practices, please refer to the [Deploio documentation](https://guides.deplo.io). You can also view a Ruby on Rails specific guide [here](https://guides.deplo.io/ruby/quick-start.html).
+For further configuration, see the [Rails on Deploio guide](https://guides.deplo.io/ruby/quick-start.html). For general Deploio docs, see [guides.deplo.io](https://guides.deplo.io).
 
 ## Next Steps