codebar · mroderick · Jun 12, 2026
diff --git a/Makefile b/Makefile
@@ -25,3 +25,6 @@ serve:
 
 test:
 	bundle exec parallel_rspec spec/ -n 3
+
+check:
+	bundle exec rake setup:check
diff --git a/README.md b/README.md
@@ -11,120 +11,118 @@ If you are considering making a PR, please take a look at the [GitHub issues](ht
 
 ## Getting Started
 
-The following steps walk through getting the application running. Before you start, please check out our [contributing guidelines](https://github.com/codebar/planner/blob/master/CONTRIBUTING.md).
+Before you start, please check out our [contributing guidelines](https://github.com/codebar/planner/blob/master/CONTRIBUTING.md).
+
+We recommend **native installation** for local development. A full step-by-step guide is in [docs/development-setup.md](docs/development-setup.md). The quick version is below.
+
+### Quick start
+
+1. **Install prerequisites** (macOS or Linux):
+   - [mise](https://mise.jdx.dev/) — manages Ruby and environment variables
+   - [PostgreSQL](https://www.postgresql.org/) — database server
+   - [ImageMagick](https://imagemagick.org/) — image processing
+
+   On macOS with Homebrew:
+   ```bash
+   brew install mise postgresql imagemagick
+   brew services start postgresql
+   ```
+
+2. **Clone the project**:
+   ```bash
+   git clone https://github.com/codebar/planner.git
+   cd planner
+   ```
+
+3. **Install Ruby** (managed by mise):
+   ```bash
+   mise install
+   ```
+
+4. **Configure GitHub OAuth**:
+   - Create a GitHub OAuth app at [https://github.com/settings/applications/new](https://github.com/settings/applications/new)
+   - Authorization callback URL: `http://localhost:3000/auth/github`
+   - Copy your Client ID and Client Secret into `mise.local.toml`:
+     ```bash
+     cp mise.local.toml.example mise.local.toml
+     # Edit mise.local.toml with your real credentials
+     ```
+
+5. **Install dependencies and set up the database**:
+   ```bash
+   gem install bundler
+   bundle install
+   bundle exec rake db:create db:migrate db:test:prepare
+   ```
+
+6. **Check your environment**:
+   ```bash
+   bundle exec rake setup:check
+   ```
+
+7. **Start the app**:
+   ```bash
+   bundle exec rails server
+   ```
+
+   Visit [http://localhost:3000](http://localhost:3000).
+
+### Run the tests
 
-1. [Clone the project](#1-clone-the-project)
-2. [Enable GitHub Authentication](#2-enable-github-authentication)
-3. [Install and set up the environment using docker](#3-install-and-set-up-the-environment-using-docker)
-4. [Start the app](#4-start-the-app)
-5. [Run the tests](#5-run-the-tests)
-
-### 1. Clone the project
-
-1. Navigate to your project's chosen parent directory, e.g. `cd ~/Documents/codebar`
-2. [Clone the project](https://help.github.com/articles/cloning-a-repository/), e.g. `git clone git@github.com:codebar/planner.git`
-3. Navigate into the project directory: `cd planner`
-
-### 2. Enable GitHub Authentication
-
-The application uses GitHub OAuth for user authentication. You'll need to create a new OAuth application on your GitHub account, then add the key and secret to your project's environment variables.
-
-#### Create a new Github OAuth application
-
-Visit [https://github.com/settings/applications/new](https://github.com/settings/applications/new) and fill out the form to create a new application. Use these field values:
-
-| Field | Value |
-| --- | --- |
-| Application name | Something memorable, like 'codebar planner' |
-| Homepage URL | `http://localhost:3000` |
-| Application description | Something memorable, like 'Local codebar app authentication'. |
-| Authorization Callback URL | `http://localhost:3000/auth/github` |
-
-#### Add your application details to your environment variables
-
-**Native installation (recommended):** Copy `mise.local.toml.example` to `mise.local.toml`
-and fill in your GitHub key and secret:
-
-```
-cp mise.local.toml.example mise.local.toml
-# Edit mise.local.toml with your values
+```bash
+bundle exec rspec
 ```
 
-Environment variables are managed by [mise](https://mise.jdx.dev). Install it
-with `brew install mise` and enable `mise activate` in your shell profile.
-
-**Docker installation:** Copy `docker-compose.override.yml.example` to
-`docker-compose.override.yml` and fill in your GitHub key and secret:
-
-```
-cp docker-compose.override.yml.example docker-compose.override.yml
-# Edit docker-compose.override.yml with your values
+Run tests in parallel for faster results:
+```bash
+bundle exec parallel_rspec spec/ -n 3
 ```
 
-Docker Compose automatically merges this file — no extra configuration needed.
-
-### 3. Install and set up the environment using docker
-
-We recommend using Docker to install and run the application. However alternatively if you prefer, [you can install directly to your system environment instead](./native-installation-instructions.md).
-
-Before you start, you will need to have Docker installed and running. You can [download it from the Docker website](https://docker.com/). Once downloaded, install and start the Docker application.
-
-Run `bin/dup` to build and create the docker container. This will also set up the Rails application within the container and start the container. You will only have to run this command once. After initial setup, use `bin/dstart` to start an existing container - using `bin/dup` will recreate an existing container and reset the database.
-
-**Note:** The Docker setup includes ImageMagick automatically. If you're using native installation, you must install ImageMagick separately (see [native-installation-instructions.md](./native-installation-instructions.md)).
-
-### 4. Start the app
-
-Run `bin/dserver` to start the Rails server.
-
-*If you have previously stopped the container, you will have to first start the container using `bin/dstart`.
-
-This should run a process which starts a server in a Docker container on your computer. This process won't finish - you'll know the server is ready when it stops doing anything and displays a message like this:
-```
-Rails 4.2.11 application starting in development on http://localhost:3000
+Run a single test:
+```bash
+bundle exec rspec spec/path/to/test_spec.rb:42
 ```
 
-(Optional) Note that to be able to use the page as an admin, you must first give yourself admin privileges. Make sure you have started your app and signed up as an user on your locally running app. Then run the script `bin/dadmin <your email>`.
-
-**You can now view the app at http://localhost:3000**
+Run JavaScript-enabled feature tests with a visible browser:
+```bash
+PLAYWRIGHT_HEADLESS=false bundle exec rspec
+```
 
-You can stop the server when you're finished by typing `Ctrl + C`.
+### Make yourself an admin
 
-### 5. Run the tests
+After signing up locally, run:
+```bash
+bundle exec rails runner "Member.find_by(email: 'your-email@example.com').add_role(:admin)"
+```
 
-Run `bin/drspec` to run all the tests.
+### Full setup guide
 
-This command passes any additional arguments into `rspec` in the docker container, so you can run individual tests with `bin/drspec PATH_TO_TEST` and run a single test case in a file with `bin/drspec PATH_TO_TEST:LINE_NUMBER`
+For detailed, step-by-step instructions — including troubleshooting, Linux-specific steps, and explanations of what each tool does — see [docs/development-setup.md](docs/development-setup.md).
 
-#### Running JavaScript enabled feature tests with a visible browser
+---
 
-There are a small number of feature tests marked with `js: true` which use
-headless Chrome. These can be hard to work with without being able to see what is
-actually happening in the browser. To spin up a visible browser, pass
-`CHROME_HEADLESS=false` as part of the test command, for example:
+## Docker (not recommended)
 
-```bash
-CHROME_HEADLESS=false bundle exec rspec
-```
+A Docker setup exists but is **not recommended** for local development. It is slower, harder to debug, and does not support running JavaScript feature tests with a visible browser.
 
-Running JavaScript enabled tests with a visible browser currently doesn't work with Docker.
+If you prefer Docker, see the commands in `bin/d*`:
 
-### Available Docker commands
+| Command | What it does |
+|---------|-------------|
+| `bin/dup` | Build and start a new container (also resets the database) |
+| `bin/dstart` | Start an existing container |
+| `bin/dserver` | Run the Rails server inside the container |
+| `bin/drspec` | Run the test suite inside the container |
+| `bin/drake` | Run rake inside the container |
+| `bin/dexec` | Open a shell inside the container |
+| `bin/dstop` | Stop the container |
+| `bin/ddown` | Stop and remove the container |
 
-- `bin/dup`: `docker-compose up --build -d --wait && rake db:drop db:create db:migrate db:seed db:test:prepare`. Rebuilds and boots up a new container, and then initialize the Rails database.
-- `bin/dstart`: `docker-compose start`. Starts the existing container.
-- `bin/dserver`: `docker-compose exec web make serve`. Runs the Rails server. Use this instead of `bin/drails server` to make it bind to the correct IP addresses to allow the server to be viewable outside the container.
-- `drails`: `docker-compose exec web rails $@`. Runs rails within the container.
-- `drspec`: `docker-compose exec web rspec $@`. Runs rspec within the container.
-- `drake`: `docker-compose exec web rake $@`. Runs rake inside the container.
-- `dexec`: `docker-compose exec web bash`. Runs a bash shell inside the container.
-- `dadmin`: Gives the the last user (or the one with a given email) the admin role
-- `bin/dstop`: `docker-compose stop`. Stops container but does not remove it
-- `bin/ddown`: `docker-compose down`. Stops and destroy a container.
+---
 
 ## Front-end framework
 
-We use Bootstrap 5, you can find the documentation here: https://getbootstrap.com/docs/5.2/getting-started/introduction/
+We use Bootstrap 5. Documentation: https://getbootstrap.com/docs/5.2/getting-started/introduction/
 
 ## Finding something to work on
 

diff --git a/db/seeds.rb b/db/seeds.rb
@@ -15,7 +15,7 @@
     Rails.logger.error '  Ubuntu/Debian: apt-get install imagemagick'
     Rails.logger.error '  Windows:       https://imagemagick.org/script/download.php'
     Rails.logger.error ''
-    Rails.logger.error 'See native-installation-instructions.md for details.'
+    Rails.logger.error 'See docs/development-setup.md for details.'
     Rails.logger.error '=' * 80
     exit 1
   end

diff --git a/docs/coding-agent-setup-skill.md b/docs/coding-agent-setup-skill.md
@@ -0,0 +1,115 @@
+# Skill: Help a contributor set up codebar planner locally
+
+Use this skill when a user asks for help setting up the codebar planner application for local development, or when they report errors running the app, tests, or database commands.
+
+## Context
+
+The codebar planner is a Rails 8.1 application. Contributors range from junior to senior engineers. The recommended setup path is **native installation** (not Docker). The project uses:
+
+- **Ruby** (version in `.ruby-version`) managed by **mise**
+- **PostgreSQL** as the database
+- **ImageMagick** for image processing
+- **GitHub OAuth** for authentication (requires a local OAuth app)
+- **Bundler** for Ruby dependencies
+
+## Diagnostic command
+
+The project has a built-in diagnostic command. Always run this first:
+
+```bash
+bundle exec rake setup:check
+```
+
+This command checks:
+- Ruby version matches `.ruby-version`
+- Bundler is installed
+- PostgreSQL is installed and accepting connections
+- ImageMagick is installed
+- `mise.local.toml` exists and contains real GitHub OAuth credentials
+- Ruby gems are installed (`bundle check`)
+- Database connection works
+- Development database exists and is migrated
+- Test database exists and is accessible
+
+**Interpret the output:**
+- ✅ = all good, no action needed
+- ⚠️ = warning, development can usually proceed but review the note
+- ❌ = error, must be fixed before the app will work
+
+Each error prints a specific fix next to it. Guide the user through those fixes.
+
+## Common scenarios and responses
+
+### "I just cloned the repo, what do I do?"
+
+1. Ask what operating system they are using (macOS or Linux).
+2. Run `bundle exec rake setup:check` to see what is already installed.
+3. Guide them through the missing pieces using the instructions in `docs/development-setup.md`.
+4. Emphasise: they must create a GitHub OAuth app and configure `mise.local.toml` before the app will start.
+
+### "The app won't start" or "I get an error when running rails server"
+
+1. Run `bundle exec rake setup:check`.
+2. If PostgreSQL errors appear, help them start the service:
+   - macOS: `brew services start postgresql`
+   - Linux: `sudo service postgresql start`
+3. If GitHub OAuth errors appear, walk them through creating the OAuth app at https://github.com/settings/applications/new and editing `mise.local.toml`.
+4. If database errors appear, run `bundle exec rake db:create db:migrate`.
+5. If dependency errors appear, run `bundle install`.
+
+### "Tests fail"
+
+1. Run `bundle exec rake setup:check` to confirm the test database is accessible.
+2. If the test database is missing, run `bundle exec rake db:test:prepare`.
+3. Run `bundle exec rspec` to get the failure output.
+4. If failures are in JavaScript feature tests, suggest running with `PLAYWRIGHT_HEADLESS=false bundle exec rspec` to see the browser.
+5. If failures persist after a clean setup, they may be legitimate bugs — suggest opening an issue.
+
+### "I can't log in" or "GitHub authentication fails"
+
+1. Check `mise.local.toml` exists and contains real (not placeholder) values.
+2. Verify the GitHub OAuth app callback URL is exactly `http://localhost:3000/auth/github`.
+3. Make sure they restarted their terminal after creating `mise.local.toml` so mise loads the variables.
+4. Check they are visiting `http://localhost:3000` (not `https` or `127.0.0.1`).
+
+### "db:seed fails"
+
+1. Check `bundle exec rake setup:check` for ImageMagick.
+2. If ImageMagick is missing, install it:
+   - macOS: `brew install imagemagick`
+   - Linux: `apt-get install imagemagick`
+3. Re-run `bundle exec rake db:seed`.
+
+### "I get a 'role does not exist' error from PostgreSQL"
+
+PostgreSQL does not have a user matching the system username. Help them create it:
+
+- macOS: `createuser -s $(whoami)`
+- Linux: `sudo -u postgres createuser -s $(whoami)`
+
+Then re-run `bundle exec rake db:create`.
+
+## Principles
+
+- **Never recommend Docker** unless the user explicitly asks for it. The project documentation has moved away from Docker as the primary path.
+- **Always run `setup:check` first.** It gives concrete, actionable error messages and saves time.
+- **Explain the 'why' when juniors ask.** For example, explain that mise manages Ruby versions, that PostgreSQL is the database, and that GitHub OAuth credentials are needed because the app uses GitHub for login.
+- **Point to the docs.** `docs/development-setup.md` is the authoritative, detailed guide. Use it as the reference for anything not covered here.
+- **Assume the user is not a senior engineer.** Use simple language, avoid jargon without explanation, and break instructions into small steps.
+
+## Quick reference
+
+| Problem | First check | Likely fix |
+|---------|------------|------------|
+| App won't start | `setup:check` | PostgreSQL not running, or missing GitHub credentials |
+| Database errors | `setup:check` | `bundle exec rake db:create db:migrate` |
+| Tests fail | `setup:check` | `bundle exec rake db:test:prepare` |
+| Can't log in | `setup:check` | GitHub OAuth app misconfigured or `mise.local.toml` not loaded |
+| Seed fails | `setup:check` | `brew install imagemagick` |
+| Missing gems | `setup:check` | `bundle install` |
+
+## Off-limits
+
+- Do not modify `.ruby-version` or `Gemfile.lock`.
+- Do not commit `mise.local.toml` (it is gitignored, but reinforce this).
+- Do not suggest modifying `config/database.yml` unless there is a genuine connection issue that cannot be solved with environment variables.
-Original file line number
+Diff line change
@@ Expand Up / @@ -25,3 +25,6 @@ serve: @@
     test:
     	bundle exec parallel_rspec spec/ -n 3
+    check:
+    	bundle exec rake setup:check