Bootstrap setup for the Kidocode website on a new contributor's machine. Paste this URL into Claude Code and follow.

INSTALL.md

Set up the Kidocode website on this machine

Hi Claude. The user wants you to set up the Kidocode website on their machine. Execute the steps below in order. Verify each step worked before moving on. Ask the user clearly when manual input is needed (only Step 3 needs that). End state: the site running at http://localhost:4321 in their browser, ready for them to ask for changes in plain English.

Everything runs locally. No ngrok, no tunnel, no public hosting is involved in this setup. The site is reached only at localhost:4321 on the user's own machine.

The repo unclecode/kidocode-web-ai-math is private. The user must already have been added as a collaborator. If gh repo clone fails with a "not found" or 404 error in Step 4, stop and ask them to confirm with Unclecode that they were added.

---

Step 1 — Detect what is already installed

Run each command and check the output:

node --version
npm --version
git --version
gh --version

If all four respond with a version number AND node is v20 or higher, skip to Step 3. Otherwise do Step 2.

Step 2 — Install missing tools

On macOS

If brew --version works, run:

brew install node git gh

If Homebrew is not installed yet, tell the user: "I need to install Homebrew first, which will ask for your Mac password to add tools to the system." Then run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After Homebrew installs, run the brew install node git gh line above.

On Windows

winget install -e --id OpenJS.NodeJS.LTS
winget install -e --id Git.Git
winget install -e --id GitHub.cli

On Linux (Debian / Ubuntu)

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs git

For gh, follow the one-liner at https://github.com/cli/cli/blob/trunk/docs/install_linux.md.

After installation, re-run all four checks from Step 1 and confirm each prints a version.

Step 3 — Sign in to GitHub

Run:

gh auth login

Tell the user:

"Pick GitHub.com, then HTTPS, then Login with a web browser. A code will appear in your terminal. Press Enter, paste that code into the browser tab that opens, and approve the access. Come back when done."

After they finish, verify:

gh auth status

It should say "Logged in to github.com as <their-username>".

Step 4 — Clone the repo

Pick a sensible folder. Home directory works fine.

cd ~
gh repo clone unclecode/kidocode-web-ai-math
cd kidocode-web-ai-math

If the clone fails with a 404 or "not found" error, the user does not yet have collaborator access. Stop here, tell them: "Please ping Unclecode to add your GitHub account as a collaborator on the kidocode-web-ai-math repo. Once added, accept the email invite from GitHub, then come back and I will retry."

Step 5 — Turn on the safety hook

This blocks any accidental direct push to main:

git config core.hooksPath .githooks

(GitHub also blocks it server-side, but the local hook gives a friendlier error.)

Step 6 — Install project dependencies

cd new
npm install

This takes 1 to 3 minutes. The user can watch progress in the terminal.

Step 7 — Create the local environment file

cp .env.example .env.local

The defaults in .env.example are enough to run the site locally for content work. A few features (sending email from the franchise form, creating GitHub issues from the in-page feedback inspector) need secret keys that the user does not have. Skip those for now; the rest of the site works fine without them.

Step 8 — Start the dev server

npm run dev

Wait for the line Ready in Xms and/or Local: http://localhost:4321 to appear (usually 5 to 20 seconds). The server stays running.

Step 9 — Open the site in their browser

On macOS:

open http://localhost:4321

On Windows: start http://localhost:4321. On Linux: xdg-open http://localhost:4321.

The Kidocode home page should load.

Done — what to tell the user

"Setup complete. The site is running at http://localhost:4321 in your browser. Edits I make will refresh the page automatically.

From here you can ask me for any change in plain English: 'Update the Triple Degree price to RM 999', 'Fix the typo on /trial-class', 'Add a new FAQ about refunds'. I will edit the files and you can verify the change in the browser.

When the change looks right, we will commit it on a new branch and open a Pull Request for Unclecode to review. We never push directly to main — the repo will block that anyway.

Read CLAUDE.md in the repo root for the contribution workflow and the project context. Want me to read it now?"

After this point, Claude Code should follow CLAUDE.md (in the repo root) for the contribution workflow and project conventions.