From 2c40899e7642758d3572fd82a5b371d0b9d14e6f Mon Sep 17 00:00:00 2001
From: Bean Labs <287763725+beanscg@users.noreply.github.com>
Date: Mon, 8 Jun 2026 13:59:33 -0400
Subject: [PATCH] docs: improve developer setup guide

---
 CONTRIBUTING.md | 25 +++++++++++++++++++++----
 README.md       | 32 ++++++++++++++++++++++++++++++--
 2 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 02a8c2c..e11e0a6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,13 +4,30 @@ Thanks for your interest in contributing! Here's how to get started.
 
 ## Development Setup
 
+### Prerequisites
+
+- Node.js 20 or newer
+- npm 10 or newer
+- Git
+
 ```bash
-git clone https://github.com/zumap/zumap.git
-cd zumap
+git clone https://github.com/Keylab-dev/keylab.git
+cd keylab
 npm install
 npm run dev
 ```
 
+Open [http://localhost:3000](http://localhost:3000) to test changes locally.
+
+### Validation
+
+Run these before submitting a pull request:
+
+```bash
+npm run lint
+npm run build
+```
+
 ## Ways to Contribute
 
 ### 🎹 Add a Keyboard Definition
@@ -37,8 +54,8 @@ Check the roadmap in README.md. Open an issue to discuss before starting large c
 1. Fork and create a feature branch
 2. Make your changes
 3. Test locally with `npm run dev`
-4. Run `npm run build` to check for errors
-5. Submit a PR with a clear description
+4. Run `npm run lint` and `npm run build`
+5. Submit a PR with a clear description, screenshots for UI changes, and any manual test notes
 
 ## Keyboard Definition Guidelines
 
diff --git a/README.md b/README.md
index b9bce4c..11dc67a 100644
--- a/README.md
+++ b/README.md
@@ -16,15 +16,37 @@ An open-source, VIA-compatible keyboard configurator for the web. Load any keybo
 
 ## Getting Started
 
+### Prerequisites
+
+- Node.js 20 or newer
+- npm 10 or newer
+- Git
+
 ```bash
-git clone https://github.com/zumap/zumap.git
-cd zumap
+git clone https://github.com/Keylab-dev/keylab.git
+cd keylab
 npm install
 npm run dev
 ```
 
 Open [http://localhost:3000](http://localhost:3000).
 
+### Development Commands
+
+```bash
+npm run dev      # Start the local Next.js development server
+npm run lint     # Run ESLint
+npm run build    # Create a production build
+npm run start    # Serve the production build after npm run build
+```
+
+Before opening a pull request, run:
+
+```bash
+npm run lint
+npm run build
+```
+
 ## Project Structure
 
 ```
@@ -44,6 +66,12 @@ src/
   types/         → TypeScript type definitions
 ```
 
+### Architecture Overview
+
+Zumap is a client-side Next.js app. The UI lives in `src/components/`, route-level pages live in `src/app/`, and the
+keyboard/keymap logic lives in `src/lib/`. VIA keyboard definition files are loaded from `keyboards/`, while reusable
+keymap presets live in `keymaps/`.
+
 ## Adding a Keyboard
 
 1. Create a VIA-compatible JSON definition (see [VIA spec](https://www.caniusevia.com/docs/specification))