Gaggiuino Local

Gaggiuino analytical skill for machine control, shot expression analysis, and high-performance visualization. It interprets shot data through profile intent and generates unified static/animated graphs or synchronized video overlays.

# Gaggiuino Local

Gaggiuino Local is a machine-connected skill for espresso machines running the Gaggiuino mod. 
It enables live status monitoring, in-depth shot analysis based on profile intent vs. actual expression, profile management, and settings configuration. Additionally, it provides a high-performance rendering engine for generating static graphs, animated trajectory videos, and synchronized overlays for extraction footage.

Its core question is not simply **“is this cup good?”**
It first asks whether the shot became what its profile was trying to make it become.
In other words, it asks:

> **Did this shot become the kind of coffee it was trying to be?**

In Chinese:

> **这杯咖啡有没成为它本来想成为的样子？**

Only after that should it move into troubleshooting or dial-in guidance.

All machine interaction goes through `scripts/gaggiuino.sh`.

---


## What this skill is for

Use this skill when the task involves one or more of these:
- checking current machine state, readiness, temperature, water level, or active profile / 当前状态
- analyzing the latest shot / 萃取 or a historical one (**preferred; strongest evidence**)
- generating static graphs, animated trajectory videos, or synchronized overlays / 萃取可视化与视频叠加
- dialing in or troubleshooting espresso taste and shot behavior
- recommending a profile / 曲线 or profile family
- listing or switching profiles / 曲线 on the real machine
- helping identify what family a named profile / 曲线 belongs to
- reading or updating Gaggiuino settings
- interpreting graph screenshots or machine screen photos (**fallback; lower-confidence evidence**)


## What this skill is not for

- It is **not** a generic coffee essay generator.
- It is **not** a profile-name cookbook detached from real machine behavior.
- It should not answer live-status questions from memory or guesswork when the API path is available.
- It should not assume every coffee question needs machine control if the user is only asking for general dial-in reasoning.

## Direct machine asks

### Immediate command routing
- machine status / readiness / temperature / online / current profile / 当前状态 / 准备好了没 / 当前温度 / 在线吗 / 当前曲线 / 现在是什么曲线  
  → `scripts/gaggiuino.sh status`
- available profiles / what profiles are installed / 有哪些曲线 / 可用曲线 / 装了哪些曲线  
  → `scripts/gaggiuino.sh profiles`
- switch to a named profile / use profile XXX / 切到 XXX 曲线 / 换成 XXX 曲线 / 用 XXX 曲线  
  → `scripts/gaggiuino.sh profiles` → resolve id → `scripts/gaggiuino.sh select-profile <id>`
- latest shot / latest extraction / last shot / latest extraction / 最新一杯 / 最新萃取 / 上一杯 / 最近一杯  
  → `scripts/gaggiuino.sh latest-shot`
- historical shot by id / extraction by id / 按 id 查历史萃取 / 查某一杯历史记录  
  → `scripts/gaggiuino.sh shot <id>`
- settings read/change / 读设置 / 改设置 / 查看设置 / 修改设置  
  → `scripts/gaggiuino.sh get-settings <category>` first, then `scripts/gaggiuino.sh update-settings <category> <json>`
- shot graph (static/dynamic) / overlay video / 渲染萃取图 / 合成视频  
  → `scripts/render_shot_graph.py` & `scripts/render_shot_video_overlay.py`

### Connection default and fallback
- default base URL is `http://gaggiuino.local`
- `gaggiuino.local` is the machine's **mDNS hostname**
- on first use, if no remembered fixed LAN IP exists, the script tries `gaggiuino.local` first
- the remembered fixed LAN IP is stored at `~/.openclaw/workspace/memory/gaggiuino-base-url.json`
- if `gaggiuino.local` fails, guide the user to check the machine's network connection and find its real LAN IP in **router settings**
- for long-term stability, suggest setting a **DHCP static lease on the router**
- when the user confirms a stable LAN IP they want to keep using, save it with `scripts/gaggiuino.sh set-base-url <url-or-host>`
- once a remembered fixed LAN IP exists, the script tries that address first and falls back to `gaggiuino.local` on connection-layer failure
- if both the remembered address and `gaggiuino.local` fail, treat the remembered IP as possibly stale and guide the user to re-check the network or update the saved address
- use `scripts/gaggiuino.sh get-base-url` to inspect the remembered address and `scripts/gaggiuino.sh clear-base-url` to remove it
- these addresses are intended for trusted local/LAN endpoints; do **not** point them at untrusted remote servers
- prefer retrying with a concrete LAN IP over guessing

---

## Terminology normalization

Use these as output-normalization rules, especially when replying in Chinese coffee context.
They are meant to prevent literal but unnatural translations.

### General rule
- Match the user's language.
- In Chinese coffee context, prefer established coffee terms over literal translation.
- Treat these as normalization hints for analysis and replies, unless the user clearly means something else.

### Core term mappings
- **profile** → **曲线**
- **shot** → **萃取**
- **phase** → **阶段**
- **Bloom** → **焖蒸**
- **phase transition** → **阶段切换** / **阶段过渡**
- **yield** → **出液**
- **channeling** → **通道效应**
- **puck** → **粉饼**
  - Do **not** use the literal sports translation **冰球**.
- **control mode** → **控制模式**
- **family** → **方案**
- **flow phase** → **流速先决阶段**
- **pressure phase** → **压力先决阶段**

### Local alias / machine-specific interpretation
- In this local context, **超萃** usually refers to the local `HyperEx` / `HyperEx 2.0` profiles.
- When users say **超萃** here, default to checking whether they mean the local HyperEx lineage first.

### Phase Replay Nomenclature (Target vs Limit)
Use the terminology rules above, but for phase-transition replays and control-mode summaries apply the following stricter formatting rules.

When writing phase transition replays or summarizing control modes, **strictly avoid** exposing raw machine fields or machine-style shorthand such as `type: "FLOW"`, `target.end: 3`, `restriction: 4`, `stopConditions.pressureAbove: 4`, or compressed tuples built from them. Translate them into human-readable descriptions centered on **Targets**, **Limits**, and exit conditions.

**Critically: Match the output language strictly to the user's query language. Do not mix English and Chinese.**

**For `type: flow`:**
- The mode is the **flow phase** (EN) / **流速先决阶段** (CN).
- The **flow target** is the target (EN) / **目标流速** (CN).
- The **pressure limit** is the limit (EN) / **压力限制** (CN).
- *Format Example (EN):* "Flow phase, flow target 12 ml/s, pressure limit 6 bar."
- *Format Example (CN):* "流速先决阶段，目标流速 12 ml/s，压力限制 6 bar。"

**For `type: pressure`:**
- The mode is the **pressure phase** (EN) / **压力先决阶段** (CN).
- The **pressure target** is the target (EN) / **目标压力** (CN).
- The **flow limit** is the limit (EN) / **流速限制** (CN).
- *Format Example (EN):* "Pressure phase, pressure target 6 bar, flow limit 2 ml/s."
- *Format Example (CN):* "压力先决阶段，目标压力 6 bar，流速限制 2 ml/s。"

---

## Core operating rule

Always decide first whether the task is mainly about:
1. **real machine state / real shot data**
2. **general dial-in reasoning**
3. **graph interpretation**
4. **local profile classification**

Then read only the references needed for that path.

For real machine tasks, default to:
1. fetch the actual state / shot / settings payload
2. reconstruct what the named profile actually tried to do
3. interpret the machine-side semantics correctly
4. use family as an interpretation layer, not the first execution verdict
5. only then recommend the next move

---

## Primary routing logic

### Analysis Principle: Family vs. Profile
Use family as an interpretation layer, not as the first execution verdict.
In real-shot analysis, judge the intended **named profile** first, then use family to explain broader intent, likely expectations, and common misreads.

A shot may fit the broader family yet still fail to express the named profile.
A shot may also express the named profile coherently and still be worth changing for taste reasons.

For full machine semantics, read:
- [references/analysis-protocol.md](references/analysis-protocol.md)

For family intent, graph interpretation, and broader next