ru.Bee 2.6.5 → 2.7.0

data/readme.md

@@ -5,25 +5,25 @@
 ![Gem](https://img.shields.io/gem/v/ru.Bee.svg)
 ![GitHub Repo stars](https://img.shields.io/github/stars/nucleom42/rubee?style=social)
 
-<img width="363" height="131" alt="Screen Shot 2026-01-27 at 11 19 15 PM" src="https://github.com/user-attachments/assets/f6f07b88-f58d-4f36-a857-a293e613269e" />
+<img width="363" height="131" alt="ru.Bee logo" src="https://github.com/user-attachments/assets/f6f07b88-f58d-4f36-a857-a293e613269e" />
 
-ru.Bee is a Ruby-based web framework designed to streamline the development of modular monolith web applications. \
-Under the hood, it leverages the power of Ruby and Rack backed by Puma, offering a clean, efficient, and flexible architecture. \
-It offers a structured approach to building scalable, maintainable, and React-ready projects, \
+ru.Bee is a Ruby-based web framework designed to streamline the development of modular monolith web applications.
+Under the hood, it leverages the power of Ruby and Rack backed by Puma, offering a clean, efficient, and flexible architecture.
+It offers a structured approach to building scalable, maintainable, and React-ready projects,
 making it an ideal choice for developers seeking a balance between monolithic simplicity and modular flexibility.
 
-Want to get a quick API server up and runing? You can do it for real quick!
+Want to get a quick API server up and running? You can do it in no time!
 <br />
 [![Watch the demo](https://img.youtube.com/vi/ko7H70s7qq0/hqdefault.jpg)](https://www.youtube.com/watch?v=ko7H70s7qq0)
 
-Starting from ru.Bee 2.0.0, ru.Bee supports Websocket, which is a feature that allows you to build real-time applications with ease. \
+Starting from ru.Bee 2.0.0, ru.Bee supports WebSocket, which allows you to build real-time applications with ease.
 <br />
 [![Watch the demo](https://img.youtube.com/vi/gp8IheKBNm4/hqdefault.jpg)](https://www.youtube.com/watch?v=gp8IheKBNm4)
 
 ## Production ready
 
-Take a look on the ru.Bee demo site with all documentation stored in there: https://rubee.dedyn.io/
-Want to explore how it built? https://github.com/nucleom42/rubee-site
+Take a look at the ru.Bee demo site with full documentation: https://rubee.dedyn.io/
+Want to explore how it was built? https://github.com/nucleom42/rubee-site
 
 ## Stress tested
 
@@ -39,31 +39,33 @@ Requests/sec:    323.78
 Transfer/sec:    140.07KB
 ```
 
-- Short output explanation:
+Short output explanation:
+
 - Requests/sec: ~324
 - Average latency: ~305 ms
 - Total requests handled: 9,721
-- Hardware: Raspberry Pi 5(8 Gb) (single board computer)
+- Hardware: Raspberry Pi 5 (8 GB) — single board computer
 - Server: ru.Bee app hosted via Nginx + HTTPS
 
-This demonstrate ru.Bee’s efficient architecture and suitability for lightweight deployments — even on low-power hardware.
+This demonstrates ru.Bee's efficient architecture and suitability for lightweight deployments — even on low-power hardware.
 
 ## Comparison
-Here below is a **short web frameworks comparison** built with Ruby, so you can evaluate your choice with ru.Bee.
+
+Here is a short web frameworks comparison built with Ruby, so you can evaluate your choice with ru.Bee.
 
 **Disclaimer:**
-The comparison is based on a very generic and subjective information open in the Internet and is not a real benchmark. The comparison is aimed to give you a general idea of the differences between the frameworks and Rubee and not to compare the frameworks directly.
+The comparison is based on generic and subjective information available on the internet and is not a real benchmark. It is aimed at giving you a general idea of the differences between the frameworks and is not intended as a direct comparison.
 
 | Feature / Framework | **ru.Bee** | Rails | Sinatra | Hanami | Padrino | Grape |
 |---------------------|-----------|-------|---------|--------|---------|-------|
 | **React readiness** | Built-in React integration (route generator can scaffold React components that fetch data via controllers) | React via webpacker/importmap, but indirect | No direct React support | Can integrate React | Can integrate via JS pipelines | API-focused, no React support |
 | **Routing style**   | Explicit, file-based routes with clear JSON/HTML handling | DSL, routes often implicit inside controllers | Explicit DSL, inline in code | Declarative DSL | Rails-like DSL | API-oriented DSL |
-| **Modularity**      | Lightweight core, pluggable projects | One project by default, but can be extended with repsecrive gem | Very modular (small DSL) | Designed for modularity | Semi-modular, still Rails-like | Modular (mount APIs) |
+| **Modularity**      | Lightweight core, pluggable projects | One project by default, but can be extended with respective gem | Very modular (small DSL) | Designed for modularity | Semi-modular, still Rails-like | Modular (mount APIs) |
 | **Startup / Load speed** | Very fast (minimal boot time, designed for modern Ruby) | Not very fast, especially on large apps | Very fast | Medium (slower than Sinatra, faster than Rails) | Similar to Rails (heavier) | Fast |
-| **Ecosystem**       | 🌱 Early-stage, focused on modern simplicity, but easily expandable over bundler | Huge ecosystem, gems, community | Large ecosystem, many gems work | Small, growing | Small, less active | Small, niche |
+| **Ecosystem**       | Early-stage, focused on modern simplicity, but easily expandable via Bundler | Huge ecosystem, gems, community | Large ecosystem, many gems work | Small, growing | Small, less active | Small, niche |
 | **Learning curve**  | Simple, explicit, minimal DSL | Steep (lots of conventions & magic) | Very low (DSL fits in one file) | Medium, more concepts (repositories, entities) | Similar to Rails, easier in parts | Low (API-only) |
 | **Customizability** | High (explicit over implicit, hooks & generators) | Limited without monkey-patching | Very high (you control flow) | High, modular architecture | Medium | High (designed for APIs) |
-| **Target use case** | Modern full-stack apps with React frontends or APIs, may be well suite if you prefer modular monolith over microservices | Large, full-stack, mature apps | Small apps, microservices | Modular apps, DDD | Rails-like but modular | APIs & microservices |
+| **Target use case** | Modern full-stack apps with React frontends or APIs; well-suited if you prefer modular monolith over microservices | Large, full-stack, mature apps | Small apps, microservices | Modular apps, DDD | Rails-like but modular | APIs & microservices |
 | **Early adopters support** | Personal early adopters support via fast extending and fixing | Not available | Not known | Not known | Not known | Not known |
 
 ## Content
@@ -75,33 +77,33 @@ The comparison is based on a very generic and subjective information open in the
 - [Routing](#routing)
 - [Database](#database)
 - [Views](#views)
-- [Hooks](#hooks)
+- [Object hooks](#object-hooks)
 - [Validations](#validations)
-- [JWT based authentification](#jwt-based-authentification)
-- [OAuth2 based authentification](#oauth-authentification)
-- [Rubee commands](#rubee-commands)
+- [JWT based authentication](#jwt-based-authentication)
+- [OAuth authentication](#oauth-authentication)
+- [ru.Bee commands](#rubee-commands)
 - [Generate commands](#generate-commands)
 - [Migration commands](#migration-commands)
-- [Rubee console](#rubee-console)
+- [ru.Bee console](#rubee-console)
 - [Rubee::Support](#rubee-support)
 - [Testing](#testing)
 - [Background jobs](#background-jobs)
-- [Modular](#modualar-application)
+- [Modular application](#modular-application)
 - [Logger](#logger)
-- [Websocket](#websocket)
+- [WebSocket](#websocket)
+- [Bee assistant](#bee-assistant)
 
-You can read it on the demo: [site](https://rubee.dedyn.io/)
+You can read the full docs on the demo site: [rubee.dedyn.io](https://rubee.dedyn.io/)
 
 ## Features
 
 Lightweight – A minimal footprint focused on serving Ruby applications efficiently.
 <br>
-Modular – A modular approach to application development. Build modular monolith app with ease by attaching
-as many subprojects as you need.
+Modular – A modular approach to application development. Build a modular monolith app with ease by attaching as many subprojects as you need.
 <br>
 Contract-driven – Define your API contracts in a simple, declarative way, then generate all the boilerplate you need.
 <br>
-Fast – Optimized for speed, providing quick responses. (Everything is relative, we know! 😄)
+Fast – Optimized for speed, providing quick responses.
 <br>
 Rack-powered – Built on Rack. The full Rack API is available for easy integration.
 <br>
@@ -127,7 +129,7 @@ Console – Start an interactive console and reload on the fly.
 <br>
 Background Jobs – Schedule and process background jobs using your preferred async stack.
 <br>
-Websocket – Serve and handle WebSocket connections.
+WebSocket – Serve and handle WebSocket connections.
 <br>
 Logger – Use any logger you want.
 
@@ -145,44 +147,39 @@ rubee project my_project
 cd my_project
 ```
 
-[Back to content](#content)
-
 3. Install dependencies
 
-***Prerequisites***<br />
-Make sure:
-**Ruby** language (3.1 or higher, 3.4.1 recommended) is installed
-**Bundler** is installed
+Prerequisites: make sure **Ruby** (3.1 or higher, 3.4.1 recommended) and **Bundler** are installed.
 
 ```bash
 bundle install
 ```
 
-4. Run ru.Bee server. Default port is 7000
+4. Run the ru.Bee server. Default port is 7000.
 ```bash
 rubee start # or rubee start_dev for development
 
-# Sarting from veriosn 1.8.0, you can also start you rubee server with yjit compiler and enjoy speed boost.
+# Starting from version 1.8.0, you can also start the server with the yjit compiler for a speed boost.
 rubee start --jit=yjit
-# Option is available for dev environment too
+# This option is available for the dev environment too.
 rubee start_dev --jit=yjit
 ```
 
 5. Open your browser and go to http://localhost:7000
 
 ## Run tests
+
 ```bash
 rubee test
-# or you can specify specific test file
+# or specify a specific test file
 rubee test models/user_model_test.rb
-# you can run specicfc line in the test file
+# or run a specific line in the test file
 rubee test models/user_model_test.rb --line=12
 ```
-[Back to content](#content)
 
 ## Draw contract
 
-1. Add the routes to the routes.rb
+1. Add the routes to `routes.rb`
     ```ruby
     Rubee::Router.draw do |router|
       ...
@@ -201,28 +198,28 @@ rubee test models/user_model_test.rb --line=12
     end
     ```
 
-2. generate the files
+2. Generate the files
 ```bash
-    rubee generate get /apples
+rubee generate get /apples
 ```
-This will generate the following files
+This will generate the following files:
 ```bash
-  ./app/controllers/apples_controller.rb # Controller with respective action
-  ./app/views/apples_index.erb # ERB view that is rendered by the controller right away
-  ./app/models/apple.rb # Model that acts as ORM
-  ./db/create_apples.rb # Database migration file needed for creating repsective table
+./app/controllers/apples_controller.rb # Controller with respective action
+./app/views/apples_index.erb           # ERB view rendered by the controller
+./app/models/apple.rb                  # Model that acts as ORM
+./db/create_apples.rb                  # Database migration file for the respective table
 ```
 
-3. Run the initial db migration
+3. Run the initial database migration
 ```bash
-    rubee db run:all
+rubee db run:all
 ```
 
-4. Fill the generated files with the logic you need and run the server again!
+4. Fill the generated files with the logic you need and run the server again.
 
-5. You can find full snapshot of the schema in the STRUCTURE constant or in the db/structur.rb file.
+5. You can find a full snapshot of the schema in the `STRUCTURE` constant or in the `db/structure.rb` file.
 
-6. You can use rubee cli for printing out lates schema, out of STRUCUTRE constant
+6. Print the latest schema from the `STRUCTURE` constant via the CLI
 ```bash
 -> rubee db schema
 --- users
@@ -232,7 +229,7 @@ This will generate the following files
 
 --- accounts
 - id, (PK), type (INTEGER)
-- addres, type (varchar(255))
+- address, type (varchar(255))
 - user_id, type (INTEGER)
 
 --- posts
@@ -245,7 +242,8 @@ This will generate the following files
 - text, type (varchar(255))
 - user_id, type (INTEGER)
 ```
-7. You can also rpint out the schema for the table you need
+
+7. Print the schema for a specific table
 ```bash
 -> rubee db schema posts
 --- posts
@@ -259,149 +257,145 @@ This will generate the following files
   - comment_id → comments() on delete no_action on update no_action
   - user_id → users() on delete no_action on update no_action
 ```
-8. Drop all tables can be handy for development process. But be careful and make sure you pass desired environment
+
+8. Dropping all tables can be handy during development. Be careful and make sure you pass the desired environment.
 ```bash
 RACK_ENV=test rubee db drop_tables
-These tables has been dropped for test env
+These tables have been dropped for the test env:
 [:companies, :company_clients, :services]
 ```
 
 [Back to content](#content)
 
 ## Model
-Model in ru.Bee is just simple ruby object that can be serilalized in the view
-in the way it required (ie json).
-Here below is a simple example on how it can be used by rendering json from in memory object
+
+A model in ru.Bee is a simple Ruby object that can be serialized in the view in whatever form is required (e.g. JSON).
+Here is a simple example of rendering JSON from an in-memory object:
 
 ```ruby
-  #ApplesController
+# ApplesController
 
-  def show
-    # In memory example
-    apples = [Apple.new(colour: 'red', weight: '1lb'), Apple.new(colour: 'green', weight: '1lb')]
-    apple = apples.find { |apple| apple.colour = params[:colour] }
+def show
+  # In-memory example
+  apples = [Apple.new(colour: 'red', weight: '1lb'), Apple.new(colour: 'green', weight: '1lb')]
+  apple = apples.find { |apple| apple.colour = params[:colour] }
 
-    response_with object: apple, type: :json
-  end
+  response_with object: apple, type: :json
+end
 ```
 
-Just make sure Serializable module included in the target class.
+Make sure the `Serializable` module is included in the target class:
 ```ruby
-  class Apple
-    include Serializable
-    attr_accessor :id, :colour, :weight
-  end
+class Apple
+  include Serializable
+  attr_accessor :id, :colour, :weight
+end
 ```
 
-However, you can simply turn it to ORM object by extending database class Rubee::SequelObject.
-This one is already serializable and charged with hooks.
-```Ruby
-  class Apple < Rubee::SequelObject
-    attr_accessor :id, :colour, :weight
-  end
+You can also turn it into an ORM object by extending `Rubee::SequelObject`, which is already serializable and charged with hooks:
+```ruby
+class Apple < Rubee::SequelObject
+  attr_accessor :id, :colour, :weight
+end
 ```
 
-So in the controller you would need to query your target object now.
+In the controller, query your target object directly:
 ```ruby
-  #ApplesController
+# ApplesController
 
-  def show
-    apple = Apple.where(colour: params[:colour])&.last
+def show
+  apple = Apple.where(colour: params[:colour])&.last
 
-    if apple
-      response_with object: apple, type: :json
-    else
-      response_with object: { error: "apple with colour #{params[:colour]} not found" }, status: 422, type: :json
-    end
+  if apple
+    response_with object: apple, type: :json
+  else
+    response_with object: { error: "apple with colour #{params[:colour]} not found" }, status: 422, type: :json
   end
+end
 ```
 
 [Back to content](#content)
 
-#### Rubee::SequelObject base methods
+### Rubee::SequelObject base methods
 
-Initiate new record in memory
-```Ruby
+Initiate a new record in memory
+```ruby
 irb(main):015> user = User.new(email: "llo@ok.com", password: 543)
 => #<User:0x000000010cda23b8 @email="llo@ok.com", @password=543>
 ```
 
-Save record in db
-```Ruby
-=> #<User:0x000000010cda23b8 @email="llo@ok.com", @password=543, @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400">
+Save a record to the database
+```ruby
 irb(main):018> user.save
 => true
 ```
 
-Update record with new value
-```Ruby
+Update a record with a new value
+```ruby
 irb(main):019> user.update(email: "update@email.com")
-=> #<User:0x000000010c39b298 @email="update@email.com", @id=3, @password="543" @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400">
+=> #<User:0x000000010c39b298 @email="update@email.com", @id=3, @password="543", @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400">
 ```
 
-Check whether it includes id
-```Ruby
-irb(main):015> user = User.new(email: "llo@ok.com", password: 543)
-=> #<User:0x000000010cda23b8 @email="llo@ok.com", @password=543>
+Check whether a record has been persisted
+```ruby
 irb(main):016> user.persisted?
 => false
 ```
 
-Get the record from the database
-```Ruby
+Get a record from the database and reload it
+```ruby
 irb(main):011> user = User.last
-=> #<User:0x000000010ccea178 @email="ok23@ok.com", @id=2, @password="123", @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400">
+=> #<User:0x000000010ccea178 @email="ok23@ok.com", @id=2, @password="123", ...>
 irb(main):012> user.email = "new@ok.com"
 => "new@ok.com"
-irb(main):013> user
-=> #<User:0x000000010ccea178 @email="new@ok.com", @id=2, @password="123", @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400">
 irb(main):014> user.reload
-=> #<User:0x000000010c488548 @email="ok23@ok.com", @id=2, @password="123", @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400"> # not persited data was updated from db
+=> #<User:0x000000010c488548 @email="ok23@ok.com", @id=2, @password="123", ...> # unpersisted data refreshed from db
 ```
 
-Assign attributes without persisiting it to db
-```Ruby
+Assign attributes without persisting to the database
+```ruby
 irb(main):008> User.last.assign_attributes(email: "bb@ok.com")
-=> {"id" => 2, "email" => "ok23@ok.com", "password" => "123"
+=> {"id" => 2, "email" => "ok23@ok.com", "password" => "123"}
 ```
 
-Get all records scoped by field
-```Ruby
+Get all records scoped by a field
+```ruby
 irb(main):005> User.where(email: "ok23@ok.com")
 => [#<User:0x000000010cfaa5c0 @email="ok23@ok.com", @id=2, @password="123">]
 ```
 
-Get all record
-```Ruby
+Get all records
+```ruby
 irb(main):001> User.all
-=> [#<User:0x000000010c239a30 @email="ok@ok.com", @id=1, @password="password", @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400">]
+=> [#<User:0x000000010c239a30 @email="ok@ok.com", @id=1, @password="password", ...>]
 ```
+
 Find by id
-```Ruby
+```ruby
 irb(main):002> user = User.find 1
-=> #<User:0x000000010c2f7cd8 @email="ok@ok.com", @id=1, @password="password", @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400">
+=> #<User:0x000000010c2f7cd8 @email="ok@ok.com", @id=1, @password="password", ...>
 ```
 
-Get last record
-```Ruby
+Get the last record
+```ruby
 irb(main):003> User.last
-=> #<User:0x000000010c2f7cd8 @email="ok@ok.com", @id=1, @password="password", @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400">
+=> #<User:0x000000010c2f7cd8 @email="ok@ok.com", @id=1, @password="password", ...>
 ```
 
-Create new persited record
-```Ruby
+Create a new persisted record
+```ruby
 irb(main):004> User.create(email: "ok23@ok.com", password: 123)
-=> #<User:0x000000010c393818 @email="ok23@ok.com", @id=2, @password=123, @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400">
+=> #<User:0x000000010c393818 @email="ok23@ok.com", @id=2, @password=123, ...>
 ```
 
-Destroy record and all related records
-```Ruby
+Destroy a record and all related records
+```ruby
 irb(main):021> user.destroy(cascade: true)
 => 1
 ```
 
-Find record in the databse or initialize the instance for following persistence
-```Ruby
+Find a record in the database or initialize a new instance for subsequent persistence
+```ruby
 irb(main):020> user = User.find_or_new(email: "ok23@ok.com")
 => #<User:0x000000010cfaa5c0 @email="ok23@ok.com", @id=2, @password="123">
 irb(main):021> user.persisted?
@@ -413,15 +407,15 @@ irb(main):023> user.persisted?
 ```
 
 Destroy all records one by one
-```Ruby
+```ruby
 irb(main):022> User.destroy_all
-=> [#<User:0x000000010d42df98 @email="ok@ok.com", @id=1, @password="password", @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400">, #<User:0x000000010d42de80 @email="ok23@ok.com", @id=2, @password="123", @created="2025-09-28 22:03:07.011332 -0400", @updated="2025-09-28 22:03:07.011332 -0400">>
+=> [#<User ...>, #<User ...>]
 irb(main):023> User.all
 => []
 ```
 
-Use complex queries chains and when ready serialize it back to ru.Bee object.
-```Ruby
+Use complex query chains and serialize results back to ru.Bee objects in a single query:
+```ruby
 # user model
 class User < Rubee::SequelObject
   attr_accessor :id, :email, :password, :created, :updated
@@ -442,54 +436,40 @@ class Post < Rubee::SequelObject
 end
 ```
 
-```Ruby
-irb(main):001> comment = Comment.new(text: "test")
-irb(main):002> comment.save
-irb(main):003> user = User.new(email: "ok-test@test.com", password: "123")
-irb(main):004> user.save
-irb(main):005> post = Post.new(user_id: user.id, comment_id: comment.id)
-irb(main):006> post.save
-=> true
-irb(main):007> comment
-=> #<Comment:0x000000012281a650 @id=21, @text="test", @created=2025-09-28 22:03:07.011332 -0400, @updated=2025-09-28 22:03:07.011332 -0400>
+```ruby
 irb(main):008> result = Comment.dataset.join(:posts, comment_id: :id)
 irb(main):009>  .where(comment_id: Comment.where(text: "test").last.id)
 irb(main):010>  .then { |dataset| Comment.serialize(dataset) }
-=> [#<Comment:0x0000000121889998 @id=30, @text="test", @user_id=702, @created=2025-09-28 22:03:07.011332 -0400, @updated=2025-09-28 22:03:07.011332 -0400>]
+=> [#<Comment:0x0000000121889998 @id=30, @text="test", @user_id=702, ...>]
 ```
-This is recommended when you want to run one query and serialize it back to ru.Bee object only once.
-So it may safe some resources.
 
-Since version 2.6.0 Rubee::SequelObject supports chaining queries:
+Since version 2.6.0, `Rubee::SequelObject` supports chained queries. Supported methods: `where`, `order`, `limit`, `offset`, `all`, `owns_many`, `owns_one`, `join`, `paginate`.
+
 ```ruby
 irb(main):001> Comment.where(text: "test").where(user_id: 1)
-=> [#<Comment:0x0000000121889998 @id=30, @text="test", @user_id=702, @created=2025-09-28 22:03:07.011332 -0400, @updated=2025-09-28 22:03:07.011332 -0400>]
+=> [#<Comment:0x0000000121889998 @id=30, @text="test", @user_id=702, ...>]
 ```
-It will run only one query tho.
-Supported methods: where, order, limit, offset, all, owns_many, owns_one, join, paginate
 
-Also new paginate method is available:
+A `paginate` method is also available:
 ```ruby
 irb(main):001> comments = Comment.all.paginate(page: 1, per_page: 3)
-[#<Comment:0x0000000121889998 @id=30, @text="test", @user_id=702, @created=2025-09-28 22:03:07.011332 -0400, @updated=2025-09-28 22:03:07.011332 -0400>,
- #<Comment:0x0000000121889998 @id=30, @text="test", @user_id=702, @created=2025-09-28 22:03:07.011332 -0400, @updated=2025-09-28 22:03:07.011332 -0400>,
- #<Comment:0x0000000121889998 @id=30, @text="test", @user_id=702, @created=2025-09-28 22:03:07.011332 -0400, @updated=2025-09-28 22:03:07.011332 -0400>]
 
 irb(main):001> comments.pagination_meta
 => {:current_page=>1, :per_page=>3, :total_count=>10, :first_page=>true, :last_page=>false, :prev=>nil, :next=>2}
 ```
+
 [Back to content](#content)
 
 ## Database
 
-ru.Bee supports Postgres and Mysqlite databases fully and can potentially be used with any
-database supported by Sequel gem.
+ru.Bee supports Postgres and SQLite databases fully and can potentially be used with any database supported by the Sequel gem.
 
-When it comes to sqlite make sure you have sqlite3 included in your Gemfile.
+When using SQLite, include `sqlite3` in your Gemfile:
 ```ruby
 gem 'sqlite3'
 ```
-And define your database urls for each environment in config/base_configuration.rb file:
+
+Define your database URLs for each environment in `config/base_configuration.rb`:
 ```ruby
 Rubee::Configuration.setup(env = :development) do |config|
   config.database_url = { url: 'sqlite://db/development.db', env: }
@@ -504,11 +484,12 @@ Rubee::Configuration.setup(env = :production) do |config|
   ...
 end
 ```
-For the PostgreSQL you need to include pg gem in your Gemfile
+
+For PostgreSQL, include the `pg` gem and configure the URLs:
 ```ruby
 gem 'pg'
 ```
-And define your database urls for each environment in config/base_configuration.rb file:
+
 ```ruby
 Rubee::Configuration.setup(env = :development) do |config|
   config.database_url = { url: "postgres://postgres@localhost:5432/development", env: }
@@ -523,68 +504,70 @@ Rubee::Configuration.setup(env = :production) do |config|
   ...
 end
 ```
-Before you start the server or runninng test suite you need to ensure your database is initated.
+
+Before starting the server or running the test suite, ensure your database is initialized:
 ```bash
-rubee db init # this will ensure your database is created for each environment
-RACK_ENV=test rubee db run:all # this will run all migrations for test environment
-RACK_ENV=development rubee db run:all # this will run all migrations for development environment
+rubee db init                         # ensures your database is created for each environment
+RACK_ENV=test rubee db run:all        # runs all migrations for the test environment
+RACK_ENV=development rubee db run:all # runs all migrations for the development environment
 ```
 
 [Back to content](#content)
 
-## Mysqlite production ready
-Starting from verison 1.9.0 main issue for using sqlite - write db lock is resolved!
-If you feel comfortable you can play with retry configuration parameters:
+### SQLite production ready
+
+Starting from version 1.9.0, the main issue with SQLite — write database locking — is resolved.
+You can tune the retry configuration parameters as needed:
 
 ```ruby
-  ## configure db write retries
-  config.db_max_retries = { env:, value: 3 } # set it to 0 to disable or increase if needed
-  config.db_retry_delay = { env:, value: 0.1 }
-  config.db_busy_timeout = { env:, value: 1000 } # this is busy timeout in ms, before raising bussy error
+## configure database write retries
+config.db_max_retries    = { env:, value: 3 }     # set to 0 to disable, or increase if needed
+config.db_retry_delay    = { env:, value: 0.1 }
+config.db_busy_timeout   = { env:, value: 1000 }  # busy timeout in milliseconds before raising an error
 ```
 
-For ru.Bee model class persist methods create and update retry will be added automatically. However, \
-if you want to do it with Sequel dataset you need to do it yourself:
+For ru.Bee model `create` and `update` methods, retries are added automatically. To use retries with a Sequel dataset directly:
 
 ```ruby
-  Rubee::DBTools.with_retry { User.dataset.insert(email: "test@ok.com", password: "123") }
+Rubee::DBTools.with_retry { User.dataset.insert(email: "test@ok.com", password: "123") }
 ```
+
 [Back to content](#content)
 
 ## Routing
-ru.Bee uses explicit routes. In the routes.rb yout can define routes for any of the main HTTP methods. \
-You can also add any matched parameter denoted by a pair of `{ }` in the path of the route. \
-Eg. `/path/to/{a_key}/somewhere`
+
+ru.Bee uses explicit routes. In `routes.rb` you can define routes for any of the main HTTP methods.
+You can also include matched parameters denoted by `{ }` in the route path, e.g. `/path/to/{a_key}/somewhere`.
 
 ### Routing methods
-``` ruby
+
+```ruby
 Rubee::Router.draw do |router|
-  router.get '/posts', to: 'posts#index'
-  router.post '/posts', to: 'posts#create'
-  router.patch '/posts/{id}', to: 'posts#update'
-  router.put '/posts/{id}', to: 'posts#update'
-  router.delete '/posts/{id}', to: 'posts#delete'
-  router.head '/posts', to: 'posts#index'
-  router.connect '/posts', to: 'posts#index'
-  router.options '/posts', to: 'posts#index'
-  router.trace '/posts', to: 'posts#index'
+  router.get     '/posts',       to: 'posts#index'
+  router.post    '/posts',       to: 'posts#create'
+  router.patch   '/posts/{id}',  to: 'posts#update'
+  router.put     '/posts/{id}',  to: 'posts#update'
+  router.delete  '/posts/{id}',  to: 'posts#delete'
+  router.head    '/posts',       to: 'posts#index'
+  router.connect '/posts',       to: 'posts#index'
+  router.options '/posts',       to: 'posts#index'
+  router.trace   '/posts',       to: 'posts#index'
 end
 ```
 
-As you see above every route is set up as:\
+Every route follows this structure:
 ```ruby
 route.{http_method} {path}, to: "{controller}#{action}",
-  model { ...optional }, namespace { ...optional }, react { ...optional }
+  model: { ...optional }, namespace: { ...optional }, react: { ...optional }
 ```
 
-### Defining Model attributes in routes
-One of ru.Bee's unique traits is where we can define our models for generation. \
-You've seen above one possible way you can set up.
+### Defining model attributes in routes
+
+One of ru.Bee's unique traits is defining models for generation directly in the routes:
 
 ```ruby
 Rubee::Router.draw do |router|
   ...
-  # draw the contract
   router.get "/apples", to: "apples#index",
     model: {
       name: "apple",
@@ -599,139 +582,105 @@ Rubee::Router.draw do |router|
 end
 ```
 
-There are many other types supported by us and Sequel to help generate your initial db files. \
-Other supported attribute key types are:
-``` ruby
+Other supported attribute types via Sequel:
+```ruby
 [
-  { name: 'id', type: :primary},
-  { name: 'name', type: :string },
-  { name: 'description', type: :text },
-  { name: 'quntity', type: :integer },
-  { name: 'created', type: :date },
-  { name: 'modified', type: :datetime },
-  { name: 'exists', type: :time },
-  { name: 'active', type: :boolean },
-  { name: 'hash', type: :bigint },
-  { name: 'price', type: :decimal },
-  { name: 'item_id', type: :foreign_key },
-  { name: 'item_id_index', type: :index },
-  { name: 'item_id_unique', type: :unique }
+  { name: 'id',              type: :primary },
+  { name: 'name',            type: :string },
+  { name: 'description',     type: :text },
+  { name: 'quantity',        type: :integer },
+  { name: 'created',         type: :date },
+  { name: 'modified',        type: :datetime },
+  { name: 'exists',          type: :time },
+  { name: 'active',          type: :boolean },
+  { name: 'hash',            type: :bigint },
+  { name: 'price',           type: :decimal },
+  { name: 'item_id',         type: :foreign_key },
+  { name: 'item_id_index',   type: :index },
+  { name: 'item_id_unique',  type: :unique }
 ]
 ```
-Every attribute can have a set of options passed based on their related \
-[Sequel schema definition](https://github.com/jeremyevans/sequel/blob/master/doc/schema_modification.rdoc).
 
-An example of this would be for the type string: \
+Every attribute can carry options based on the [Sequel schema definition](https://github.com/jeremyevans/sequel/blob/master/doc/schema_modification.rdoc). For example:
+
 ```ruby
-{name: 'key', type: :string, options: { size: 50, fixed: true } }
+{ name: 'key', type: :string, options: { size: 50, fixed: true } }
 ```
 
-Gets translated to:\
-```
-rubyString :key, size: 50, fixed: true
+Gets translated to:
+```ruby
+String :key, size: 50, fixed: true
 ```
 
 ### Generation from routes
-As long as you have a `{ model: 'something' }` passed to your given route, \
-you can use it to generate your initial model files. If only a `path` and a `to:` are defined will only generate \
-a controller and a corresponding view.
 
-To generate based on a get route for the path /apples:\
-```ruby
-rubee generate get /apples # or rubee gen get /apples
-```
+As long as a route has a `model:` key, you can use it to generate initial model files. If only `path` and `to:` are defined, only a controller and view will be generated.
 
-To generate base on a patch request for the path /apples/{id}:\
-```ruby
-rubee generate patch /apples/{id} # or rubee gen patch /apples/{id}
+```bash
+rubee generate get /apples           # or: rubee gen get /apples
+rubee generate patch /apples/{id}    # or: rubee gen patch /apples/{id}
 ```
 
-Example:
+**Example 1** — route without a model:
 ```ruby
-Rubee::Router.draw do |router|
-  ...
-  # draw the contract
-  router.get "/apples", to: "apples#index"
-end
+router.get "/apples", to: "apples#index"
 ```
-Will Generate:
+Generates:
 ```bash
-./app/controllers/apples_controller.rb # Controller with respective action
-./app/views/apples_index.erb # ERB view that is rendered by the controller right away
+./app/controllers/apples_controller.rb
+./app/views/apples_index.erb
 ```
 
-Example 2:
+**Example 2** — route with a model name only:
 ```ruby
-Rubee::Router.draw do |router|
-  ...
-  # draw the contract
-  router.get "/apples", to: "apples#index", model: { name: 'apple' }
-end
+router.get "/apples", to: "apples#index", model: { name: 'apple' }
 ```
-
-Will generate:
+Generates:
 ```bash
-./app/controllers/apples_controller.rb # Controller with respective action
-./app/views/apples_index.erb # ERB view that is rendered by the controller right away
-./app/models/apple.rb # Model that acts as ORM
-./db/create_apples.rb # Database migration file needed for creating repsective table
+./app/controllers/apples_controller.rb
+./app/views/apples_index.erb
+./app/models/apple.rb
+./db/create_apples.rb
 ```
 
-Example 3:
+**Example 3** — route with full model attributes:
 ```ruby
-Rubee::Router.draw do |router|
-  ...
-  # draw the contract
-  router.get "/apples", to: "apples#index",
-    model: {
-      name: 'apple',
-      attributes: [
-        { name: 'id', type: :primary },
-        { name: 'colour', type: :string },
-        { name: 'weight', type: :integer },
-        { name: 'created', type: :datetime },
-        { name: 'updated', type: :datetime },
-      ]
-    }
-end
-```
-
-Will generate:
+router.get "/apples", to: "apples#index",
+  model: {
+    name: 'apple',
+    attributes: [
+      { name: 'id', type: :primary },
+      { name: 'colour', type: :string },
+      { name: 'weight', type: :integer },
+      { name: 'created', type: :datetime },
+      { name: 'updated', type: :datetime },
+    ]
+  }
+```
+Generates:
 ```bash
-./app/controllers/apples_controller.rb # Controller with respective action
-./app/models/apple.rb # Model that acts as ORM
-./app/views/apples_index.erb # ERB view that is rendered by the controller right away
-./db/create_apples.rb # Database migration file needed for creating repsective table
+./app/controllers/apples_controller.rb
+./app/models/apple.rb
+./app/views/apples_index.erb
+./db/create_apples.rb
 ```
 
+### Modular application
 
-### Modualar application
-
-You can also use ru.Bee to create modular applications.\
-And attach as many subprojects you need.
-Main philosophy of attach functinality is to keep the main project clean and easy to maintain. It will still\
-share data with the main app. So where to define a border between the main app and subprojects is up to developer.
-Howerver by attching new subproject you will get a new folder and files configured and namespaced respectively.
-
-So if you need to extend your main app with a separate project, you can do it easily in ruBEE.
-1. Attach new subrpoject
+ru.Bee supports modular applications — attach as many subprojects as you need. Each subproject gets its own folder, MVC setup, routes, and namespacing, while still sharing data with the main app.
 
+1. Attach a new subproject
 ```bash
 rubee attach admin
 ```
-This will create a dedicated folder in the project root called admin and all the MVC setup, route and configuraion \
-files will be created there.
 
 2. Add routes
-
 ```ruby
 # admin_routes.rb
 Rubee::Router.draw do |router|
-  ...
-  # draw the contract
-  router.get '/admin/cabages', to: 'cabages#index',
+  router.get '/admin/cabbages', to: 'cabbages#index',
                                model: {
-                                 name: 'cabage',
+                                 name: 'cabbage',
                                  attributes: [
                                    { name: 'id', type: :primary },
                                    { name: 'name', type: :string },
@@ -739,59 +688,51 @@ Rubee::Router.draw do |router|
                                    { name: 'updated', type: :datetime },
                                  ]
                                },
-                               namespace: :admin # mandatory option for supporting namespacing
+                               namespace: :admin  # mandatory for namespacing support
 end
 ```
 
-3. Run gen command
-
+3. Run the generate command
 ```bash
-rubee gen get /admin/cabages app:admin
+rubee gen get /admin/cabbages app:admin
 ```
-
-This will generate the bolierplate files:
-
+Generates:
 ```bash
-./admin/controllers/cabages_controller.rb
-./admin/views/cabages_index.erb
-./admin/models/cabage.rb
-./db/create_cabages.rb
+./admin/controllers/cabbages_controller.rb
+./admin/views/cabbages_index.erb
+./admin/models/cabbage.rb
+./db/create_cabbages.rb
 ```
 
-4. Perform migrations
-
+4. Run the migration
 ```bash
-rubee db run:create_cabages
+rubee db run:create_cabbages
 ```
 
-5. Fill the views and controller with the content
-
+5. Fill the controller with content
 ```ruby
-# ./admin/controllers/cabages_controller.rb
-class Admin::CabagesController < Rubee::BaseController
+# ./admin/controllers/cabbages_controller.rb
+class Admin::CabbagesController < Rubee::BaseController
   def index
-    response_with object: Cabage.all, type: :json
+    response_with object: Cabbage.all, type: :json
   end
 end
 ```
 
-6. Run the rubee server
-
+6. Run the server
 ```bash
-rubee start # or rubee start_dev for development
+rubee start  # or rubee start_dev for development
 ```
 
 [Back to content](#content)
 
 ## Views
-View in ru.Bee is just a plain html/erb/react file that can be rendered from the controller.
 
-## Templates over erb
+A view in ru.Bee is a plain HTML, ERB, or React file rendered from the controller.
 
-You can use erb as a template engine in the views.
+### Templates with ERB
 
-layout.erb is the parent template that is rendered first and then the child templates are rendered inside it.
-Feel free to include you custom css and js files in the this file.
+`layout.erb` is the parent template rendered first; child templates are rendered inside it. Feel free to include custom CSS and JS files there.
 
 ```ruby
 # app/controllers/welcome_controller.rb
@@ -804,80 +745,67 @@ end
 ```
 
 ```erb
-# app/views/welcome_header.erb
+<%# app/views/welcome_header.erb %>
 
 <h1>All set up and running!</h1>
 ```
 
 ```erb
-# app/views/welcome_show.erb
+<%# app/views/welcome_show.erb %>
 
 <div class="container">
-    <%= render_template :welcome_header %> # you can easily attach erb temlate using render_template method
-    <p><%= locals[:object][:message] %></p> # displaying, passed in the controller object
+    <%= render_template :welcome_header %> <%# attach an ERB partial with render_template %>
+    <p><%= locals[:object][:message] %></p> <%# display the object passed from the controller %>
 </div>
 ```
 
-## React as a view
-
-React is supported out of the box in the rubee view.
-Make react as a view representation layer is easy.
+### React as a view
 
-Prerequisites: Node and NPM are required
+React is supported out of the box as a view layer in ru.Bee.
 
-1. Make sure after creating project and bundling you have installed react dependencies by
+Prerequisites: Node and NPM are required.
 
+1. After creating your project and bundling, install React dependencies:
 ```bash
-rubee react prepare # this will install react related node modules
+rubee react prepare
 ```
 
-2. Make sure you have configured react in the configuration file
-
+2. Configure React in `config/base_configuration.rb`:
 ```ruby
-# config/base_configuration/rb
 Rubee::Configuration.setup(env = :development) do |config|
   config.database_url = { url: 'sqlite://db/development.db', env: }
 
-  # this line registers react as a view
+  # register React as a view
   config.react = { on: true, env: }
 end
 ```
 
-3. Start server by
-
+3. Start the server:
 ```bash
 rubee start
-# It will start to server on port 7000 (default)
-# You can change it by
-
+# Default port is 7000. To change it:
 rubee start --port=3000
 ```
 
-3. Open your browser and navigate to http://localhost:3000/home
-
-4. You will see the react app running in the browser.
+4. Open your browser and navigate to http://localhost:3000/home.
 
-5. For development purposes make sure you run `rubee start_dev` and in other terminal window run `rubee react watch`.
-So that will ensure all cahnges applying instantly.
+5. For development, run `rubee start_dev` in one terminal and `rubee react watch` in another. Changes apply instantly.
 
-6. You can generate react view from the route by indicating the view name explicitly
-
-7. Do not forget to rebuild react app in production by running `rubee react build`. This is unnecessary in development,
-when you use `rubee react watch` tho. So it does rebuild automatically.
+6. In production, rebuild the React app with `rubee react build`. Not needed in development when using `rubee react watch`.
 
+7. Generate a React view from a route by specifying the view name:
 ```ruby
 # config/routes.rb
 Rubee::Router.draw do |router|
-  router.get('/', to: 'welcome#show') # override it for your app
+  router.get('/', to: 'welcome#show')
 
   router.get('/api/users', to: 'user#index', react: { view_name: 'users.tsx' })
-  # Please note /api/users here is the backend endpoint
-  # For rendering generated /app/views/users.tsx file, you need to update react routes
+  # Note: /api/users is the backend endpoint.
+  # To render /app/views/users.tsx, update the React routes as shown below.
 end
 ```
 
-7. Add logic to generated api controller
-
+8. Add logic to the generated API controller:
 ```ruby
 # app/controllers/api/user_controller.rb
 class Api::UserController < Rubee::BaseController
@@ -886,8 +814,8 @@ class Api::UserController < Rubee::BaseController
   end
 end
 ```
-8. Register path in react routes
 
+9. Register the path in React routes:
 ```javascript
 // app/views/app.tsx
 <Router>
@@ -897,10 +825,10 @@ end
   </Routes>
 </Router>
 ```
-9. Fetch data from the backend in the users.tsx react component and display it in the browser http://localhost:3000/users
 
+10. Fetch data from the backend in the component:
 ```javascript
-# app/views/users.tsx
+// app/views/users.tsx
 import { useState, useEffect } from 'react';
 
 function Users() {
@@ -923,22 +851,20 @@ function Users() {
     </div>
   );
 }
-
 ```
+
 [Back to content](#content)
 
 ## Object hooks
 
-In ru.Bee by extending Hookable module any Ruby object can be charged with hooks (logic),
-that can be executed before, after and around a specific method execution.
+By including the `Hookable` module, any Ruby object can be charged with hooks — logic that executes before, after, or around a specific method call.
 
-Here below a controller example. However it can be used in any Ruby object, like Model etc.
+`BaseController` is Hookable by default:
 ```ruby
-# base conrteoller is hopokable by Default
 class ApplesController < Rubee::BaseController
-  before :index, :print_hello # you can useinstance method as a handler
-  after :index, -> { puts "after index" }, if: -> { true } # or you can use lambda
-  after :index, -> { puts "after index2" }, unless: -> { false } # if, unless guards may accept method or lambda
+  before :index, :print_hello                                       # use an instance method as a handler
+  after  :index, -> { puts "after index" },  if:     -> { true }   # or use a lambda
+  after  :index, -> { puts "after index2" }, unless: -> { false }  # if/unless guards accept a method or lambda
   around :index, :log
 
   def index
@@ -950,18 +876,17 @@ class ApplesController < Rubee::BaseController
   end
 
   def log
-    puts "before log aroud"
+    puts "before log around"
     res = yield
     puts "after log around"
     res
   end
-  ...
 end
 ```
-Then, in the server logs we could see next execution stack
 
+The server logs will show the following execution stack:
 ```bash
-before log aroud
+before log around
 hello!
 after index
 after index2
@@ -969,12 +894,11 @@ after log around
 127.0.0.1 - - [17/Feb/2025:11:42:14 -0500] "GET /apples HTTP/1.1" 401 - 0.0359
 ```
 
-Starting from ver 1.11 hooks are able to be pinned to class methods.
-
+Starting from version 1.11, hooks can also be pinned to class methods:
 ```ruby
 class AnyClass
   include Rubee::Hookable
-  before :print_world, :print_hello, class_methods: true # you can use class method as a handler
+  before :print_world, :print_hello, class_methods: true
 
   class << self
     def print_world
@@ -987,6 +911,8 @@ class AnyClass
   end
 end
 ```
+
+Output:
 ```bash
 hello!
 world!
@@ -996,8 +922,9 @@ world!
 
 ## Validations
 
-In ru.Bee any class can be charged with validations. This is done by including Validatable module.
-Please note, ru.Bee model is validatable by default. No need to include it explicitly.
+Any class can be charged with validations by including the `Validatable` module.
+ru.Bee models are validatable by default — no need to include it explicitly.
+
 ```ruby
 class Foo
   include Rubee::Validatable
@@ -1013,51 +940,32 @@ class Foo
     attribute(:name).required.type(String).condition(->{ name.length > 2 })
 
     attribute(:age)
-      .required('Age is a manadatory field')
-      .type(Integer, error_message: 'Must be an integerRRRRRRrrr!')
-      .condition(->{ age > 18 }, fancy_error: 'You must be at least 18 years old, dude!')
+      .required('Age is a mandatory field')
+      .type(Integer, error_message: 'Must be an integer!')
+      .condition(->{ age > 18 }, fancy_error: 'You must be at least 18 years old!')
   end
 end
 ```
-Then we can evaluate it in the ru.Bee console
+
 ```bash
-=> #<Proc:0x000000010d389d80 (irb):32>
-irb(main):041> Foo.new("Test", 20)
-=> #<Foo:0x000000010d383fc0 @__validation_state=#<Rubee::Validatable::State:0x000000010d383de0 @errors={}, @valid=true>, @age=20, @name="Test">
-irb(main):042> Foo.new("Test", 1)
-=>
-#<Foo:0x000000010ce61c40
- @__validation_state=#<Rubee::Validatable::State:0x000000010ce61bc8 @errors={age: {fancy_error: "You must be at least 18 years old, dude!"}}, @valid=false>,
- @age=1,
- @name="Test">
-irb(main):043> Foo.new("Test", nil)
-=>
-#<Foo:0x000000010c46f200
- @__validation_state=#<Rubee::Validatable::State:0x000000010c46f070 @errors={age: {message: "Age is a manadatory field"}}, @valid=false>,
- @age=nil,
- @name="Test">
-irb(main):044> Foo.new("Te", 20)
-=>
-#<Foo:0x000000010cfe9270
- @__validation_state=#<Rubee::Validatable::State:0x000000010cfe91f8 @errors={name: {message: "condition is not met"}}, @valid=false>,
- @age=20,
- @name="Te">
-irb(main):045> foo = Foo.new("Joe", "wrong")
-=>
-#<Foo:0x000000010d32eb38
-...
-irb(main):046> foo.valid?
+irb(main):041> Foo.new("Test", 20).valid?
+=> true
+irb(main):042> Foo.new("Test", 1).errors
+=> {age: {fancy_error: "You must be at least 18 years old!"}}
+irb(main):046> Foo.new("Joe", "wrong").valid?
 => false
-irb(main):047> foo.errors
-=> {age: {error_message: "Must be an integerRRRRRRrrr!"}}
+irb(main):047> Foo.new("Joe", "wrong").errors
+=> {age: {error_message: "Must be an integer!"}}
 ```
-Model example
+
+Model example with persistence guards:
 ```ruby
 class User < Rubee::SequelObject
   attr_accessor :id, :email, :password, :created
 
-  validate_after_setters # This will run validation after each setter.
-  validate_before_persist! # This will validate and raise error in case invalid before saving to DB
+  validate_after_setters    # runs validation after each setter
+  validate_before_persist!  # validates and raises an error if invalid before saving
+
   validate do
     attribute(:email).required
       .condition(
@@ -1066,117 +974,86 @@ class User < Rubee::SequelObject
   end
 end
 ```
+
 ```bash
-irb(main):074> user = User.new(email: "wrong", password: 123)
-=>
-#<User:0x000000010d2c3e78
-...
-irb(main):075> user.valid?
-=> false
-irb(main):076> user.errors
-=> {email: {error: "Wrong email format"}}
 irb(main):077> user.save
-=>{email: {error: "Wrong email format"}} (Rubee::Validatable::Error) ..
+=> {email: {error: "Wrong email format"}} (Rubee::Validatable::Error)
 irb(main):078> user.email = "ok@ok.com"
-=> "ok@ok.com"
-irb(main):079> user.valid?
-=> true
 irb(main):080> user.save
 => true
-irb(main):081> user
-=>
-#<User:0x000000010d2c3e78
- @__validation_state=#<Rubee::Validatable::State:0x000000010cb28628 @errors={}, @valid=true>,
- @created=2025-11-30 17:18:52.254197 -0500,
- @email="ok@ok.com",
- @id=2260,
- @password=123,
- @updated=2025-11-30 17:18:52.254206 -0500>
-```
-If you want to apply validation_before_persist! and validation_after_setters globally,
-add init/sequle_object_preloader.rb(you can chose any name)
-file withing set up those methods
-for Rubee::SequelObject parent class by adding:
-```
-Rubee::SequelObject.validate_befor_persist!
+```
+
+To apply `validate_before_persist!` and `validate_after_setters` globally, add an initializer such as `init/sequel_object_preloader.rb`:
+```ruby
+Rubee::SequelObject.validate_before_persist!
 Rubee::SequelObject.validate_after_setters
 ```
-So you shouldn't add it to each model again and again.
+
 [Back to content](#content)
 
 ## Rubee support
 
-In Rubee you have an optional way to charge your code with usefull methods that added to base Ruby classes.
-You can add them to your project globally by setting up it in configuration.
+An optional set of useful methods can be added to base Ruby classes globally via configuration:
 
 ```ruby
-# To include all support methods
+# Include all support methods
 Rubee::Configuration.setup do |config|
   config.rubee_support = { all: true }
 end
 
-# To include only those who belong to a indicated class
+# Include only methods for a specific class
 Rubee::Configuration.setup do |config|
   config.rubee_support = { classes: [Rubee::Support::String] }
-  # So only String will be charged with support methods
 end
 ```
-Here are list of additionl APIs extended for:
 
-```ruby
-# By adding to configuration Rubee::Suport::Hash class or just applying all, Hash will tollerate string or symbol keys.
-{one: 1}[:one] # => 1
-{one: 1}["one"] # => 1
-```
+Available extensions:
 
-# By adding to configuration Rubee::Support::String or just applying all, String will be enriched with handy helper methods.
 ```ruby
-"test".pluralize # => "tests"
-"test".singularize # => "test"
-"test".camelize # => "Test"
-"TestMe".snakeize # => "test_mei"
-"test".singular? # => true
-"test".plural? # => false
+# Hash — tolerates string or symbol keys interchangeably
+{one: 1}[:one]   # => 1
+{one: 1}["one"]  # => 1
+
+# Hash — deep digging
+{one: {two: 2}}.deep_dig(:two)  # => 2
 ```
 
 ```ruby
-{one: {two: 2}}.deep_dig(:two) # => 2
+# String — enriched with helper methods
+"test".pluralize   # => "tests"
+"test".singularize # => "test"
+"test".camelize    # => "Test"
+"TestMe".snakeize  # => "test_me"
+"test".singular?   # => true
+"test".plural?     # => false
 ```
 
 [Back to content](#content)
 
+## JWT based authentication
 
+Include the `AuthTokenable` module in your controller and authenticate any action you need.
 
-## JWT based authentification
-
-Charge you rpoject with token based authentification system and customize it for your needs.
-include AuthTokenable module to your controller and authentificate any action you need.
-
-Make sure you have initiated User model which is a part of the logic.
+First, initialize the User model:
 ```bash
 rubee db run:create_users
 ```
-This will create table users and initiate first user with demo credentials.
-email: "ok@ok.com", password: "password"
-Feel free to customize it in the /db/create_users.rb file before running migration.
-Please note user model is default but are free to use any model you need. See more examples below.
 
-Then in the controller you can include the AuthTokenable module and use its methods:
+This creates the `users` table and seeds it with demo credentials — email `ok@ok.com`, password `password`. Customize `/db/create_users.rb` before running the migration if needed.
+
 ```ruby
 class UsersController < Rubee::BaseController
   include Rubee::AuthTokenable
-  # List methods you want to restrict
-  auth_methods :index # unless the user is authentificated it will return unauthentificated
+  auth_methods :index  # unauthenticated requests to these actions will be rejected
 
-  # GET /users/login (login form page)
+  # GET /users/login
   def edit
     response_with
   end
 
-  # POST /users/login (login logic)
+  # POST /users/login
   def login
-    if authentificate! # AuthTokenable method that init @token_header
-      # Redirect to restricted area, make sure headers: @token_header is passed
+    if authenticate!  # initializes @token_header
       response_with type: :redirect, to: "/users", headers: @token_header
     else
       @error = "Wrong email or password"
@@ -1184,92 +1061,57 @@ class UsersController < Rubee::BaseController
     end
   end
 
-  # POST /usres/logout (logout logic)
+  # POST /users/logout
   def logout
-    unauthentificate! # AuthTokenable method aimed to handle logout action.
-    # Make sure @zeroed_token_header is paRssed within headers options
+    unauthenticate!
     response_with type: :redirect, to: "/users/login", headers: @zeroed_token_header
   end
 
-  # GET /users (restricted endpoint)
+  # GET /users (restricted)
   def index
     response_with object: User.all, type: :json
   end
 end
 ```
-For security reason it is recommended to initialize JWT_KEY while starting ru.Bee application.
+
+Set a `JWT_KEY` at startup for security:
 ```bash
 JWT_KEY=SDJwer0wer23j rubee start
 ```
-User is a default model for validation but using it is not a mandatory. You can use any model you need by
-passing arguments to authentificate! and unauthentificate! methods.
 
+To use a custom model instead of the default `User`, pass arguments to `authenticate!` and `unauthenticate!`:
 ```ruby
-class Client < Sequel::Model
-  attr_accessor :id, :name, :digest_password, :created, :updated
+if authenticate! user_model: Client, login: :name, password: :digest_password
+  response_with type: :redirect, to: "/clients", headers: @token_header
 end
-
-class ClientController < Rubee::BaseController
-  include Rubee::AuthTokenable
-  # List methods you want to restrict
-  auth_methods :index
-
-  # GET /clinets/login (login form page)
-  def edit
-    response_with
-  end
-
-  # POST /clients/login (login logic)
-  def login
-    if authentificate! user_model: Client, login: :name, password: :digest_password
-      response_with type: :redirect, to: "/clinets", headers: @token_header
-    else
-      @error = "Wrong login or password"
-      response_with render_view: "clinets_edit"
-    end
-  end
-
-  # POST /clinets/logout
-  def logout
-    unauthentificate! user_model: Client, login: :name, password: :digest_password
-    response_with type: :redirect, to: "/clients/login", headers: @zeroed_token_header
-  end
-
-  # GET /clinets (restricted endpoint)
-  def index
-    response_with object: Client.all, type: :json
-  end
-end
-
 ```
 
 [Back to content](#content)
 
-## OAuth authentification
-If you want to plug in the OAuth 2.0 authentication, you can use the following code using OAuth2 gem:
-First thing you need to do is to add the gem to your Gemfile
+## OAuth authentication
+
+To plug in OAuth 2.0 authentication, add the `oauth2` gem to your Gemfile:
 ```bash
 gem 'oauth2'
 ```
-Then use down below code as an example and add yours to your controller
+
+Use the following as a starting point:
 ```ruby
 class UsersController < Rubee::BaseController
   include Rubee::AuthTokenable
 
-  REDIRECT_URI = 'https://mysite.com/users/outh_callback'
-  CLIENT_ID = ENV['GOOGLE_CLIENT_ID']
+  REDIRECT_URI  = 'https://mysite.com/users/oauth_callback'
+  CLIENT_ID     = ENV['GOOGLE_CLIENT_ID']
   CLIENT_SECRET = ENV['GOOGLE_CLIENT_SECRET']
 
-  # GET /login (login form page)
+  # GET /login
   def edit
     response_with
   end
 
-  # POST /users/login (login logic)
+  # POST /users/login
   def login
-    Rubee::Logger.info(message: "Login attempt for user #{params[:email]}")
-    if authentificate! # AuthTokenable method that init @token_header
-      Rubee::Logger.info(message: "Successful login for user #{@authentificated_user.email}")
+    if authenticate!
       response_with(type: :redirect, to: "/sections", headers: @token_header)
     else
       @error = "Wrong email or password"
@@ -1277,8 +1119,8 @@ class UsersController < Rubee::BaseController
     end
   end
 
-  # GET /users/outh_login
-  def outh_login
+  # GET /users/oauth_login
+  def oauth_login
     response_with(
       type: :redirect,
       to: auth_client.auth_code.authorize_url(
@@ -1288,40 +1130,35 @@ class UsersController < Rubee::BaseController
     )
   end
 
-  # GET /users/outh_callback
-  def outh_callback
-    code = params[:code]
-    token = auth_client.auth_code.get_token(code, redirect_uri: REDIRECT_URI)
+  # GET /users/oauth_callback
+  def oauth_callback
+    code      = params[:code]
+    token     = auth_client.auth_code.get_token(code, redirect_uri: REDIRECT_URI)
     user_info = JSON.parse(token.get('https://www.googleapis.com/oauth2/v1/userinfo?alt=json').body)
-    Rubee::Logger.debug(object: user_info, method: "outh_callback", class: "UsersController")
 
     user = User.where(email: user_info['email'])&.last
-    unless user
-      raise "User with email #{user_info['email']} not found"
-    end
+    raise "User with email #{user_info['email']} not found" unless user
 
-    params[:email] = user_info['email']
+    params[:email]    = user_info['email']
     params[:password] = user.password
 
-    if authentificate! # AuthTokenable method that init @token_header
-      Rubee::Logger.info(message: "Successful Outh login for user #{@authentificated_user.email}")
+    if authenticate!
       response_with(type: :redirect, to: "/sections", headers: @token_header)
     else
       @error = "Something went wrong"
       response_with(render_view: "users_edit")
     end
-  rescue OAuth2::Error => e
+  rescue OAuth2::Error
     @error = "OAuth login failed"
     response_with(render_view: "users_edit")
-  rescue StandardError => e
+  rescue StandardError
     @error = "Something went wrong"
     response_with(render_view: "users_edit")
   end
 
-  # POST /users/logout (logout logic)
+  # POST /users/logout
   def logout
-    unauthentificate! # AuthTokenable method aimed to handle logout action.
-    # Make sure @zeroed_token_header is paRssed within headers options
+    unauthenticate!
     response_with(type: :redirect, to: "/login", headers: @zeroed_token_header)
   end
 
@@ -1331,9 +1168,9 @@ class UsersController < Rubee::BaseController
     @client ||= OAuth2::Client.new(
       CLIENT_ID,
       CLIENT_SECRET,
-      site: 'https://accounts.google.com',
+      site:          'https://accounts.google.com',
       authorize_url: '/o/oauth2/auth',
-      token_url: 'https://oauth2.googleapis.com/token'
+      token_url:     'https://oauth2.googleapis.com/token'
     )
   end
 end
@@ -1342,76 +1179,83 @@ end
 [Back to content](#content)
 
 ## ru.Bee commands
+
 ```bash
-rubee start # start the server
-rubee start_dev # start the server in dev mode, which restart server on changes
-rubee react prepare # install react dependencies
-rubee react watch # dev mode for react, works together with start_dev
-rubee stop # stop the server
-rubee restart # restart the server
+rubee start          # start the server
+rubee start_dev      # start the server in dev mode, restarting on file changes
+rubee react prepare  # install React dependencies
+rubee react watch    # React dev mode, use together with start_dev
+rubee stop           # stop the server
+rubee restart        # restart the server
 ```
 
 ## Generate commands
+
 ```bash
-rubee generate get /apples # generate controller view, model and migration if set in the routes
+rubee generate get /apples  # generate controller, view, model, and migration if set in routes
+rubee gen get /apples        # shorthand alias
 ```
 
-## Migraiton commands
+## Migration commands
+
 ```bash
-rubee db run:all # run all migrations
-rubee db run:create_apples # where create_apples is the name of the migration file, located in /db folder
-rubee db structure # generate migration file for the database structure
+rubee db run:all              # run all migrations
+rubee db run:create_apples    # run a specific migration file from /db
+rubee db structure            # generate a migration file for the database structure
 ```
 
 ## ru.Bee console
+
 ```bash
-rubee console # start the console
-# you can reload the console by typing reload, so it will pick up latest changes
+rubee console  # start the interactive console
+# type 'reload' inside the console to pick up the latest changes
 ```
 
-## Testing
+To run any ru.Bee command in a specific environment, prefix with the env variable:
 ```bash
-rubee test # run all tests
-rubee test auth_tokenable_test.rb # run specific tests
+RACK_ENV=test rubee console
 ```
 
-[Back to content](#content)
-
-
-If you want to run any ru.Bee command within a specific ENV make sure you added it before a command.
-For instance if you want to run console in test environment you need to run the following command
+## Testing
 
 ```bash
-RACK_ENV=test rubee console
+rubee test                                          # run all tests
+rubee test auth_tokenable_test.rb                   # run a specific test file
+rubee test models/user_model_test.rb --line=12      # run a specific line
 ```
 
+[Back to content](#content)
+
 ## Background jobs
-Set your background job engine with ease!
 
 ### Sidekiq engine
-1. Add sidekiq to your Gemfile
+
+1. Add Sidekiq to your Gemfile
 ```bash
 gem 'sidekiq'
 ```
-2. Configure adapter for desired env
+
+2. Configure the adapter for the desired environment
 ```ruby
 # config/base_configuration.rb
-
-Rubee::Configuration.setup(env=:development) do |config|
-  config.database_url = { url: "sqlite://db/development.db", env: }
+Rubee::Configuration.setup(env = :development) do |config|
+  config.database_url  = { url: "sqlite://db/development.db", env: }
   config.async_adapter = { async_adapter: SidekiqAsync, env: }
 end
 ```
-3. Bundle up
+
+3. Install dependencies
 ```bash
 bundle install
 ```
-4. Make sure redis is installed and running
+
+4. Start Redis
 ```bash
 redis-server
 ```
-5. Add sidekiq configuration file
-```bash
+
+5. Add a Sidekiq configuration file
+```yaml
 # config/sidekiq.yml
 
 development:
@@ -1422,12 +1266,13 @@ development:
     low:
     high:
 ```
-6. Create sidekiq worker
+
+6. Create a Sidekiq worker
 ```ruby
 # app/async/test_async_runner.rb
 require_relative 'extensions/asyncable' unless defined? Asyncable
 
-class TestAsyncRunnner
+class TestAsyncRunner
   include Rubee::Asyncable
   include Sidekiq::Worker
 
@@ -1438,18 +1283,21 @@ class TestAsyncRunnner
   end
 end
 ```
-7. Use it in the code base
+
+7. Use it in your codebase
 ```ruby
-TestAsyncRunnner.new.perform_async(options: {"email"=> "new@new.com", "password"=> "123"})
+TestAsyncRunner.new.perform_async(options: { "email" => "new@new.com", "password" => "123" })
 ```
 
-### Default engine is ThreadAsync
-However it is not yet recommended for production. Use it with cautions!
-1. Do not define any adapter in the /config/base_configuration.rb file, so default ThreadAsync will be taken.
-2. Just create a worker and process it.
+### Default engine — ThreadAsync
+
+The default adapter is `ThreadAsync`. It is not yet recommended for production — use with caution.
+
+1. Do not define any adapter in `config/base_configuration.rb`; the default `ThreadAsync` will be used.
+2. Create a worker and process it:
 ```ruby
 # test_async_runner.rb
-class TestAsyncRunnner
+class TestAsyncRunner
   include Rubee::Asyncable
 
   def perform(options)
@@ -1457,32 +1305,29 @@ class TestAsyncRunnner
   end
 end
 
-TestAsyncRunnner.new.perform_async(options: {"email"=> "new@new.com", "password"=> "123"})
+TestAsyncRunner.new.perform_async(options: { "email" => "new@new.com", "password" => "123" })
 ```
 
 [Back to content](#content)
 
-### Logger
-
-You can use your own logger by setting it in the /config/base_configuration.rb.
+## Logger
 
+Use your own logger by setting it in `config/base_configuration.rb`:
 ```ruby
-# config/base_configuration.rb
-Rubee::Configuration.setup(env=:development) do |config|
+Rubee::Configuration.setup(env = :development) do |config|
   config.database_url = { url: "sqlite://db/development.db", env: }
-  config.logger = { logger: MyLogger, env: }
+  config.logger       = { logger: MyLogger, env: }
 end
 ```
 
-Or you can use the default logger.
-Let's consider example with welcome controller and around hook:
+Or use the built-in logger with its full set of levels:
 ```ruby
 # app/controllers/welcome_controller.rb
 class WelcomeController < Rubee::BaseController
   around :show, ->(&target_method) do
     start = Time.now
     Rubee::Logger.warn(message: 'This is a warning message', method: :show, class_name: 'WelcomeController')
-    Rubee::Logger.error(message: 'This is a warning message', class_name: 'WelcomeController')
+    Rubee::Logger.error(message: 'This is an error message', class_name: 'WelcomeController')
     Rubee::Logger.critical(message: 'We are on fire!')
     target_method.call
     Rubee::Logger.info(
@@ -1498,145 +1343,213 @@ class WelcomeController < Rubee::BaseController
   end
 end
 ```
-When you trigger the controller action, the logs will look like this:
 
+Output:
 ```bash
-[2025-04-26 12:32:33] WARN [method: show][class_name: WelcomeController] This is a warning message
-[2025-04-26 12:32:33] ERROR [class_name: WelcomeController] This is a warning message
+[2025-04-26 12:32:33] WARN     [method: show][class_name: WelcomeController] This is a warning message
+[2025-04-26 12:32:33] ERROR    [class_name: WelcomeController] This is an error message
 [2025-04-26 12:32:33] CRITICAL We are on fire!
-[2025-04-26 12:32:33] INFO [method: show][class_name: WelcomeController] Execution Time: 0.000655 seconds
-[2025-04-26 12:32:33] DEBUG [method: show][class_name: WelcomeController] #<User:0x000000012c5c63e0 @id=4545, @email="ok@op.com", @password="123">
+[2025-04-26 12:32:33] INFO     [method: show][class_name: WelcomeController] Execution Time: 0.000655 seconds
+[2025-04-26 12:32:33] DEBUG    [method: show][class_name: WelcomeController] #<User:0x000000012c5c63e0 ...>
 ```
 
 [Back to content](#content)
 
-## Websocket
+## WebSocket
 
-With ru.Bee 2.0.0 you can use Websocket with ease!
+With ru.Bee 2.0.0 you can use WebSocket with ease.
 
-Here are steps to get started:
-1. Make sure redis server is installed and running
-````bash
-sudo apt-get install -y redis # linux
-brew install redis # osx
-````
-2. Enable websocket and redis to your Gemfile
+1. Install and start Redis
 ```bash
+sudo apt-get install -y redis  # Linux
+brew install redis              # macOS
+```
+
+2. Add the required gems to your Gemfile
+```ruby
 gem 'ru.Bee'
 gem 'redis'
 gem 'websocket'
 ```
-3. Add the redis url to your configuration file, unless it connects to 127.0.0.1:6379
+
+3. Add the Redis URL to your configuration, unless it defaults to `127.0.0.1:6379`
 ```ruby
 # config/base_configuration.rb
-Rubee::Configuration.setup(env=:development) do |config|
-#...
+Rubee::Configuration.setup(env = :development) do |config|
+  ...
   config.redis_url = { url: "redis://localhost:6378/0", env: }
 end
 ```
-3. Add webscoket entry connection route
+
+4. Add a WebSocket entry route
 ```ruby
 # config/routes.rb
 Rubee::Router.draw do |router|
-#...
-  router.get('/ws', to: 'users#websocket') # entry point to start websocket session
-  # So, const ws = new WebSocket("ws://website/ws"); on the client side, should establish the connection
+  ...
+  router.get('/ws', to: 'users#websocket')
+  # On the client: const ws = new WebSocket("ws://website/ws");
 end
 ```
-4. Make model pubsubable
+
+5. Make the model pub/sub capable
 ```ruby
 # app/models/user.rb
 class User < Rubee::BaseModel
   include Rubee::PubSub::Publisher
   include Rubee::PubSub::Subscriber
-  #...
+  ...
 end
 ```
-5. Enable websocket in your controller and implement required methods
+
+6. Enable WebSocket in your controller and implement the required methods
 ```ruby
 # app/controllers/users_controller.rb
 class UsersController < Rubee::BaseController
-  attach_websocket! # this will handle websocket connections and direct them to the controller methods: publish, subscribe, unsubscribe
-
+  attach_websocket!  # handles WebSocket connections and routes them to publish, subscribe, unsubscribe
 
-  # Subscribe is expected to get next params from the client:
-  # { action: 'subscribe', 'channel': 'default', 'id': '123', 'subscriber': 'User' }
-  # where
-  # - action corresponds to the method name
-  # - channel is the name of the channel
-  # - id is the id of the user
-  # - subscriber is the name of the model
+  # Expected client params: { action: 'subscribe', channel: 'default', id: '123', subscriber: 'User' }
   def subscribe
-    channel = params[:channel]
-    sender_id = params[:options][:id] # id moved to options
-    io = params[:options][:io] # io is a websocket connection
+    channel   = params[:channel]
+    sender_id = params[:options][:id]
+    io        = params[:options][:io]
 
-    User.sub(channel, sender_id, io) do |channel, args| # subscribe the user for the channel updates
-      websocket_connections.register(channel, args[:io]) # register the websocket connection
+    User.sub(channel, sender_id, io) do |channel, args|
+      websocket_connections.register(channel, args[:io])
     end
-    # return websocket response
     response_with(object: { type: 'system', channel: params[:channel], status: :subscribed }, type: :websocket)
   rescue StandardError => e
     response_with(object: { type: 'system', error: e.message }, type: :websocket)
   end
 
-  # Unsubscribe is expected to get next params from the client:
-  # { action: 'unsubscribe', 'channel': 'default', 'id': '123', 'subscriber': 'User' }
-  # where
-  # - action corresponds to the method name
-  # - channel is the name of the channel
-  # - id is the id of the user
-  # - subscriber is the name of the model
+  # Expected client params: { action: 'unsubscribe', channel: 'default', id: '123', subscriber: 'User' }
   def unsubscribe
-    channel = params[:channel]
+    channel   = params[:channel]
     sender_id = params[:options][:id]
-    io = params[:options][:io]
+    io        = params[:options][:io]
 
     User.unsub(channel, sender_id, io) do |channel, args|
       websocket_connections.remove(channel, args[:io])
     end
-
     response_with(object: params.merge(type: 'system', status: :unsubscribed), type: :websocket)
   rescue StandardError => e
     response_with(object: { type: 'system', error: e.message }, type: :websocket)
   end
-  # Publish is expected to get next params from the client:
-  # { action: 'publish', 'channel': 'default', 'message': 'Hello world', 'id': '123', 'subscriber': 'User' }
-  # where
-  # - action corresponds to the method name
-  # - channel is the name of the channel
-  # - id is the id of the user
-  # - subscriber is the name of the model
+
+  # Expected client params: { action: 'publish', channel: 'default', message: 'Hello', id: '123', subscriber: 'User' }
   def publish
     args = {}
     User.pub(params[:channel], message: params[:message]) do |channel|
-      # Here we pack args with any additional data client might need
-      user = User.find(params[:options][:id])
-      args[:message] = params[:message]
-      args[:sender] = params[:options][:id]
+      user               = User.find(params[:options][:id])
+      args[:message]     = params[:message]
+      args[:sender]      = params[:options][:id]
       args[:sender_name] = user.email
       websocket_connections.stream(channel, args)
     end
-
     response_with(object: { type: 'system', message: params[:message], status: :published }, type: :websocket)
   rescue StandardError => e
     response_with(object: { type: 'system', error: e.message }, type: :websocket)
   end
 end
 ```
-If you are interested to see chat app example, please check [chat](https://github.com/nucleom42/rubee-chat)
+
+For a full chat application example, see [rubee-chat](https://github.com/nucleom42/rubee-chat).
 
 [Back to content](#content)
+
+## Bee assistant
+
+ru.Bee ships with a built-in CLI assistant called `bee`. It answers questions about the framework directly in your terminal, using a local TF-IDF knowledge base built from the project documentation. Optionally, it routes answers through a local Ollama language model for richer, more conversational responses.
+
+No external API keys or internet connection are required in the default mode.
+
+### Building the knowledge base
+
+Before using the assistant for the first time, generate the knowledge base from the README:
+
+```bash
+rubee bee generate  # or: rubee bee gen
+```
+
+This parses the documentation, computes TF-IDF vectors, and writes a `bee_knowledge.json` file to `lib/rubee/cli/`. Re-run this command any time the documentation is updated.
+
+### Interactive mode
+
+Start an interactive session and ask questions conversationally:
+
+```bash
+rubee bee
+```
+
+```
+  ⬡ ⬢ ⬢  ru.Bee — domestic AI assistant
+  ──────────────────────────────────────────────
+  Ask me anything about the ru.Bee framework.
+  Type exit to leave  •  rubee bee generate to retrain.
+  You: How do I run the server?
+```
+
+Type `exit`, `quit`, `bye`, or `q` to leave the session.
+
+### Single-shot mode
+
+Pass a question directly as a command-line argument to get one answer and exit:
+
+```bash
+rubee bee how do hooks work
+rubee bee what databases are supported
+rubee bee how do I set up JWT authentication
+```
+
+### LLM mode
+
+If you have [Ollama](https://ollama.com) installed and running locally, enable LLM mode for more detailed answers. The assistant retrieves the most relevant documentation and passes it as context to the model.
+
+```bash
+rubee bee --llm                        # interactive mode, default model (qwen2.5:1.5b)
+rubee bee --llm=llama3.2               # interactive mode, specific model
+rubee bee --llm how do hooks work      # single-shot LLM answer
+rubee bee --llm=qwen2.5:0.5b how do I configure WebSocket  # single-shot with specific model
+```
+
+If the specified model is not available locally, the assistant automatically pulls it from Ollama before answering, displaying a live download progress bar.
+
+### Environment options
+
+```bash
+OLLAMA_URL=http://remote-host:11434 rubee bee --llm  # use a custom Ollama endpoint
+BEE_KNOWLEDGE=/path/to/custom.json rubee bee         # use a custom knowledge base file
+BEE_DEBUG=1 rubee bee --llm                          # write LLM debug output to /tmp/bee_ollama_debug.txt
+```
+
+### Suggestions
+
+After every answer, the assistant suggests up to five related topics you might want to explore next, along with a link to the full documentation at https://rubee.dedyn.io/.
+
+### Command reference
+
+```bash
+rubee bee generate                      # build the knowledge base from the README
+rubee bee gen                           # alias for generate
+rubee bee                               # start interactive mode
+rubee bee <question>                    # single-shot answer
+rubee bee --llm                         # interactive LLM mode (default model: qwen2.5:1.5b)
+rubee bee --llm=<model>                 # interactive LLM mode with a specific Ollama model
+rubee bee --llm <question>              # single-shot LLM answer
+rubee bee --llm=<model> <question>      # single-shot with a specific model
+```
+
+[Back to content](#content)
+
 ### Contributing
 
-If you are interested in contributing to ru.Bee,
-please read the [Contributing]()https://github.com/nucleom42/rubee/blob/main/contribution.md) guide.
-Also feel free to open an [issue](https://github.com/nucleom42/rubee/issues) if you apot one.
-Have an idea or you wnat to discuss something?
-Please open a [discussion](https://github.com/nucleom42/rubee/discussions)
+If you are interested in contributing to ru.Bee, please read the [Contributing](https://github.com/nucleom42/rubee/blob/main/contribution.md) guide.
+Feel free to open an [issue](https://github.com/nucleom42/rubee/issues) if you spot one.
+Have an idea or want to discuss something? Open a [discussion](https://github.com/nucleom42/rubee/discussions).
 
 ## Roadmap
-Please refer the [Roadmap](https://github.com/nucleom42/rubee/blob/main/roadmap.md)
+
+Please refer to the [Roadmap](https://github.com/nucleom42/rubee/blob/main/roadmap.md).
 
 ## License
+
 This project is released under the [MIT License](https://github.com/nucleom42/rubee/blob/main/LICENSE).