Laser Bot Operator Handbook (public)

Read this first, then the lessons page (/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/ — public rules tree. HTML pages live at /rules/<page>/; raw markdown at /rules/<path>.md; machine index at /rules/index.json.
• /lessons — combined lessons HTML; raw combined dump at /lessons.md.
• /color/ — MOPA colour grids and data (b4_measured.json, color_settings.json, rounds).
• /projectaddons/ — motorized Z / camera / Pi+Pico add-ons (older copy also at /workup/).
• /settings/ — material settings index; /tools/ — tools index.
• /plates/ — colour calibration plates; public JSON at /api/materials, /api/plates, /api/cite (see Colour plates API). Unified browser on /color/ and /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.

managed by laser-rules-build (/opt/laser-rules/build.py) · source editable via SSH as grokbot in rules-src · /rules/ · /lessons