# Setting up Claude Code on the server — plain-English walkthrough

## What this is
Claude Code is Claude (the same assistant) running inside a small window on
YOUR server instead of a browser tab. Because it runs on your server, it can
connect to your real MySQL database — something the chat version can never
do. You are about to give it a checklist (CLAUDE_CODE_HANDOFF.md) that tells
it exactly what to do, safely, step by step.

## Before you start
- You need to be able to log into your server (the same way you already do
  to manage gsiq.app) — usually via a program called Terminal (Mac/Linux) or
  PuTTY (Windows), using SSH.
- This crystal2 folder should already be uploaded onto the server, inside
  or next to /var/www/html/crystal.

## The six steps

1. Log into your server as you normally do.

2. Check Node.js is installed:
   ```
   node --version
   ```
   If you see a version number (like v18.x), you're fine. If you see
   "command not found," ask your usual technical contact to install Node.js
   first — it's a one-line install on most servers
   (`apt install nodejs npm` on Ubuntu).

3. Install Claude Code (one time only):
   ```
   npm install -g @anthropic-ai/claude-code
   ```

4. Move into the crystal2 folder:
   ```
   cd /var/www/html/crystal/crystal2
   ```
   (adjust the path if you placed the folder somewhere else)

5. Start it:
   ```
   claude
   ```
   A window opens. It will ask you to log in with your Claude account —
   click the link it shows you, sign in, approve. This only happens once.

6. Give it the checklist. Type exactly this and press Enter:
   ```
   Read CLAUDE_CODE_HANDOFF.md and follow it step by step. Stop and ask me
   before Task 4 (the real backtest) so I know it's about to use real data.
   ```

## What happens next
It will start reading your real database structure (safely, read-only),
compare it against what was guessed in the engine, fix the mismatches, and
eventually run a real accuracy test against your real historical data. It
will show you its work as it goes — you can watch, ask questions, or say
"stop" at any point.

## Safety, in plain terms
- It can only READ from your existing tvviewers tables — the rules file
  explicitly forbids it from changing or deleting anything there.
- It only writes to two brand-new tables (estimate_runs, run_overrides)
  that don't exist yet and don't affect the current live Crystal.
- Your database password never appears in anything it shows you or saves
  — it reads it from a config file you set up once, the same way any
  password manager works.

## If anything feels wrong
Type "stop" — it will stop immediately and wait for you. Nothing it does
is irreversible except database reads, which change nothing.