From 7b4dc6ce8cdab28b007b304198450c98b4589f47 Mon Sep 17 00:00:00 2001
From: Adriano <adriano.dalpastro@laboticsitalia.com>
Date: Wed, 3 Jun 2026 14:43:07 +0200
Subject: [PATCH] docs: build.sh deploy workflow + badge versione (CLAUDE.md,
 README)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md |  3 +++
 README.md | 12 ++++++++++++
 2 files changed, 15 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 28e678b..5270821 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -9,6 +9,8 @@ Build & run (Docker):
 docker compose up -d presa-mano        # serves GUI + API on http://localhost:8890
 ```
 
+**Deploy changes — use `./build.sh`.** `src/` and `web/` are baked into the image (only `config.yaml` + `data/` are bind-mounted), so **code edits are invisible until the image is rebuilt**. `./build.sh` auto-bumps `VERSION` (patch by default; `./build.sh minor|major` for the others), injects version + build time as build-args, rebuilds, and restarts the container. The running version is shown as a badge in the GUI header (and at `GET /api/version`) so a stale deployment is visible at a glance. The `VERSION` bump is left uncommitted — commit it with your changes.
+
 Local dev (uses `uv`, same as the Dockerfile):
 ```bash
 uv sync                                # install deps from pyproject.toml
@@ -17,6 +19,7 @@ uv run uvicorn presa_mano.main:app --host 0.0.0.0 --port 8890 --reload
 
 Useful endpoints (all under `http://localhost:8890`):
 - `GET /apidocs` — Swagger UI; `GET /redoc` — ReDoc.
+- `GET /health` — liveness; `GET /api/version` — `{version, build_time}` baked at build by `build.sh` (falls back to the `VERSION` file + `(local)` under `uv run`).
 - `GET/PUT /api/config` — read/patch runtime config (deep-merged into `config.yaml` and persisted).
 - Calibration: `POST /api/calibration/sample`, `GET/DELETE /api/calibration/samples`, `POST /api/calibration/solve`, `GET /api/calibration/result`, `POST /api/calibration/preview`.
 - Perception: `POST /api/perception/detect`, `POST /api/perception/object_points`, `GET /api/perception/measure`.
diff --git a/README.md b/README.md
index f7525b6..cb87199 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,18 @@ docker compose up -d presa-mano
 # Apri http://localhost:8890
 ```
 
+## Build & deploy delle modifiche
+
+`src/` e `web/` sono inclusi (baked) nell'immagine: le modifiche al codice **non si vedono finché non ricostruisci l'immagine**. Usa lo script:
+
+```bash
+./build.sh            # patch++ (1.0.1 -> 1.0.2), rebuild + restart
+./build.sh minor      # 1.0.2 -> 1.1.0
+./build.sh major      # 1.1.0 -> 2.0.0
+```
+
+Lo script bumpa il file `VERSION`, inietta versione + ora di build nell'immagine e riavvia il container. La versione attiva è mostrata nel **badge in alto a destra** nella GUI (tooltip con l'ora di build) ed è esposta da `GET /api/version` — così capisci subito se il container gira l'ultima build. Il bump di `VERSION` resta non committato: committalo con le tue modifiche.
+
 ## GUI
 
 Tab principali: