nick-sde-value-driver-website/GETTING-STARTED.md

# Getting Started — Project SDE Meeting Toolkit

**A step-by-step, no-experience-needed guide to running this app on your own computer and changing it with Claude Code.**

Hi! This guide assumes you have **never written code before**. Every step tells you
exactly what to click, type, or copy. You will mostly be copying commands and pressing
Enter. Take it one step at a time and you'll be fine.

- **Time needed:** about 30–45 minutes the first time (most of it is downloads installing).
- **Can I break anything?** No. Everything runs only on your computer. If something gets
  messed up, the [Troubleshooting](#if-something-goes-wrong) section fixes it, and worst
  case you can delete the folder and start over.
- **What you'll have at the end:** the meeting-tools website running on your own machine,
  plus the ability to ask Claude Code to change it and watch the changes appear instantly.

---

## Table of contents

1. [What we're setting up (in plain English)](#1-what-were-setting-up-in-plain-english)
2. [How to use the "terminal"](#2-how-to-use-the-terminal)
3. [Step-by-step: install the tools](#3-install-the-tools)
4. [Step-by-step: get the project onto your computer](#4-get-the-project-onto-your-computer)
5. [Step-by-step: run the app](#5-run-the-app)
6. [Step-by-step: change something with Claude Code](#6-change-something-with-claude-code)
7. [Everyday use (quick reference)](#7-everyday-use--quick-reference)
8. [If something goes wrong](#if-something-goes-wrong)
9. [Word glossary](#word-glossary)

---

## 1. What we're setting up (in plain English)

The **app** is the website with the two meeting tools (Field Problem Workshop and Scope
Lock Suite). To run it on your computer, it needs three helpers:

| Helper | What it does | Why you need it |
|---|---|---|
| **Node.js** | Runs the website's code on your computer. | The app is written in a language Node understands. |
| **Docker Desktop** | Runs a small **database** for us in the background. | The app saves its data in a database. Docker lets us start one instantly without installing a database by hand (that part is genuinely painful, so we skip it). |
| **Claude Code** | An AI assistant you talk to in the terminal. | This is how you'll change ("tweak") the app without writing code yourself. |

You'll also install **VS Code** (a friendly editor — you'll use it to download the project
and to open the terminals you type commands into) and **Git** (a behind-the-scenes tool VS
Code and Claude use to download the code and save your changes — you won't use it directly).
Don't worry about what any of these are yet — just follow along.

Here's the picture of what you're building:

```
  Your computer
  ┌─────────────────────────────────────────────┐
  │                                               │
  │   Docker  ─►  Database  (stores the data)      │
  │                  ▲                             │
  │                  │                             │
  │   Node   ─►  The app  ─►  http://localhost:5180 │  ◄── you open this in your browser
  │                  ▲                             │
  │                  │                             │
  │   Claude Code  ──┘  (you ask it to change the app) │
  │                                               │
  └─────────────────────────────────────────────┘
```

---

## 2. How to use the "terminal"

A **terminal** is a window where you type commands instead of clicking buttons. On Windows
the one we'll use is called **PowerShell**.

**To open it:** press the **Windows key**, type `powershell`, and click **Windows
PowerShell**. A dark or blue window opens with a blinking cursor. That's it.

> **Use PowerShell, not "Command Prompt" (cmd).** Windows has an older, similar-looking
> black window called *Command Prompt* or *cmd*. Some of the commands in this guide only
> work in **PowerShell**, so always start from the "Windows PowerShell" app as described
> above. If your window's cursor line starts with `PS C:\...>`, you're in the right one.

A few things to know (this guide is Windows-only, so everything below is written for
PowerShell):

- A **command** is a line of text you paste in and then press **Enter** to run.
- **To paste** into PowerShell: right-click inside the window (or press `Ctrl+V`). Then
  press **Enter**.
- When a command finishes, you get your blinking cursor back on a new line. If it's still
  "thinking," just wait.
- If you ever want to **stop** something that's running, click the window and press
  **`Ctrl + C`**.
- Commands are picky about spelling and spaces. Copy-paste them exactly rather than
  retyping.

Try it now: paste this and press Enter. It just prints a message, to prove pasting works.

```powershell
echo "Hello, I can use the terminal"
```

---

## 3. Install the tools

Install these one at a time. **Some of them may already be on your work computer** — so
for each one, **run the "check" command first**. If it prints a version number, that tool
is already installed and you can skip straight to the next one. Only download it if the
check says the command isn't recognized.

After any install, **close and reopen PowerShell** so it notices the new tool, then run the
check again to confirm.

### 3a. Node.js

**First, check if it's already installed.** In PowerShell, run:

```powershell
node -v
npm -v
```

If you see two version numbers (for example `v20.11.1` and `10.2.4`), Node is already
installed — **skip to 3b**. (`npm` comes bundled with Node; you never install it
separately.) If instead you see a message like "node is not recognized," install it:

1. Go to **<https://nodejs.org>**.
2. Click the button that says **LTS** (it will have a version number like "20.x.x LTS").
   LTS means the stable, recommended version.
3. Open the downloaded file and click **Next → Next → Install → Finish**. Accept all the
   defaults. If it asks about "Tools for Native Modules," you can leave that unchecked.
4. Close PowerShell, open a fresh one, and run `node -v` and `npm -v` again to confirm you
   now get version numbers.

### 3b. Docker Desktop

**First, check if it's already installed.** Run:

```powershell
docker --version
```

If you see a version number, Docker is installed — just make sure the app is running
(Windows key → type "Docker" → open **Docker Desktop**, and wait for the whale icon by the
clock to go steady), then **skip to 3c**. Otherwise, install it:

1. Go to **<https://www.docker.com/products/docker-desktop/>** and download **Docker
   Desktop for Windows**.
2. Run the installer, accept the defaults, and let it finish. It may ask you to **restart
   your computer** — go ahead.
3. After restarting, **open Docker Desktop** (Windows key → type "Docker" → click it). The
   first launch takes a minute. Accept the service agreement if asked.
4. **Leave Docker Desktop running.** You'll know it's ready when the little whale icon
   near the clock (bottom-right of your screen) is steady, not animating. Docker must be
   running whenever you use the app.
5. Close and reopen PowerShell, then run `docker --version` again to confirm.

> Docker Desktop on Windows uses something called WSL2. If the installer offers to set it
> up, say yes. If you hit an error about WSL, run PowerShell **as Administrator** (right-
> click PowerShell → "Run as administrator") and paste `wsl --install`, then restart.

### 3c. Git

**First, check if it's already installed.** Run:

```powershell
git --version
```

If you see a version number, skip to 3d. Otherwise, install it:

1. Go to **<https://git-scm.com/download/win>**. The download starts automatically.
2. Run the installer. There are a lot of screens — **just click Next through all of them**
   and then Install. The defaults are fine.
3. Close and reopen PowerShell, then run `git --version` again to confirm.

### 3d. VS Code

VS Code is the editor you'll use to download the project and to open a terminal. We'll use
it in Step 4, so please install it.

**First, check if it's already installed:** press the **Windows key** and type
`Visual Studio Code`. If it shows up, it's installed — skip to 3e. Otherwise:

- Download from **<https://code.visualstudio.com>** and run the installer.
- On the installer's "Select Additional Tasks" screen, **tick the "Open with Code"
  checkboxes** — it makes things easier later. Then finish with the defaults.

### 3e. Claude Code

This is the AI assistant you'll use to change the app.

**First, check if it's already installed.** Run:

```powershell
claude --version
```

If you see a version number, skip to Step 4. Otherwise, now that Node is installed (3a),
install Claude Code with one command:

```powershell
npm install -g @anthropic-ai/claude-code
```

The `-g` means "install it for the whole computer." When it finishes, close and reopen
PowerShell and confirm:

```powershell
claude --version
```

You'll log in the first time you actually start it (in Step 6) — it opens your browser to
sign in with your Anthropic account. If you don't have an account yet, ask whoever gave
you this project which login to use.

---

## 4. Get the project onto your computer

You'll download ("clone") the project from our internal Gitea site straight into VS Code.
Don't download a ZIP — cloning from Gitea keeps your copy connected to the real project so
you can pull in updates later.

We'll do this entirely through VS Code's menus — **no typing commands.**

1. **Open VS Code** (Windows key → type `Visual Studio Code` → Enter).
2. Open the **Command Palette**: press **`Ctrl + Shift + P`**. A search box drops down from
   the top.
3. Type **`Git: Clone`** and click it when it appears in the list.
4. It asks for a repository URL. Paste this exact address and press **Enter**:

   ```
   https://primegit.primecontrols-dev.com/c.west/nick-sde-value-driver-website.git
   ```

5. A file window opens asking **where to put the project.** Choose your **Documents**
   folder and click **Select as Repository Destination**. (VS Code creates a
   `nick-sde-value-driver-website` folder inside it for you.)
6. The first time, a browser window or a pop-up will ask you to **sign in** to the internal
   Gitea site — use your work login. If it asks to allow the "GitHub"/"Git" extension to
   sign in, allow it.
7. When it finishes downloading, VS Code shows a notification in the bottom-right:
   **"Would you like to open the cloned repository?"** Click **Open**.

You should now see the project's files listed in the panel on the left side of VS Code
(names like `src`, `package.json`, `docker-compose.yml`, and `GETTING-STARTED.md` — this
guide). That means it worked. Keep VS Code open for the next step.

> If you don't have the Gitea link or can't sign in, ask the person who shared this project
> with you — you need access to that internal site to download the code.

---

## 5. Run the app

From here on, all commands go into a terminal that is **inside the project folder**. The
easiest way to get one is to use the terminal built into VS Code — because you opened the
project there in Step 4, it already starts in the right place.

### 5a. Open the terminal inside VS Code

1. With the project open in VS Code, click the **Terminal** menu at the top → **New
   Terminal**. (Or press **`` Ctrl + ` ``** — that's the key just above Tab, to the left of
   the `1` key.)
2. A panel opens at the bottom of VS Code with a blinking cursor. This is your PowerShell
   terminal, and it's already sitting inside the project folder.
3. Make sure it's PowerShell: the line should start with `PS` followed by a path ending in
   `nick-sde-value-driver-website`. If it says something else, click the small **dropdown
   arrow (⌄)** next to the `+` at the top-right of the terminal panel, choose **Select
   Default Profile → Windows PowerShell**, then open a New Terminal again.

To double-check you're in the right place, type this and press Enter:

```powershell
ls
```

You should see names like `package.json`, `src`, `docker-compose.yml`, and this
`GETTING-STARTED.md`. If you do, you're ready. **Use this VS Code terminal for all the
commands below.**

### 5b. Create your settings file

The app reads its settings from a file named `.env`. There's a ready-made template called
`.env.example`. Copy it — **the default values already match the database we're about to
start, so you don't need to edit anything.**

```powershell
Copy-Item .env.example .env
```

### 5c. Start the database (with Docker)

Make sure **Docker Desktop is running** (steady whale icon). Then start just the database:

```powershell
docker compose up -d db
```

- The first time, Docker downloads the database software — this can take a minute or two.
- `-d` means "run it in the background," so you get your cursor back.
- The database automatically creates the tables it needs on first startup. You don't have
  to do anything.

Check it's running:

```powershell
docker compose ps
```

You should see a `db` line with status `running` (or `healthy`). Leave it running in the
background.

### 5d. Install the app's building blocks

The app depends on some code libraries. This command downloads them into the folder. It's
a **one-time** step (you only re-run it if someone changes the dependencies later).

```powershell
npm install
```

It prints a lot of text and takes a minute. A few warnings in yellow are normal. As long
as it ends without a big red `ERR!` block, you're good.

### 5e. Start the app

```powershell
npm run dev
```

After a moment you'll see something like:

```
  VITE ready
  ➜  Local:   http://localhost:5180/
```

**Open your browser and go to <http://localhost:5180>** — the app appears! Try the dark-
mode button in the top bar, click into the tools, enter some text.

Important:

- **Keep this terminal open.** As long as it's running, the app is live. If you close it
  (or close VS Code), the app stops.
- To **stop** the app, click inside that terminal and press **`Ctrl + C`**.
- The address is `localhost`, which just means "this computer." Only you can see it — it's
  not on the internet.

🎉 The app is now running on your machine. Next, let's change something.

---

## 6. Change something with Claude Code

Here's the magic: while the app is running, you tell Claude Code what you want changed, and
the change shows up in your browser **automatically** — this is called "hot reload."

### 6a. Open a *second* terminal (also in VS Code)

Your first terminal is busy running the app — leave it alone. You'll open a **second**
terminal right next to it in VS Code:

1. In the terminal panel at the bottom of VS Code, click the **`+`** (plus) button at its
   top-right corner. This opens a fresh terminal alongside the first one — you'll see both
   listed on the right side of the panel, and you can click between them.
2. The new terminal also starts inside the project folder, so you're ready to go. (Your
   `npm run dev` keeps running in the other one the whole time.)

### 6b. Start Claude Code

```powershell
claude
```

The first time, it opens your browser to **log in** — follow the prompts. After that,
you'll see a prompt where you can type to Claude in plain English.

### 6c. Ask for a change

Type a request in normal words and press Enter. Some examples to try:

- `Change the heading on the home page from "Meeting Toolkit" to "SDE Meeting Tools".`
- `Make the "Open →" links on the home page cards bright green.`
- `Add a short sentence under the main heading explaining what the Scope Lock tool is for.`

Claude will explain what it's about to do and make the edits. It may ask for your approval
before changing files — read what it says and approve if it looks right. **You can't
permanently break anything** — see "undo" below.

### 6d. Watch it happen

Switch to your browser at <http://localhost:5180> and **refresh if needed**. Your change
is there. Keep chatting with Claude to refine it: `a bit darker green`, `undo that`, `move
it above the heading`, and so on.

### 6e. Undoing changes

If you don't like a change, just ask Claude in plain English: `undo the last change`, `put
the heading back the way it was`, or `undo everything you've changed today`. Claude keeps
track and can walk it back for you — you don't need to know how it does that.

### 6f. When you're happy — saving your work to the repo

Your changes so far live only on your computer. When you want to keep them and put them
back into the shared project, **just ask Claude** — for example:

- `Save my changes and put them in the repo with a short description of what I did.`

Claude handles all the behind-the-scenes steps for you. If it needs anything from you (like
confirming your login), it'll ask in plain language. You don't need to learn any of the
commands yourself — describe what you want and let Claude do it.

---

## 7. Everyday use — quick reference

Once everything is installed, starting up each day is quick:

1. Make sure **Docker Desktop is running** (open it from the Start menu; wait for the steady
   whale icon).
2. **Open the project in VS Code** (it should appear under **File → Open Recent**, or reopen
   the `nick-sde-value-driver-website` folder).
3. Open a terminal (**Terminal → New Terminal**) and run these two commands:

```powershell
# make sure the database is up (safe to run even if it already is)
docker compose up -d db

# start the app  (leave this terminal running while you work)
npm run dev
```

Then open <http://localhost:5180> in your browser. Open a **second** terminal in VS Code
(the **`+`** button in the terminal panel) and run `claude` to make changes.

**Shutting down:**

```powershell
# in the app's terminal: press Ctrl + C to stop the app
# then, if you want to stop the database too:
docker compose stop
```

Your data is safe when you stop — it's stored by Docker and will be there next time. (See
Troubleshooting for how to wipe it if you ever want a clean slate.)

---

## If something goes wrong

**"The app won't open in my browser / the page is blank."**
Check the first VS Code terminal is still running `npm run dev` and shows a `Local:`
address. Make sure you typed the address exactly: `http://localhost:5180`. If the terminal
shows a red error, copy it and paste it to Claude Code and ask what's wrong.

**"Port 5180 is already in use" (or the app won't start).**
Something else is using that address — usually an old copy of the app still running. Close
any other terminals running the app (or close and reopen VS Code, or restart your
computer), then try `npm run dev` again.

**"Cannot connect to the database" / errors mentioning `ECONNREFUSED` or `5432`.**
The database isn't running. Make sure **Docker Desktop is open**, then run
`docker compose up -d db` and wait until `docker compose ps` shows it `running`/`healthy`.

**"docker: command not found" or "Docker Desktop is not running."**
Open Docker Desktop from the Start menu and wait for the whale icon to go steady. Then
retry your command.

**`npm install` ended with red `ERR!` text.**
Make sure you're in the project folder (`ls` should show `package.json`). Try running it
once more. If it still fails, copy the red text to Claude Code and ask for help.

**"claude: command not found."**
Close and reopen the VS Code terminal (it needs to pick up the new install) — the quickest
way is to close VS Code entirely and reopen the project. If it still isn't found, re-run
`npm install -g @anthropic-ai/claude-code`.

**I want to erase all the app's saved data and start clean.**
This deletes the database contents (the tables get re-created empty next start):

```powershell
docker compose down -v
docker compose up -d db
```

**When in doubt:** you have an AI assistant right here. In the second terminal, run
`claude` and describe what happened in plain English — paste any red error text. That's
literally what it's for.

---

## Word glossary

- **Terminal / PowerShell** — the window where you type commands.
- **Command** — a line of text you paste and run by pressing Enter.
- **Node.js** — the program that runs the app's code on your computer.
- **npm** — comes with Node; downloads and manages the app's code libraries. ("npm install"
  fetches them; "npm run dev" starts the app.)
- **Docker** — runs the database for us in a self-contained box, so we don't install a
  database by hand.
- **Database** — where the app stores the data people enter.
- **Dependencies / libraries** — pre-written code the app relies on, downloaded by
  `npm install` into a `node_modules` folder.
- **`.env` file** — a small settings file the app reads on startup.
- **localhost** — "this computer." `http://localhost:5180` is the app running only on your
  machine.
- **Port** — a numbered "door" on your computer. The app uses door `5180`; the database
  uses `5432`.
- **Hot reload** — when you change the code, the running app updates in the browser by
  itself.
- **Git** — a behind-the-scenes tool that downloads the project and saves changes. VS Code
  and Claude use it for you; you don't run it yourself.
- **Repository ("repo")** — the project stored on our internal Gitea site (its code plus
  its history). Your copy on your computer is connected to it.
- **Gitea** — our internal website where the project lives, like a private GitHub.
- **Claude Code** — the AI assistant in the terminal you ask to change the app.

---

*Stuck on a step? Open Claude Code (`claude`) in the project folder and describe exactly
what you see. It can read this guide and walk you through it.*