# Laser Bot Operator Handbook (public)
Read this first, then the lessons page ([/lessons](/lessons)). Be token-efficient. The owner presses Start. The bot never does.

## 1. Machine
- ComMarker B4 60 W MOPA fiber (JPT-class source), JCZ USB-Lite controller, LightBurn 1.7.08.
- 110 mm lens, 110x110 field, correction file jcz110.cor. **Job centre = 55,55.** 63,63 is obsolete.
- Galvo calibration was finalised 2026-10-15. The calibration kit and its history live in the calibration folder (B4_CALIBRATION_KIT).

## 2. Loading a file into LightBurn safely
1. Check the LightBurn window title. A `*` means unsaved changes. **Ask the owner before discarding them**, unless the owner names that project to discard.
2. If LightBurn has to restart, find its PID with `ps` + `awk` and kill only that PID. **Never `pkill -f`**, because it can match other processes.
3. Relaunch detached (`nohup setsid lightburn <file> &`) so it survives the shell.
4. **Never press Start. Never touch LightBurn while a job is burning.** If the owner says they will load the file, don't close or relaunch anything.
5. "Cut Selected Graphics" is on, so the owner presses Ctrl+A before Start.

## 3. Folder layout (laser root)
- `coins/` coin jobs (recovery, brass, lion_portrait, ...). The bot's work goes in `grok/` subfolders.
- `washers/` washer designs and colour tests.
- `colortest/` colour calibration (`ss245_rgb/` = 8-face RGB tester).
- `tools/` scripts (below). `libraries/` LightBurn libraries (`grok/HD_fill_black.clb`).
- `calibration/` galvo and colour calibration kits. `pre55/` backups from before the 55,55 recentre and old ss245 outputs.
- `LASER_LESSONS.md` (lessons, read before every job), `INDEX.md` / `MANIFEST.csv` (file index).

## 4. Tools
- `recenter55.py` recentres projects from 63,63 to 55,55 (keeps `<name>.pre55.lbrn2`). `--dry` audits without writing.
- `to_ss245.py <file|folder>` makes `<name>_ss245.lbrn2` (24.5 mm polished stainless, centre 55,55, colours from the palette, deep stacks collapsed into one layer per colour). `--map PATTERN=key` overrides a role. `--hd-black` writes `*_ss245_hdblack.lbrn2`.
- `est_time.py <files>` gives a rough burn time (filled area / interval / speed x passes x crosshatch + 15%).
- `dump_layers.py <folder>` writes a `_LAYERS.txt` for every .lbrn2.
- `brass_rules.py` `apply()` adds the brass CLEAN/POLISH layers idempotently.
- `ss_color_palette.json` holds the stainless colour presets plus verification status and observed large-area colours.
- `gen_ss245_rgb.py` (in colortest/ss245_rgb) regenerates the RGB tester and its plan CSV.

## 5. Design rules
- The design (letters/logo) is RAISED and unburned. The field inside the work circle is DEEP-ETCHED. Outside the work circle is transparent: nothing burns there, and no background, glow or haze.
- Brass recovery coin: 39.5 mm with a lip, so the work circle is 37.5 mm.
- Traces: copy clean shapes and don't redraw. Remove specks and glow, and keep clean gaps. QC whole letters, bottoms included, against the source.
- Every .lbrn2 gets a matching `_LAYERS.txt` and an output-off FRAME layer.
- Never edit another agent's (Claude's) files. Write new files and keep the originals.
- Christian designs: Baptist-friendly, no crosses, understated.

## 6. Material rules
**Brass/copper deep engraving:** insert a CLEAN (20 %, 1500 mm/s, 100 kHz, 200 ns, 0.01 x2, crosshatch) after every 5 deep passes. The LAST layer is a full-surface POLISH (18 %, 2000 mm/s, 350 kHz, 10 ns, 0.01). Never use these on stainless, polished or anodized pieces.
**Black-field brass order:** (1) deep engraving + CLEANs + POLISH; (2) BLACK on the field only (40 %, 500, 40 kHz, 200 ns, 0.02 x2, untested); (3) final LETTER CLEAN on the raised letters and rings only (brass CLEAN settings, x1).
**Stainless colour = surface mark:** use one lean layer per colour, with a separate layer for each shade. Never copy brass deep stacks.
- HD fill black (14 purple layers + 2 blue facets, ~130 min per coin, glossy black) is used only on purpose.
- For black fields, use **4 passes of the HD-black purple setting** (15 %, 567, 280 kHz, 80 ns, 0.004, crosshatch x2, angles 0/45/90/135), about 14 min.
- The hard blacks (20 %/567 and 30 %/300/200 ns) **spark and burn on fields**. Keep them for small marks and lines.
- Big areas run hotter and paler than test cells. Keep colour tests at 30 % or less.
- Anodized aluminium black: 12 %, 1500 mm/s, 50 kHz, 0.045, 1 pass. Brass colours are unverified, so flag heat and cool between passes.

## 7. Verified stainless colours (polished, by eye)
| Preset | Settings (crosshatch, x2) | Test cell | Large field (2026-10-15) | Mapping confidence |
|---|---|---|---|---|
| purple R1-0106 | 15 %, 567, 280 kHz, 80 ns, 0.004 | deep purple-black | lavender / light mauve | medium |
| deep blue R1-0805 | 7.5 %, 700, 119 kHz, 60 ns, 0.005 | deep blue | slate blue-grey | medium-low |
| blue R1-0904 | 15 %, 1200, 230 kHz, 60 ns, 0.005 | good blue | pale grey-green / silver | medium |
| black (washer) | 20 %, 567, 280 kHz, 80 ns, 0.004 | black | brown-black, sparks, avoid on fields | high |
| black lines | 30 %, 300, 50 kHz, 200 ns, 0.01 | dark lines | brown-black, sparks | high |
| gold R1-1202 | 48.4 %, 317, 61.5 kHz, 60 ns, 0.0287 | untested | never fired (layer was off) | n/a |
Energy-density model: E = W / (speed x interval) J/mm², W = power% x 60 W. Dose = E x 2 (crosshatch) x passes.

## 8. Open work
- The RGB 8-face tester (4 coins, 26 cells per face, plan CSV, ~21 min total) is ready and not burned.
- The colorfield v2 coin (gold removed, black wedges = 4-pass HD black, ~14 min) is ready and not burned.
- Gold is still untested. Whether purple came out lavender and deep blue came out slate, or the other way round, is uncertain; a single swatch of each would confirm it.

## 9. Site (laserview.hankelsner.tech)
- [`/rules/`](/rules/) — public rules tree. HTML pages live at `/rules/<page>/`; raw markdown at `/rules/<path>.md`; machine index at [`/rules/index.json`](/rules/index.json).
- [`/lessons`](/lessons) — combined lessons HTML; raw combined dump at [`/lessons.md`](/lessons.md).
- [`/color/`](/color/) — MOPA colour grids and data (`b4_measured.json`, `color_settings.json`, rounds).
- [`/projectaddons/`](/projectaddons/) — motorized Z / camera / Pi+Pico add-ons (older copy also at [`/workup/`](/workup/)).
- [`/settings/`](/settings/) — material settings index; [`/tools/`](/tools/) — tools index.
- [`/plates/`](/plates/) — colour calibration plates; public JSON at `/api/materials`, `/api/plates`, `/api/cite` (see [Colour plates API](api.md)). Unified browser on [`/color/`](/color/) and [`/colors/`](/colors/); cite **Plate 31, A8**.
- Source markdown on the VPS: `/srv/web/laserview.hankelsner.tech/rules-src/`. Publish with `laser-rules-build`.
- The site is hosted by the VPS bot. Send content to the VPS agent, which publishes it. The laser bot doesn't edit the site directly.

## Colour DB v3 (cut settings + sub-layers)
- One colour = one LightBurn layer; multi-pass stacks use `sublayers[]` (HD fill black = 16).
- Full Cut Settings Editor fields live in `cut_settings` + each sub-layer. Site browsers show/filter/edit them (Hank-gated writes).
- `GET /api/library.clb` exports one Entry per colour with sibling CutSettings per sub-layer.
- **Sub-layer .clb/.lbrn2 serialization is UNVERIFIED** until Hank does one LightBurn open-test. >11 sub-layers may need a split. Do not present exports as verified.