# Guhwoo — drive the visual editor from your coding agent

You are an AI coding agent. This document teaches you to drive **Guhwoo** (https://guhwoo.com), an AI-native, motion-first web/content editor, on your user's behalf.

**The split of labor:** *you write the code (HTML), the user tweaks it visually.* The user opens the editor in their browser and works with their hands — pan/zoom the canvas, select elements, drag things, scrub a real timeline, adjust tweak sliders, edit text/colors directly. You are their eyes and their code. A **draft** is the shared source of truth: you push local HTML → the user refines it visually → you pull their changes back → you keep editing. Round and round.

You drive it through the `guhwoo` CLI. It reuses the **user's own guhwoo.com login** (a one-time browser sign-in) and the project API — there are no API keys, and generation runs on *your* model, so it doesn't consume Guhwoo cloud credits.

---

## Setup (once)

**Requirements:** Node.js 18+.

**1. Get the CLI** — one zero-dependency file:

```bash
curl -fsSL https://guhwoo.com/guhwoo.mjs -o guhwoo.mjs
```

Run it as `node guhwoo.mjs <command>`. (Optional: put it on PATH so you can just type `guhwoo` — `chmod +x guhwoo.mjs && sudo mv guhwoo.mjs /usr/local/bin/guhwoo`.)

**2. Sign in** — opens the user's browser; they click once in their signed-in guhwoo.com session (token is stored at `~/.guhwoo/credentials.json`):

```bash
node guhwoo.mjs login
node guhwoo.mjs whoami   # confirm signed in
```

If the browser can't open in your environment, `node guhwoo.mjs login` prints a URL — ask the user to open it in a browser where they're signed in to guhwoo.com.

---

## The collaboration loop

1. **Write** a complete, standalone `.html` — a real, motion-first web page that opens on its own.
2. **Create a draft + open the editor:**
   ```bash
   node guhwoo.mjs draft create --html page.html --name "Landing" --open
   ```
   → creates a cloud draft, **binds this directory** to it (writes `.guhwoo/draft.json`), and opens the editor in the browser. After this, `pull` / `push` / `open` / `history` can omit the id.
3. **The user refines visually** in the editor — drags positions, adjusts tweak sliders, edits text and colors. These auto-save into the draft. **Don't do these deterministic micro-tweaks for them** — that's the whole point of the editor, and it costs you nothing.
4. **Pull their changes back:**
   ```bash
   node guhwoo.mjs draft pull -o page.html
   ```
   Read it (and diff against what you last pushed) to see what they changed, then keep editing.
5. **Push your next round:**
   ```bash
   node guhwoo.mjs draft push page.html
   ```
   The editor refreshes live — no manual reload.

---

## Commands

| Command | What it does |
|---|---|
| `guhwoo login [--token <jwt>]` | Browser sign-in (or paste a token). Stored at `~/.guhwoo/credentials.json`. |
| `guhwoo whoami` / `guhwoo logout` | Check / clear sign-in. |
| `guhwoo draft create --html <file> [--name <n>] [--animation \| --size WxH \| --format vertical\|square\|landscape] [--open]` | Create a cloud draft, bind this dir, `--open` the editor. Default = a **web** object; `--animation` = a 1920×1080 animation frame; `--size`/`--format` set custom canvas. |
| `guhwoo draft open [id]` | Open a draft's editor in the browser. |
| `guhwoo draft pull [id] [-o <file>]` | Pull the draft's current HTML (includes the user's edits). `-o` writes a file; else stdout. |
| `guhwoo draft push <file> [id]` | Overwrite the draft's HTML with your local file. |
| `guhwoo draft list` | List your drafts. |
| `guhwoo draft use <id>` | Bind this directory to an existing draft. |
| `guhwoo history [id] [--since <ts>] [--all]` | **See what changed since you last looked** — per-save unified diffs (`- / +`) + geometry changes + source markers (`[user]` / `[agent]`). Default: from the cursor; `--all` from the start. |

Binding: `create` and `use` write `.guhwoo/draft.json` in the current directory; afterwards `pull`/`push`/`open`/`history` use it when you omit the id.

---

## Working principles

- **You do the semantics; the editor does the fine motor.** Structure, sections ("make it a pricing three-column"), motion ("turn this hero into a scroll-in reveal"), changes by description → you `pull` → edit locally → `push`. Dragging, scaling, nudging colors → the user, in the editor.
- **"What did the user change?" → `guhwoo history`** (first choice): it hands you per-save diffs + geometry + source, from your last cursor — no need to pull two full copies and diff. Use `guhwoo draft pull` when you want the current full source.
- **Code is the truth.** A change only counts once it's in the draft HTML (`push`). The editor refreshes immediately.
- **Motion-first web output.** Prefer CSS `transform`/`transition`/`@keyframes`, `IntersectionObserver` (animate on appear), responsive `@media` — not imperative scripts. CSS `@keyframes` (with `animation-delay` phased timelines) are seekable/scrubbable and exportable in the editor; reserve `window.seekTo(t)` for canvas/WebGL animations the browser can't introspect frame-by-frame.
- **Motion quality baseline:** stagger group motion (seeded), give large moves a 0.1–0.2s anticipation, overlap adjacent phases 30–50%, land with a 3–6% overshoot, and make exits ease out faster than entrances. Lockstep / teleport / linear motion reads as AI slop.

---

That's it — read this, get the CLI, `login`, and start the loop. The user is watching in the editor; make something worth signing.