# 360LM Walkthroughs — manual install on your laptop

A Playwright-based replacement for CiC chat walkthroughs. Opens a real Chromium
window, drives it for you, pauses at sensitive points (login, OTP, CAPTCHA).
Scripts also work as automated Playwright tests when run with `WALKTHROUGH_TEST=1`.

> If you'd rather have Claude Code do this for you, paste
> [`walkthroughs_install_for_claude.txt`](walkthroughs_install_for_claude.txt)
> as a prompt into Claude Code (or Claude Desktop) and follow along.

## Where it goes

```
~/360lm-walkthroughs/
├── bin/walkthrough        ← the CLI you'll run
├── lib/                   ← runner + HUD + VPS helpers
├── scripts/               ← actual walkthroughs (hello.js, brevo_*.js, …)
└── package.json
```

VPS-side helpers SSH from your laptop to `root@srv1111289.hstgr.cloud` to do
things like `dig`, edit `.env`, restart docker, query Postgres. You need
passwordless SSH set up (which you already have if you SSH to the VPS today).

## Prerequisites

### 1. Node 20 or higher

```bash
node -v
```

If it prints `v20.x` or higher, skip. Otherwise:

- **macOS:** `brew install node`
- **Linux (Ubuntu/Debian):** see [nodesource.com/](https://github.com/nodesource/distributions) (don't use the old `apt install nodejs` — too old)
- **Windows:** download the LTS installer from [nodejs.org](https://nodejs.org), pick "Add to PATH", reopen your terminal

### 2. `ssh`, `curl`, `tar`

Already present on macOS and Linux. On Windows, use **Git Bash** or **WSL** — they include all three.

### 3. (Optional) `dig`

The framework runs DNS lookups locally if `dig` is present, otherwise it proxies through SSH (slower but works).
- macOS: `brew install bind`
- Linux: `sudo apt install dnsutils`
- Windows: skip — the framework will use SSH

### 4. Passwordless SSH to the VPS

```bash
ssh root@srv1111289.hstgr.cloud "echo ok"
```

If that prints `ok` without prompting for a password → you're set.
If it asks for a password → run:

```bash
ssh-copy-id root@srv1111289.hstgr.cloud
```

…enter the password once, then re-test. (If you don't already have a key:
`ssh-keygen -t ed25519` first.)

## Install — option A: one-line installer

```bash
curl -fsSL https://srv1111289.hstgr.cloud/walkthroughs/install.sh | bash
```

The script:
1. Verifies Node ≥ 20, npm, ssh, curl, tar
2. Creates `~/360lm-walkthroughs/`
3. Downloads `walkthroughs.tar.gz` and extracts
4. Runs `npm install`
5. Runs `npx playwright install chromium` (downloads ~150 MB, one-time)
6. Tests passwordless SSH to VPS
7. Appends `export PATH="$HOME/360lm-walkthroughs/bin:$PATH"` to your `~/.zshrc` or `~/.bashrc`

After it finishes:

```bash
source ~/.zshrc                # or ~/.bashrc
walkthrough doctor             # all five lines should be green ✓
walkthrough list               # shows: hello
walkthrough run hello          # self-test
```

The "hello" walkthrough opens Chromium → navigates to example.com → shows
a HUD card in the bottom-right corner. Click **▶ Continue** to advance steps.

## Install — option B: step-by-step (use if A fails)

```bash
# 1. Create directory
mkdir -p ~/360lm-walkthroughs
cd ~/360lm-walkthroughs

# 2. Download + extract
curl -fsSL https://srv1111289.hstgr.cloud/walkthroughs/dist/walkthroughs.tar.gz | tar xz

# 3. Install Node deps
npm install

# 4. Download Chromium for Playwright (one-time, ~150 MB)
npx playwright install chromium

# 5. Verify
./bin/walkthrough doctor
./bin/walkthrough list
./bin/walkthrough run hello

# 6. Add to PATH so you can just type `walkthrough` from anywhere
# Pick the shell rc file matching your shell:
echo 'export PATH="$HOME/360lm-walkthroughs/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

## What "walkthrough doctor" should print

```
Diagnostics:
  ✓ Node          v20.11.1
  ✓ Playwright    installed
  ✓ ssh           OpenSSH_9.6p1, …
  ✓ dig           DiG 9.18.x
  ✓ SSH→VPS       passwordless OK
```

If any line is ✗, fix that piece and rerun. The most common failure is
**SSH→VPS** when the key isn't on the VPS yet — `ssh-copy-id` and retry.

## What "walkthrough run hello" looks like

A Chromium window opens at `https://example.com`. In the bottom-right corner,
a small navy card appears reading:

```
360LM WALKTHROUGH                    Step 1 / 3
Sanity check
You should see the example dot com page in this browser, and
this HUD card in the bottom right corner. The HUD is injected
by the framework on every page.
                Waiting for you…
[ ▶ Continue ] [ ⏭ Skip ] [ ⏹ Abort ]
```

Click **▶ Continue**, the script navigates to google.com, the card updates,
click again, the script finishes. **No tokens consumed during the run** —
this is all local Playwright.

## Updating

When new walkthroughs are authored, pull them with:

```bash
walkthrough update          # re-downloads tarball, extracts over existing files
walkthrough list            # see what's new
```

## Resetting state

Each walkthrough saves progress in `~/.360lm-walkthroughs/<name>.state.json`.
Re-running picks up where you left off. To start over:

```bash
walkthrough reset <name>
```

## Test mode (skip pauses, run headless)

Useful for CI / regression / quick smoke:

```bash
WALKTHROUGH_TEST=1 walkthrough run brevo_domain_auth
```

In test mode the browser is headless and every `pause()` is a no-op — the
script blasts through end-to-end. Assertions inside step functions become
the test contract.

## Uninstall

```bash
rm -rf ~/360lm-walkthroughs ~/.360lm-walkthroughs
# then remove the PATH line from your shell rc file
sed -i.bak '/360lm-walkthroughs\/bin/d' ~/.zshrc        # or ~/.bashrc
```

## Troubleshooting

| Symptom | Likely fix |
|---|---|
| `Node.js not found` after install | Reopen the terminal; Windows installer requires a new shell |
| `npm install` complains about engines | Node version too old; upgrade to Node 20+ |
| `npx playwright install chromium` stalls | First-run download is ~150 MB; let it finish or run `npx playwright install chromium --with-deps` for Linux |
| `walkthrough run hello` opens browser but no HUD shows | Browser blocked the inline script — open devtools console, paste the error here |
| SSH→VPS fails with "Permission denied (publickey)" | Run `ssh-copy-id root@srv1111289.hstgr.cloud` to install your key |
| `dig` says command not found on macOS | `brew install bind` (the package providing dig) |
| `walkthrough` command not found after install | Run `source ~/.zshrc` (or `~/.bashrc`); or invoke as `~/360lm-walkthroughs/bin/walkthrough` |
| Chromium pops a "verify you're human" CAPTCHA on Hostinger | Hostinger may flag the Playwright profile on first run. Solve once manually; the persistent profile remembers afterward |

## How this compares to CiC prompts

| | CiC prompt | Walkthrough |
|---|---|---|
| First run setup | none | ~10 min (this guide) |
| Per-run wall-clock | 30–60 min chat | 5–10 min |
| LLM tokens per run | 50K–200K | ~0 |
| Re-runnable | one-shot | infinite (state-saved) |
| Doubles as test? | no | yes (`WALKTHROUGH_TEST=1`) |
| Resilient to UI redesigns | yes (LLM adapts) | needs script update |
| Good for one-off tasks | yes | overkill |
| Good for recurring setup | painful | excellent |

The take-away: CiC is the right tool for **open-ended troubleshooting and one-off
exploration**; walkthroughs are the right tool for **anything you'll do more
than once** and anything you want a regression test for.