diff --git a/README.md b/README.md
index 028fcba4..8336e614 100644
--- a/README.md
+++ b/README.md
@@ -1,56 +1,82 @@
- 
+
+
+# Good First Issue
+
Welcome! 👋🏼
-**Good First Issue** is an initiative to curate easy pickings from popular projects, so developers who've never contributed to open-source can get started quickly.
+**Good First Issue** is an initiative to curate “easy pickings” from popular open-source projects, so developers who have never contributed before can get started quickly.
-Open-source maintainers are always looking to get more people involved, but new developers generally think it's challenging to become a contributor. We believe getting developers to fix super-easy issues removes the barrier for future contributions. This is why Good First Issue exists.
+Open-source maintainers are always looking to get more people involved, but new developers often think it's challenging to become a contributor. We believe that helping developers fix super-easy issues removes the barrier for future contributions.
-## Adding a new project
+This is why **Good First Issue** exists. đź’ś
-You're welcome to add a new project in Good First Issue, and we encourage all projects — old and new, big and small.
+---
-Follow these simple steps:
+## 🚀 Adding a New Project
-- Our goal is to narrow down projects for new open-source contributors. To maintain the quality of projects in Good First Issue, please make sure your GitHub repository meets the following criteria:
+You're welcome to add a new project to Good First Issue, and we encourage all kinds of projects — old and new, big and small.
- - It has at least three issues with the `good first issue` label. This label is already present on all repositories by default. If not, you can follow the steps [here](https://help.github.com/en/github/managing-your-work-on-github/applying-labels-to-issues-and-pull-requests).
+Please follow these steps:
- - It has at least 10 contributors.
+### 1. Check that your repository meets the criteria
- - It contains a README.md with detailed setup instructions for the project, and a CONTRIBUTING.md with guidelines for new contributors.
+Our goal is to narrow down projects for new open-source contributors. To maintain the quality of projects shown on Good First Issue, make sure your GitHub repository satisfies **all** of the following:
- - It is actively maintained.
+- âś… It has **at least three issues** with the `good first issue` label.
+ This label exists on all repositories by default. If you don’t see it, you can follow the steps in the [GitHub docs](https://help.github.com/en/github/managing-your-work-on-github/applying-labels-to-issues-and-pull-requests).
-- Add your repository's path (in lexicographic order) in [data/repositories.toml](data/repositories.toml).
+- âś… It has **at least 10 contributors**.
-- Create a new pull-request. Please add the link to the issues page of the repository in the PR description. Once the pull request is merged, the changes will be live on [goodfirstissue.dev](https://goodfirstissue.dev/).
+- âś… It contains:
+ - A `README.md` with **clear, detailed setup instructions** for the project.
+ - A `CONTRIBUTING.md` with **guidelines for new contributors**.
-## Setting up the project locally
+- âś… It is **actively maintained** (for example, there have been recent commits or issues handled in the last few months).
-Good First Issue has two components — the front-end app built with Nuxt.js and a data population script written in Python.
+### 2. Add your repository to the list
-To contribute new features and changes to the website, you would want to run the app locally. Please follow these steps:
+Once your repository meets the criteria:
-1. Clone the project locally. Make sure you have Python 3 and a recent version of Node.js installed on your computer.
+1. Open the file [`data/repositories.toml`](data/repositories.toml).
+2. Add your repository’s path **in lexicographic (alphabetical) order**.
+3. Save the file.
-2. Make a copy of the sample data files for your local app to use and rename them to the filename that the app expects. **This step is important, as the front-end app won't work without these data files.**
+If you’re not familiar with TOML: it’s a simple configuration file format. You can learn more at [https://toml.io](https://toml.io), but for most use cases, copying an existing entry and adjusting it will be enough.
-```bash
-$ cp data/generated.sample.json data/generated.json
-$ cp data/tags.sample.json data/tags.json
-```
+### 3. Open a Pull Request
-3. Build the front-end app and start the development server.
+1. Commit your changes to `data/repositories.toml`.
+2. Create a new pull request to this repository.
+3. In the PR description, **include a link to the issues page** of your repository (e.g. `https://github.com/owner/repo/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22`).
-```bash
-$ bun install # install the dependencies
-$ bun dev # start the development server
-```
+Once your pull request is reviewed and merged, your project will appear on [goodfirstissue.dev](https://goodfirstissue.dev/). 🎉
+
+---
+
+## 🛠️ Setting Up the Project Locally
+
+Good First Issue has two components:
-The app should open in your browser.
+1. A **front-end app** built with Nuxt.js.
+2. A **data population script** written in Python.
+
+If you want to contribute new features or changes to the website, you’ll likely want to run the app locally.
+
+### 1. Prerequisites
+
+Make sure you have the following installed on your computer:
+
+- **Python 3**
+- A recent version of **Node.js**
+- **Bun**, the JavaScript runtime and package manager used by this project
+
+You can download Node.js from the official website, and check your version with:
+
+```bash
+node -v