# The Drawing Board — how to use it

This is the plain-English manual. Keep it with the project; it explains everything
without assuming you remember how any of it works.

---

## What it is

A web page where you can look at the sculpture drawings, draw on them, write down
what you want changed, and save it. Whatever you save goes straight into the project
folder, where the people and AI workers who do the drawing will find it.

**Why it exists:** some things are easier to point at than to describe.

---

## Opening it

Two addresses. Use whichever fits where you are:

- **At home:** `http://10.0.0.177:8082`
- **Away from home:** `http://100.101.221.93:8082` — this one needs Tailscale
  running on your phone or laptop

**The password is the same one as your book manager.** Nothing new to remember.
Your browser will ask for it. Put `mike` as the username.

> If the page will not load at all: you are probably on the wrong address, or
> Tailscale is not connected. Try the other one.

---

## The screen, top to bottom

**Across the top:** the size of the picture you have open, who you are signed in as,
a **Manual** link (this page), **Undo**, **Clear**, and the big blue
**Save my changes** button.

**The second row:** a drop-down of everything you can open, **Import a picture**, **Draw
from scratch**, the drawing tools, **Insert shape**, **Select area**, seven colours, a
width slider, and **– / +** to zoom. **Whole page** appears here too, once you have cut
into a detail.

**The big white area:** the picture. That is where you draw.

**The bottom:** a box to write in — *"Changes I want"* — then any earlier markups,
and (if you are the owner) the list of people who can get in.

---

## Drawing on a picture

- **Pick what to open** from the drop-down. It shows every drawing the project has
  made, plus anything you have imported. 📐 means a drawing, 📷 means a picture you
  brought in.
- **Pick a tool:** Pen (draw freehand), Line, Arrow, Box, Circle, or Text.
- **Insert shape** opens a palette with more shapes — **Triangle, Diamond, Cross,
  Star**, and Box and Circle again. Tap one, then drag on the picture.
- **Pick a colour** by tapping a circle. **Set the width** with the slider — thin for
  pointing, thick for emphasis.
- **Draw with your finger** or with a mouse. Same thing either way.
- **Zoom with – and +.** Use it. A big drawing shrunk to fit your phone is not
  readable, and the zoom keeps you in control of the detail.
- **Undo** takes back the last mark. **Clear** wipes the marks from the picture you
  are looking at (it will ask first).

**Text** asks you what to write, then puts it where you tapped.

---

## Starting with a blank page

Press **📄 Draw from scratch**, then choose **Wide page**, **Tall page** or **Square
page**. A blank white page appears in the list, exactly like a picture you imported, and
you draw on it the normal way.

This is how you add **a part of your own** to the project: draw it, write what it is in
the changes box, and save. It lands in the same place as every other markup, so the
drawing workers find it and know it came from you.

---

## Cutting in to a detail

**🔍 Select area** is for working closely on one part of a big drawing.

Tap it, then drag a box around the part you care about. The board cuts into that area and
fills the screen with it, so you can mark it accurately instead of squinting at a drawing
shrunk to fit your phone. Your colours and width work exactly as before, and **– / +**
still zooms further in.

**↩ Whole page** takes you back out when you are done. Nothing is lost by cutting in or
out — marks are stored against the picture itself, so they stay where you put them.

---

## Bringing in your own pictures

Press **📷 Import a picture**, then choose a photo or a picture from your phone.

You will be asked *"What is this picture?"* — put a few words in. Those words become
the file name and a note, so that later nobody has to guess what the photo was of.

Good things to import: a photo of the spot in the yard, a sketch on paper, a picture
of a sculpture you like, a screenshot of something someone sent you.

Then draw on it and save, exactly like a drawing.

> **iPhone photos:** if it says it could not read the picture, that is the HEIC
> format. Open Settings → Camera → Formats → **Most Compatible**, or share the photo
> as a JPEG, and try again.

Large photos are shrunk down automatically before they are sent, so this works fine
on a phone signal.

---

## Saying what you want changed

The box at the bottom is as important as the drawing. **The words are the instruction;
the marks show where it applies.**

Say it the way you would say it out loud:

> *"Drop all five blooms 6 inches. The counterweight looks too heavy in this drawing —
> show it smaller."*

> *"This is the spot in the yard. I want it about here, facing the house."*

You can save marks with no words, or words with no marks. You can also save with both
— that is usually best.

---

## Saving

Press **Save my changes**. It tells you in plain words what it saved.

**Saving never damages the drawing.** Your marks are put on a *copy*. The original
drawing is untouched, so nothing you do here can break the real thing.

---

## Where your changes go

Inside the project, in the folder `output/markup/`. Each save makes two files:

- a **picture** — the drawing with your marks on it, so you can just look at it
- a **data file** — the same marks as numbers, plus your words

If you want to look at something you saved earlier, open **"Earlier markups"** at the
bottom of the page — there is a link to the marked-up picture.

**Read this next part, it is the whole point:** the workers who draw these sculptures
are told to **read your newest markup before they redraw anything.** Your words are
the work order; your marks show where. If something you asked for contradicts the
design sheet, they are told to come back and ask you which one wins, instead of
quietly choosing.

---

## Letting other people in

Only you see this section. Open **"People who can open this"** at the bottom.

Press **Add someone** and type their name. You get two things:

1. A **password** made for them — four words and a number, easy to read out over the
   phone.
2. A **message** ready to send them, with the address, the username and the password.
   Press **Copy that message** and paste it into a text or an email.

**They must be able to reach your network.** That is the one real catch. Somebody
away from your house needs **Tailscale** set up on their device, and you have to share
this machine with them in your Tailscale admin page. Someone sitting in your house,
on your wifi, can just open the home address.

What they can do: look at everything, draw on it, write comments, import their own
pictures, and save. Every save records **their name**, so you can always see who said
what. They cannot add or remove people — only you can.

---

## When something looks wrong

- **The page will not open** — try the other address; check Tailscale is connected.
- **It asks for a password over and over** — the username is `mike`, and the password
  is the same as your book manager. A private/incognito window clears a stuck one.
- **My marks vanished** — you changed which drawing you had open, or pressed Clear.
  Marks are only remembered until you save.
- **Nothing draws for a moment after you switch drawings** — that is deliberate. The new
  picture is still loading, and a mark drawn in that moment used to land off the page and
  look like it had been swallowed. Wait until the size appears at the top, then draw.
- **The picture will not open** — it may have been moved or renamed on disk. Reload
  the page to refresh the list.
- **Nothing happens when I press Save** — write a note *or* draw something first; an
  empty save is refused on purpose.

---

## For whoever works on this next

Plain-English manual above; engineering notes below.

- Lives in `app/`: `server.py` (Python standard library only — no venv, no packages),
  `index.html` (one page, plain JavaScript), `MANUAL.md` (this file),
  `people.json` (accounts, `chmod 600`, passwords stored as PBKDF2-SHA256 hashes).
- Runs as a systemd **user** service, no sudo: `systemctl --user status drawingboard`,
  restart with `systemctl --user restart drawingboard`, watch it with
  `journalctl --user -u drawingboard -f`.
- Port 8082 (env `DRAWING_BOARD_PORT`). Host `0.0.0.0` (env `DRAWING_BOARD_HOST`).
- Accounts live in `people.json`. On first run it is seeded from the host's existing
  password file (env `DRAWING_BOARD_AUTH`, default the book manager's `auth.json`), so
  there is one password per host. **Delete `people.json` only deliberately** — it
  removes everybody's access, including the owner's.
- Saves go to `output/markup/`; imports go to `output/uploads/`; drawings are read
  from `output/`. Mark coordinates are in **image pixels**, never screen pixels.
- The standing rule that makes the loop work is in the project's `.hermes.md`:
  read the newest markup before revising a drawing, treat the typed notes as the
  work order, and flag a contradiction rather than resolving it.
- It refuses to start with no accounts rather than serving the drawings unprotected.
