Feat: Update Dev setup documentation

.mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "4.0.0"

README.md

@@ -24,18 +24,51 @@ EndsideOut staff build a **curriculum** as a set of **programs**. Each program i
 
 Curriculum is delivered through **schools** and their **classrooms**. A classroom enrolls in a program at a given level, and modules are scheduled to publish on specific dates. **Students** belong to a classroom, and their participation is recorded through **student sessions** — giving the organization the statistics and trends it needs to measure impact.
 
-See [DESIGN.md](DESIGN.md) for the full data model and workflow.
+See [Architecture Decision Records (ADRs)](docs/adrs/README.md) for architectural decisions and guidelines.
 
 ## Getting Started 🛠️
 
-Built on **Ruby on Rails 8** with Hotwire, Tailwind, SQLite, and the Solid stack (Queue/Cache/Cable), deployed with Kamal. See [DESIGN.md](DESIGN.md) for the full tech stack.
-
-```sh
-git clone https://github.com/rubyforgood/endsideout.git
-cd endsideout
-bundle install
-bin/rails db:prepare   # create, load schema, seed sample data
-bin/dev                # http://localhost:3000
-```
-
-Seed data is generated with [Faker](https://github.com/faker-ruby/faker); see `db/seeds.rb` for login credentials.
+Built on **Ruby on Rails 8** with Hotwire, Tailwind, SQLite, and the Solid stack (Queue/Cache/Cable), deployed with Kamal.
+
+### Prerequisites
+
+- **[mise](https://mise.jdx.dev/)**: Recommended environment and tool version manager for Ruby (macOS & Linux / WSL2).
+- **libvips**: Native image processing library required by Active Storage.
+  - **macOS**: `brew install libvips`
+  - **Ubuntu/Debian**: `sudo apt-get install -y libvips`
+  - **Fedora**: `sudo dnf install vips`
+  - **Windows**: Use [WSL2 (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install) with Ubuntu/Debian.
+- **SQLite3**: Database engine (pre-installed on macOS).
+
+### Local Setup
+
+1. **Clone the repository**:
+   ```sh
+   git clone https://github.com/rubyforgood/endsideout.git
+   cd endsideout
+   ```
+
+2. **Install Ruby with mise**:
+   ```sh
+   mise install
+   ```
+
+3. **Run setup**:
+   ```sh
+   bin/setup
+   ```
+   This will install gem dependencies, prepare and seed the database, and clear log/temp files.
+
+4. **Start the development server**:
+   ```sh
+   bin/dev
+   ```
+   Visit [http://localhost:3000](http://localhost:3000) in your browser. Seed data is generated with [Faker](https://github.com/faker-ruby/faker); see `db/seeds.rb` for default login credentials.
+
+### Useful Commands
+
+- **Run all CI checks (Recommended before pushing)**: `bin/ci` (runs setup, RuboCop, security audits, and tests)
+- **Run unit & integration tests**: `bin/rails test`
+- **Run system tests**: `bin/rails test:system`
+- **Code style & linting**: `bin/rubocop`
+- **Security audits**: `bin/brakeman`, `bin/bundler-audit`, and `bin/importmap audit`

bin/setup

@@ -12,6 +12,16 @@ FileUtils.chdir APP_ROOT do
   # This script is idempotent, so that you can run it at any time and get an expectable outcome.
   # Add necessary setup steps to this file.
 
+  puts "== Checking system prerequisites =="
+  unless system("vips --version", out: File::NULL, err: File::NULL)
+    puts "\n⚠️  [WARNING] libvips does not appear to be installed on your system."
+    puts "   libvips is required by Active Storage for image processing."
+    puts "   Install it with your package manager:"
+    puts "     macOS: brew install libvips"
+    puts "     Ubuntu/Debian: sudo apt-get install -y libvips"
+    puts "     Fedora: sudo dnf install vips\n\n"
+  end
+
   puts "== Installing dependencies =="
   system("bundle check") || system!("bundle install")