bbolinger · bbolinger · Jul 23, 2026 · Jul 23, 2026
diff --git a/README.md b/README.md
@@ -1,25 +1,36 @@
-# Snapmaker U1 Toolkit
+# Snapmaker U1 Toolkit — Print From Your Phone with Telegram
 
-### Safe AI Print Operator — Snapmaker U1 first
+[![tests](https://github.com/bbolinger/snapmaker-u1-toolkit/actions/workflows/tests.yml/badge.svg)](https://github.com/bbolinger/snapmaker-u1-toolkit/actions/workflows/tests.yml)
 
-![Hermes Agent + Snapmaker U1 — safety-staged print automation](docs/images/hero-hermes-snapmaker.png)
+Safely slice, preview, upload, monitor, and start [Snapmaker U1](https://snapmaker.com/snapmaker-u1) prints remotely through Telegram, OrcaSlicer, Moonraker, and an optional local AI agent.
 
-[![tests](https://github.com/bbolinger/snapmaker-u1-toolkit/actions/workflows/tests.yml/badge.svg)](https://github.com/bbolinger/snapmaker-u1-toolkit/actions/workflows/tests.yml)
+Send an STL, 3MF, or ZIP from your phone. The toolkit analyzes the model, recommends print settings, slices it locally with OrcaSlicer, generates plate previews, verifies the loaded filament and toolhead, photographs the print bed, and asks for explicit approval before starting.
 
-> Inspired by safety-staged agent workflows, this project applies the pattern specifically to the [Snapmaker U1](https://snapmaker.com/snapmaker-u1) — local slicing, visual previews, camera-gated checks, and explicit operator approval. Useful from the command line on its own; an AI agent like Hermes is the optional remote-control layer on top.
+![Snapmaker U1 remote printing workflow from a phone through Telegram, OrcaSlicer, camera verification, and human-approved print start](docs/images/snapmaker-u1-print-from-phone-telegram-flow.png)
 
-This is how AI should touch physical machines: **plan, explain, preview, ask, verify, then act only within a narrow approved boundary.**
+## What you can do
 
----
+- Print to a Snapmaker U1 from your phone through Telegram.
+- Slice STL and 3MF files with headless OrcaSlicer on Linux, WSL, or Windows.
+- Preview model orientation, plate layout, toolpaths, and important print settings.
+- Upload G-code through the U1's Moonraker/Klipper LAN interface.
+- Verify toolheads and filament before heating or motion.
+- Receive first-layer, final-layer, and completed-print camera photos.
+- Require a fresh bed-camera image and human approval before every toolkit-started print.
+- Run the deterministic CLI tools without AI, or add Hermes with a local LLM for the phone workflow.
+
+The AI does not receive unrestricted printer control. Deterministic scripts own slicing, verification, uploading, monitoring, and the single-use print-start approval gate. See the [safety model](docs/SAFETY.md) for the exact boundary.
+
+This is how AI should touch physical machines: **plan, explain, preview, ask, verify, then act only within a narrow approved boundary.**
 
 ## See it in action
 
-A single local model takes a zip of eight STLs all the way to a printing plate in
-about 160 seconds (with local LLM), entirely over Telegram and entirely on local hardware.
-Nothing starts until a human replies "yes."
+A local model takes a ZIP of eight STLs from Telegram to a reviewed printing plate in about 160 seconds, entirely on local hardware. Nothing starts until a human approves the fresh bed photo.
 
 https://github.com/user-attachments/assets/f3acea60-4ebe-4059-8158-92abd207f4ec
 
+**Start here:** [print from your phone](docs/PRINT-FROM-PHONE.md) · [install the toolkit](#install) · [set up Telegram](docs/TELEGRAM-SETUP.md) · [run headless OrcaSlicer](docs/HEADLESS.md) · [troubleshoot](TROUBLESHOOTING.md)
+
 ---
 
 ## The flow

diff --git a/docs/HEADLESS.md b/docs/HEADLESS.md
@@ -1,6 +1,6 @@
-# Headless OrcaSlicer setup
+# Headless OrcaSlicer Setup for Snapmaker U1
 
-How to slice from the CLI with no GUI (containers, CI pipelines, agent workflows): which OrcaSlicer build to use, the 3-profile load order, a real inheritance pitfall and its workaround, plus the orientation-review and thumbnail-injection tools.
+Use OrcaSlicer from the command line to slice STL and 3MF files for a Snapmaker U1 with no GUI. This guide covers the correct upstream build, the three-profile load order, Linux and Windows setup, profile-inheritance pitfalls, orientation review, thumbnail injection, and G-code validation.
 
 [← Back to the README](../README.md)
 

diff --git a/docs/PRINT-FROM-PHONE.md b/docs/PRINT-FROM-PHONE.md
@@ -0,0 +1,124 @@
+# How to Print to a Snapmaker U1 From Your Phone
+
+Snapmaker U1 Toolkit lets you send an STL, 3MF, or ZIP through Telegram, slice it locally with OrcaSlicer, review the plate and settings, verify the printer with a fresh camera image, and approve the print from your phone. The printer stays on your LAN, and the workflow does not start a print until you explicitly approve the exact prepared job.
+
+[← Back to the README](../README.md)
+
+## What the phone workflow includes
+
+```text
+Phone → Telegram → local host → OrcaSlicer → previews → Moonraker upload
+                                                      ↓
+                           fresh bed photo → your YES → safety gate → U1
+```
+
+The Telegram chat is the interface, not the safety controller. Deterministic toolkit scripts handle the model, profiles, G-code, printer state, camera checks, upload, approval token, and print monitoring. Hermes and the local LLM relay the workflow's choices and artifacts.
+
+## Before you begin
+
+You need:
+
+- A Snapmaker U1 reachable from a Linux or WSL host on the same LAN.
+- Python 3.9 or newer.
+- Upstream OrcaSlicer 2.4.0 or newer.
+- A working Hermes gateway connected to a private Telegram chat.
+- Your numeric Telegram user ID in Hermes' `TELEGRAM_ALLOWED_USERS` configuration.
+
+Native Windows can run the core toolkit, but the current Hermes deployment scripts target Linux paths. See [Windows setup](WINDOWS.md) if the host is Windows.
+
+## 1. Install and verify the core toolkit
+
+```bash
+git clone https://github.com/bbolinger/snapmaker-u1-toolkit.git
+cd snapmaker-u1-toolkit
+python3 -m pip install -r requirements.txt
+cp .env.example .env
+```
+
+Edit `.env` and set `SNAPMAKER_U1_HOST` to the U1's LAN IP, then run the read-only checks:
+
+```bash
+python3 tools/fetch_snapmaker_profiles.py
+python3 scripts/u1_slice_workflow.py --help
+python3 scripts/snapmaker_u1_status.py
+```
+
+Follow the [main installation guide](../README.md#install) if a dependency or network check fails.
+
+## 2. Prove slicing and upload-only mode first
+
+Before involving Telegram, prepare one model from the command line without starting the printer:
+
+```bash
+python3 scripts/u1_slice_workflow.py model.3mf \
+  --tool T1 --material PETG --orient auto \
+  --profile 0_20_strength_snapmaker_u1_0_4_nozzle \
+  --supports auto --upload-only --yes
+```
+
+List the profile slugs available on your host with:
+
+```bash
+python3 scripts/u1_profile_picker.py
+```
+
+`--upload-only` sends the prepared G-code to Moonraker storage with printing disabled. It is the safest end-to-end setup test.
+
+## 3. Add the toolkit to Hermes
+
+Run these commands on the Linux host or inside the Hermes container. Let each command finish before starting the next one.
+
+```bash
+hermes skills install bbolinger/snapmaker-u1-toolkit/skills/3d-printer-slicing-automation
+bash deploy_to_runtime.sh
+python3 adapters/hermes/install.py
+bash tools/install_hermes_u1_hooks.sh
+```
+
+Restart the Hermes gateway from a separate terminal, then verify the operator hooks:
+
+```bash
+hermes gateway restart
+bash tools/install_hermes_u1_hooks.sh --verify
+```
+
+If more than one Telegram user is allowed, bind approvals to the intended operator in the runtime `.env`:
+
+```bash
+U1_OPERATOR_BINDING=telegram:<your-numeric-telegram-user-id>
+```
+
+See [Snapmaker U1 Telegram setup](TELEGRAM-SETUP.md) for the integration details and failure checks.
+
+## 4. Send a model from your phone
+
+In the private Telegram chat connected to Hermes:
+
+1. Attach one `.stl` or `.3mf` file, or a `.zip` containing multiple STL parts.
+2. Choose the parts, orientation, toolhead, material, profile, supports, and action when prompted.
+3. Review the plate preview, 3D toolpath view, and generated `review.md` settings summary.
+4. Inspect the fresh bed-camera photo.
+5. Reply `YES` only if the bed is clear and the prepared job is correct.
+6. Use the countdown's **CANCEL** button or reply `CANCEL` if you need to stop the pending start.
+
+The approval is single-use and bound to the operator, request revision, and G-code hash. A changed or stale plan is refused instead of started.
+
+## 5. Monitor the print remotely
+
+The toolkit can send first-layer, last-layer, pause/resume, and completed-print photos through Telegram. Monitoring runs as ordinary scheduled scripts and does not require an LLM turn.
+
+The full jobs and cadence are documented under [Always-on print monitoring](../README.md#always-on-print-monitoring--no-agent-required).
+
+## Common setup problems
+
+- **No printer status:** confirm `SNAPMAKER_U1_HOST` and Moonraker port `7125` are reachable from the host.
+- **No profiles:** run `tools/fetch_snapmaker_profiles.py`; extracting profiles from successful printer history is also recommended.
+- **Wrong material or layer height in G-code:** follow the [headless OrcaSlicer profile-loading checks](HEADLESS.md#headless-profile-loading-pitfall-read-this).
+- **Telegram shows no native form:** rerun `python3 adapters/hermes/install.py`, restart the gateway, and verify that both Hermes plugins loaded.
+- **YES does nothing:** rerun `bash tools/install_hermes_u1_hooks.sh --verify`. Do not bypass the failed gate or call Moonraker directly.
+
+For detailed diagnostics, see [TROUBLESHOOTING.md](../TROUBLESHOOTING.md).
+
+---
+
+[Install](../README.md#install) · [Telegram setup](TELEGRAM-SETUP.md) · [Headless OrcaSlicer](HEADLESS.md) · [Safety model](SAFETY.md)
diff --git a/docs/TELEGRAM-SETUP.md b/docs/TELEGRAM-SETUP.md
@@ -0,0 +1,89 @@
+# Snapmaker U1 Telegram Bot Setup
+
+Use your existing Hermes Telegram chat to send models to Snapmaker U1 Toolkit, answer the print form with native buttons, receive previews and camera photos, and approve a prepared print. The integration uses the same Hermes bot and conversation; it does not require a second Telegram bot token.
+
+[← Back to the README](../README.md)
+
+## How Telegram fits into the workflow
+
+Hermes owns the Telegram connection. The toolkit adds three pieces:
+
+1. The `3d-printer-slicing-automation` skill teaches Hermes to relay toolkit events and commands.
+2. The `u1-form` and `snapmaker_u1` plugins render native form buttons and attach previews, reviews, and photos.
+3. The YES/CANCEL gateway hooks redeem a bound approval or cancel a pending start without asking the model to control the printer.
+
+The core toolkit remains usable from the CLI without Telegram or Hermes.
+
+## Install the Hermes integration
+
+From a complete toolkit checkout on Linux, WSL, or inside the Hermes container:
+
+```bash
+hermes skills install bbolinger/snapmaker-u1-toolkit/skills/3d-printer-slicing-automation
+bash deploy_to_runtime.sh
+python3 adapters/hermes/install.py
+bash tools/install_hermes_u1_hooks.sh
+```
+
+The installer adds both required plugins. It should finish with a `[6/6]` verification line that reports the expected hooks.
+
+Restart the gateway from a separate terminal outside the active Hermes chat:
+
+```bash
+hermes gateway restart
+bash tools/install_hermes_u1_hooks.sh --verify
+```
+
+The gateway cannot safely restart itself from inside its own process. If you run the restart from the active Hermes conversation, the command can end before the new hooks load.
+
+## Bind approvals to your Telegram account
+
+Keep the printing workflow in a private direct message. Hermes should already restrict the Telegram gateway with `TELEGRAM_ALLOWED_USERS`.
+
+If exactly one Telegram user is allowed, the toolkit resolves the operator automatically. If multiple users are allowed, add this to the runtime `.env`:
+
+```bash
+U1_OPERATOR_BINDING=telegram:<your-numeric-telegram-user-id>
+```
+
+Restart the gateway after changing the binding.
+
+## Verify the setup
+
+Check these signals before sending a real print:
+
+- `bash tools/install_hermes_u1_hooks.sh --verify` succeeds.
+- Hermes loads both `u1-form` and `snapmaker_u1` plugins.
+- A model attachment triggers the Snapmaker U1 workflow.
+- The decision form renders as Telegram buttons, or falls back to the documented typed form.
+- Plate previews and `review.md` arrive as attachments.
+- The bed-clear question includes a fresh U1 camera photo.
+- Replying `NO` keeps the G-code uploaded without starting the printer.
+
+Use `NO` for the first live integration test. It exercises attachment routing, slicing, preview generation, Moonraker upload, and the approval path without starting the printer.
+
+## What happens when you reply YES
+
+Hermes does not receive a print-start command. The gateway consumes the YES, checks the bound operator and current request, and invokes the toolkit's approval gate. A countdown message appears only if those checks succeed.
+
+If no countdown appears, the print was not started. Run the hook verification and inspect the reported refusal; do not retry by calling Moonraker directly.
+
+## Native buttons versus the text fallback
+
+The first-party Hermes plugin renders parts, orientation, tool, material, profile, supports, advanced settings, and action as native Telegram controls. On a host without the form plugin, the workflow can emit a typed one-line fallback instead. Both paths are parsed and validated by toolkit code rather than interpreted by the model.
+
+Developers integrating a different bot can use the SDK-free reference renderer in [`adapters/telegram/u1_form_telegram.py`](../adapters/telegram/u1_form_telegram.py) and the [adapter contract](../adapters/README.md).
+
+## Troubleshooting
+
+- **No form buttons:** rerun `python3 adapters/hermes/install.py`, then restart the gateway externally.
+- **Attachments do not appear:** verify the `snapmaker_u1` hook plugin loaded after the restart.
+- **YES has no effect:** rerun `bash tools/install_hermes_u1_hooks.sh --verify`.
+- **Wrong user is refused:** check `TELEGRAM_ALLOWED_USERS` and `U1_OPERATOR_BINDING`.
+- **CANCEL is not acknowledged:** the safe fallback can only cancel; follow the recovery steps in the main Hermes integration documentation.
+
+See [TROUBLESHOOTING.md](../TROUBLESHOOTING.md) and the full [Hermes integration](../README.md#hermes-integration) for deeper diagnostics.
+
+---
+
+[Print from your phone](PRINT-FROM-PHONE.md) · [Install](../README.md#install) · [Safety model](SAFETY.md)
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,10 @@
+title: Snapmaker U1 Toolkit
+description: Print to your Snapmaker U1 from your phone through Telegram, headless OrcaSlicer, Moonraker, camera verification, and a human-approved start gate.
+url: https://bbolinger.github.io
+baseurl: /snapmaker-u1-toolkit
+repository: bbolinger/snapmaker-u1-toolkit
+theme: jekyll-theme-cayman
+show_downloads: true
+plugins:
+  - jekyll-seo-tag
+
diff --git a/docs/images/hero-hermes-snapmaker.png b/docs/images/hero-hermes-snapmaker.png
diff --git a/docs/images/snapmaker-u1-print-from-phone-telegram-flow.png b/docs/images/snapmaker-u1-print-from-phone-telegram-flow.png
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,76 @@
+---
+layout: default
+title: Print to Your Snapmaker U1 From Your Phone
+description: Send STL and 3MF files through Telegram, slice locally with OrcaSlicer, review the plate, verify your Snapmaker U1 by camera, and approve the print from your phone.
+image: /snapmaker-u1-toolkit/images/snapmaker-u1-print-from-phone-telegram-flow.png
+---
+
+# Print to Your Snapmaker U1 From Your Phone
+
+Snapmaker U1 Toolkit is an open-source remote printing workflow for the Snapmaker U1. Send an STL, 3MF, or multi-part ZIP through Telegram; slice it locally with OrcaSlicer; review the plate, toolpath, and settings; verify the printer with a fresh camera photo; then approve the exact job from your phone.
+
+![Snapmaker U1 remote printing workflow from a phone through Telegram, OrcaSlicer, camera verification, and human-approved print start](images/snapmaker-u1-print-from-phone-telegram-flow.png)
+
+[View the project on GitHub](https://github.com/bbolinger/snapmaker-u1-toolkit) · [Print-from-phone guide](PRINT-FROM-PHONE.html) · [Installation](https://github.com/bbolinger/snapmaker-u1-toolkit#install)
+
+## From model to monitored print
+
+- **Send from your phone:** attach one model or a ZIP of parts in Telegram.
+- **Slice locally:** run upstream OrcaSlicer headlessly on your own Linux, WSL, or Windows host.
+- **Review the real job:** inspect orientation, plate layout, G-code-derived previews, and the important print settings.
+- **Verify the U1:** check the loaded toolhead and filament, then inspect a fresh onboard-camera image of the bed.
+- **Approve deliberately:** a single-use approval bound to the job and operator starts the countdown.
+- **Monitor remotely:** receive first-layer, last-layer, pause/resume, and completion photos.
+
+## Designed for the Snapmaker U1
+
+The toolkit understands the U1's toolchanger, Snapmaker profiles, OrcaSlicer CLI behavior, Moonraker storage, camera, thumbnails, and multi-plate workflows. It can rewrite the selected tool, validate G-code bounds, detect profile drift, and refuse a start when printer state no longer matches the reviewed plan.
+
+## Remote printing without unrestricted AI control
+
+Hermes and a local LLM are optional chat layers. They can help explain choices and relay workflow events, but they do not receive a general-purpose print-start command. Deterministic toolkit code owns printer checks, upload-only behavior, the fresh-camera approval prompt, the single-use start gate, and the cancel window.
+
+[Read the safety model](SAFETY.html)
+
+## Choose your setup
+
+### Print from your phone with Telegram
+
+Use Hermes as the Telegram bridge and keep model processing on local hardware.
+
+[Follow the phone-printing guide](PRINT-FROM-PHONE.html) · [Configure Telegram](TELEGRAM-SETUP.html)
+
+### Run headless OrcaSlicer without AI
+
+Use the command-line tools directly for scripted slicing, previews, G-code validation, Moonraker uploads, and monitoring.
+
+[Set up headless OrcaSlicer for the Snapmaker U1](HEADLESS.html)
+
+### Build another frontend
+
+Consume the toolkit's JSON event stream or reuse the platform-neutral form contract to integrate a different chat bot, web interface, or automation system.
+
+[Read the event contract](events.html) · [View the adapter examples](https://github.com/bbolinger/snapmaker-u1-toolkit/tree/main/adapters)
+
+## Quick answers
+
+### Can I print to a Snapmaker U1 from my phone?
+
+Yes. With the Hermes Telegram integration installed, you can submit the model, choose settings, review artifacts, inspect the bed photo, and approve the prepared job from a private Telegram chat.
+
+### Does it require cloud slicing?
+
+No. OrcaSlicer and the optional local LLM run on your own host. The printer is addressed through its LAN Moonraker interface.
+
+### Can I use the toolkit without Hermes or an AI model?
+
+Yes. The slicing, preview, validation, upload, camera, status, monitoring, and audit tools are ordinary Python CLIs.
+
+### Will it start a print automatically?
+
+No. Toolkit-started prints require an explicit human approval tied to a fresh bed photo and the current prepared G-code. If the plan, operator, or printer state does not match, the gate refuses.
+
+---
+
+[GitHub repository](https://github.com/bbolinger/snapmaker-u1-toolkit) · [Troubleshooting](https://github.com/bbolinger/snapmaker-u1-toolkit/blob/main/TROUBLESHOOTING.md) · [Releases](https://github.com/bbolinger/snapmaker-u1-toolkit/releases)
+