# 360LM Walkthroughs

Playwright-based human-in-loop walkthroughs. Drop-in replacement for CiC chat prompts:
- ~0 LLM tokens at runtime (only at authoring)
- 3–6× faster wall-clock vs CiC
- Scripts double as regression tests (`WALKTHROUGH_TEST=1` skips pauses)

## Why this exists

A CiC chat prompt walks a human through a task by reading steps aloud and waiting
for verbal confirmation. Every back-and-forth burns LLM tokens, every screen-read
adds delay. This framework replaces that pattern with **Playwright doing the
clicks for you** while **pausing for the parts only a human can do** (sign in,
OTP, CAPTCHA, sensitive review).

## Quick start

```bash
curl -fsSL https://srv1111289.hstgr.cloud/walkthroughs/install.sh | bash
walkthrough doctor          # sanity check Node / Playwright / SSH / dig
walkthrough list            # what's available
walkthrough run hello       # framework self-test
walkthrough update          # pull latest scripts
```

## Authoring a walkthrough

```js
// scripts/my_thing.js
const { WalkthroughRunner } = require('../lib/runner');
const { dig, sshRun, brevoDomain } = require('../lib/vps-ops');

const w = new WalkthroughRunner('my_thing');

w.step('Sign in to Hostinger', async ({ page, pause, say }) => {
  await page.goto('https://hpanel.hostinger.com');
  await say('Sign in', 'Use your normal credentials. The script will wait.');
  await pause('Click Continue once you reach the dashboard.');
});

w.step('Programmatic verification', async ({ say }) => {
  const txt = dig('360degreelogicalmktg.com', 'TXT');
  const dom = await brevoDomain('360degreelogicalmktg.com');
  await say(
    'Check complete',
    `TXT records: ${txt.length}<br>Brevo verified: ${dom.body.verified}<br>Brevo authenticated: ${dom.body.authenticated}`
  );
});

w.run().catch(e => { console.error(e); process.exit(1); });
```

`pause(title, bodyHtml)` shows the HUD overlay with **Continue / Skip / Abort** buttons
and waits for the user to click. `say(title, bodyHtml, status)` updates the HUD with
status without pausing.

State is auto-saved after each step in `~/.360lm-walkthroughs/<name>.state.json` —
re-running picks up where you left off. Use `walkthrough reset <name>` to forget.

## Test mode (no pauses, headless, CI-friendly)

```bash
WALKTHROUGH_TEST=1 walkthrough run my_thing
```

In test mode, every `pause()` becomes a no-op and the browser runs headless.
Assertions inside step functions become the test contract.

## Layout

```
~/360lm-walkthroughs/
├── bin/walkthrough         # CLI: list / run / update / reset / doctor
├── lib/
│   ├── runner.js           # WalkthroughRunner class + HUD injection
│   ├── hud.js              # On-page HUD overlay (string)
│   └── vps-ops.js          # SSH, dig, docker, psql, Brevo API helpers
├── scripts/
│   ├── hello.js            # Sanity-test walkthrough
│   ├── brevo_domain_auth.js
│   ├── brevo_api_key.js
│   └── ...
└── package.json
```

## Environment overrides

| Var | Default | Purpose |
|---|---|---|
| `LM_SSH_HOST` | `srv1111289.hstgr.cloud` | VPS hostname |
| `LM_SSH_USER` | `root` | SSH user |
| `LM_REPO_URL` | `https://srv1111289.hstgr.cloud/walkthroughs` | Where `update` pulls from |
| `WALKTHROUGH_TEST` | (unset) | If `1`, run headless + skip pauses |

## Comparison: when to use what

| Task | CiC prompt | Playwright walkthrough | Plain Playwright test |
|---|---|---|---|
| One-off troubleshooting | ✓ best | ✗ overkill | ✗ |
| Repeatable setup (Brevo, OpenRouter, etc.) | works but slow | ✓ best | – |
| PWA functional testing | ✗ | – | ✓ best |
| Regression suite | ✗ | works (test mode) | ✓ best |
| Token budget | high | ~0 | ~0 |