Xento · Xento · Nov 30, 2025 · Nov 30, 2025
diff --git a/README.md b/README.md
diff --git a/docs/auto-spend.md b/docs/auto-spend.md
@@ -0,0 +1,17 @@
+# AUTO SPEND notes
+
+`AUTO_SPEND` enables consumption tracking from printer telemetry so matched spools display precise remaining weights.
+
+## How it works
+- When `AUTO_SPEND=True`, matched spools show remaining grams based on printer feedback instead of percentage estimates.
+- Unmatched trays continue to show percentage values until a spool is assigned.
+- The feature relies on a healthy connection to your Bambu printer and SpoolMan API.
+
+## Enabling
+1. Set `AUTO_SPEND=True` in `config.env`.
+2. Restart the application or redeploy the container.
+3. Verify remaining weights update during prints; fall back to percentage views by setting `AUTO_SPEND=False`.
+
+## Tips
+- Pair AUTO SPEND with `SPOOL_SORTING` to keep the best candidates at the top of tray searches.
+- If prints are running in read-only environments, disable AUTO SPEND to avoid stale or incomplete telemetry.
diff --git a/docs/demo-and-screenshots.md b/docs/demo-and-screenshots.md
@@ -0,0 +1,26 @@
+# Seeded demo & screenshot generation
+
+Use the built-in seeded dataset to preview OpenSpoolMan or to generate consistent screenshots.
+
+## Quick demo with seeded data
+1. Ensure dependencies for UI tests are installed: `pip install -r requirements-screenshots.txt`.
+2. Start the app in seeded mode:
+   ```bash
+   OPENSPOOLMAN_TEST_DATA=1 python app.py
+   ```
+3. Open the UI and explore without connecting to live printers or SpoolMan.
+
+## Generate screenshots
+1. Install Playwright browsers if you have not already:
+   ```bash
+   playwright install
+   ```
+2. Run the capture script (seeded mode by default):
+   ```bash
+   python scripts/generate_screenshots.py --mode seed --port 5001
+   ```
+3. Outputs are written to the directories defined in `scripts/screenshot_config.json`. Use `--output-dir` to override.
+4. To capture against a live server, point `--base-url` to your deployment and pass `--mode live`. Add `--allow-live-actions` if you intentionally want state changes during capture.
+
+## Using snapshots
+The script can load a saved dataset with `--snapshot data/live_snapshot.json` and attach a print history database via `--print-history-db` for richer history screenshots.
diff --git a/docs/deployment.md b/docs/deployment.md
@@ -0,0 +1,30 @@
+# Deployment options
+
+OpenSpoolMan can run locally, via Docker Compose, or on Kubernetes with the provided Helm chart.
+
+## Docker Compose
+1. Ensure `config.env` is populated (see the setup guide).
+2. Start the stack:
+   ```bash
+   docker compose -f compose.yaml up -d
+   ```
+3. Access the UI on `http://localhost:8000` (or the host/port you mapped).
+
+## Docker images
+- The repository builds multi-architecture images; you can also build locally with `docker build -t openspoolman:local .`.
+- Set `OPENSPOOLMAN_BASE_URL` in `config.env` to match the public URL where the container will be served.
+
+## Helm (Kubernetes)
+- A starter chart is available under `helm/openspoolman`.
+- Populate values for ingress, environment variables, and image registry as needed, then install:
+  ```bash
+  helm upgrade --install openspoolman helm/openspoolman
+  ```
+
+## Running from source
+For development, install dependencies and start Flask directly:
+```bash
+pip install -r requirements.txt
+python app.py
+```
+Use `.env` or `config.env` to supply the same environment variables used in container deployments.
diff --git a/docs/features.md b/docs/features.md
@@ -0,0 +1,40 @@
+# Feature tour & screenshots
+
+Explore the core OpenSpoolMan experience across desktop and mobile.
+
+## Desktop views
+- **Home dashboard** with AMS status, spool assignments, and quick actions.
+  ![Desktop home view](img/desktop_home.PNG)
+- **Tray management** for filling or assigning AMS slots.
+  ![Fill tray modal](img/desktop_fill_tray.PNG)
+- **Print history** with spool usage context.
+  ![Desktop print history](img/desktop_print_history.PNG)
+
+## Mobile views
+- **Mobile dashboard** tuned for quick AMS control.
+  ![Mobile home](img/mobile_home.PNG)
+- **Assign trays via NFC** and confirm writes directly from your phone.
+  ![Mobile NFC assignment](img/mobile_assign_nfc.jpeg)
+  ![NFC write success](img/nfc_write_success.jpeg)
+- **Tray changes on the go** with tap-friendly controls.
+  ![Mobile change spool](img/mobile_change_spool.PNG)
+
+## Spool insights
+- **Spool details** at a glance, including vendor, material, and remaining weight.
+  ![Desktop spool details](img/desktop_spool_info.jpeg)
+  ![Mobile spool details](img/mobile_spool_info.jpeg)
+- **Bambu tracking overlays** showing estimated usage from printer telemetry.
+  ![Bambu tracking](img/bambu_tracking.jpg)
+- **Print estimates** from slicer data alongside AMS context.
+  ![Slicer estimate](img/slicer_estimate.jpg)
+
+## Workflow helpers
+- **Resolve missing info** prompts to keep data clean and enforce NFC-assisted flows.
+  ![Resolve issues](img/resolve_issues.jpeg)
+- **Tray picking shortcuts** that surface the best slot based on spool attributes.
+  ![Pick tray](img/pick_tray.jpeg)
+- **Open SpoolMan links** from within the UI for deeper inventory edits.
+  ![Open in SpoolMan](img/open_link.jpeg)
+
+## Post-print assignment fallback
+If automatic detection misses a spool after a print, OpenSpoolMan can prompt for a manual assignment so history and consumption stay accurate.
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,23 @@
+# OpenSpoolMan documentation
+
+Manage and monitor Bambu Lab printer spools through SpoolMan with NFC-driven workflows, automatic usage tracking, and a responsive UI for desktop and mobile.
+
+## Quick navigation
+- [Feature tour & screenshots](features.html)
+- [Setup guide](setup.html)
+- [Deployment options](deployment.html)
+- [Seeded demo & screenshot generation](demo-and-screenshots.html)
+- [AUTO SPEND notes](auto-spend.html)
+
+## Release 0.1.9 highlights
+- Custom spool sorting for tray views and searches via `SPOOL_SORTING`.
+- Post-print spool assignment fallback when automatic detection is unavailable.
+- Works with Bambu Studio 2.x while preserving NFC-assisted workflows.
+
+## What you get
+- NFC-driven spool identification, assignment, and loading from mobile or desktop.
+- Automatic usage tracking for tagged and untagged Bambu filaments without cloud access.
+- Views optimized for AMS tray selection, spool details, and print history.
+
+## Where to find images
+All screenshots are stored in `docs/img/` and referenced throughout the pages linked above.
diff --git a/docs/pages-maintenance.md b/docs/pages-maintenance.md
@@ -0,0 +1,23 @@
+# GitHub Pages maintenance
+
+The documentation is published from the `docs/` folder via GitHub Pages. No submodule is required.
+
+## Configure Pages
+1. Open the repository Settings → Pages.
+2. Set **Source** to "Deploy from a branch" and choose the default branch with `/docs` as the folder.
+3. Save to enable the site at `https://<owner>.github.io/openspoolman/`.
+
+## Updating docs
+- Edit Markdown in `docs/` (e.g., `features.md`, `setup.md`, `deployment.md`).
+- Add screenshots to `docs/img/` and reference them with relative links.
+- Submit a pull request; the site will update automatically after merge.
+
+## Preview locally
+You can preview the static Markdown with any web server:
+```bash
+python -m http.server --directory docs 4000
+```
+For full Jekyll rendering, use `bundle exec jekyll serve --source docs --livereload` if you have Ruby tooling installed.
+
+## Mirroring to a dedicated branch
+If you prefer a separate `gh-pages` branch, copy the `docs/` folder into that branch via automation or a manual sync. The content remains the same; only the Pages source changes.
diff --git a/docs/setup.md b/docs/setup.md
@@ -0,0 +1,25 @@
+# Setup guide
+
+Follow these steps to connect OpenSpoolMan to your Bambu Lab printer and SpoolMan instance.
+
+## Prerequisites
+- A reachable SpoolMan server (the app expects `/api/v1` endpoints).
+- Printer details: serial number, access code, local IP, and a friendly printer name.
+- Bambu Studio 2.x is supported; NFC-assisted flows continue to work with that release.
+
+## Configure environment
+1. Copy `config.env.template` to `config.env` in the repository root.
+2. Fill in the printer and SpoolMan values:
+   - `OPENSPOOLMAN_BASE_URL` – public base URL where this app will be served.
+   - `PRINTER_ID`, `PRINTER_ACCESS_CODE`, `PRINTER_IP`, `PRINTER_NAME` – printer credentials and IP.
+   - `SPOOLMAN_BASE_URL` – base URL for your SpoolMan instance.
+3. Optional tuning:
+   - `AUTO_SPEND` – set `True` to display precise remaining weights for matched spools using printer telemetry.
+   - `SPOOL_SORTING` – customize spool sort order for tray selection and searches (default: `filament.material:asc,filament.vendor.name:asc,filament.name:asc`).
+   - `TZ` – set your server timezone for correct timestamps.
+
+## Initialize printer metadata
+Run `python scripts/init_bambulab.py` once to validate the printer connection and populate credentials.
+
+## Health check
+Start the app locally (see deployment options) and hit `/health` to confirm connectivity to both SpoolMan and the printer before enabling NFC or AUTO SPEND in production.