Add download preflight and stuck-pull guidance to local-ai-use

skills/local-ai-use/SKILL.md

@@ -250,6 +250,7 @@ machine.
 | `status` gives an "invalid choice" / usage error | An old, incompatible `lemonade` (pre-v10.1.0, from any install channel) is shadowing the modern CLI | Uninstall it the way it was installed (see the Step 1a table: `winget uninstall -e --id AMD.LemonadeServer` / `sudo apt remove lemonade-server` / `pip uninstall lemonade-sdk`), then re-run the setup script or install Lemonade from the docs link. |
 | `Server is not running` | `lemond` service stopped | Start it via the OS service manager — `sudo systemctl start lemond` / `systemctl --user start lemond` (Linux), `launchctl load /Library/LaunchDaemons/com.lemonade.server.plist` (macOS), or the tray app / `Start-Service lemond` (Windows). There is no `lemonade serve`. |
 | `POST /v1/images/generations` returns 404 model not found | Image model not downloaded | `lemonade pull SD-Turbo` and retry. |
+| `lemonade pull` keeps printing `Progress: NN%` but never finishes | Download target is a bad path (out of space, no write permission, quota, read-only mount). The write error may surface only in the server log while the console keeps showing progress | Check the target and free space first: `GET /api/v1/system-info` reports `models_dir` and `model_storage.free_bytes`. If a pull stalls, read the recent lines of the server log (typically `lemonade-server.log` in the OS temp dir) for the real error (e.g. a download/write failure like `CURL code 23`, or an out-of-space message), then point the download at a writable disk with room. |
 | Image generation is slow on CPU (~4–5 min) | sd-cpp on CPU backend | Install the GPU backend on supported AMD hardware: `lemonade backends install sd-cpp:rocm`. |
 | `POST /v1/audio/transcriptions` returns 400 unsupported format | Input is not 16 kHz mono WAV | Re-encode with `ffmpeg -i in.* -ar 16000 -ac 1 out.wav`. |
 | `POST /v1/audio/speech` returns 404 | TTS model not downloaded | `lemonade pull kokoro-v1`. |

skills/local-ai-use/templates/local-ai-rule.md

@@ -74,7 +74,24 @@ curl -sX POST {{LEMONADE_BASE_URL}}/audio/transcriptions \
 1. Try the local endpoint exactly once.
 2. If the server is unreachable, run `lemonade status` and surface the
    result to the user before doing anything else.
-3. If the model is missing, run `lemonade pull <model>` and retry once.
+3. If the model is missing, run `lemonade pull <model>` to pull it,
+   but preflight the download first, because a bad target path fails slowly and silently:
+   1. Check where the server will write and whether there is room:
+      `GET {{LEMONADE_BASE_URL}}/system-info`. The response reports `models_dir`
+      (the download location) and a `model_storage` block with `free_bytes` /
+      `total_bytes`. If free space is short of the model size, tell the user the
+      exact path and free/required space and stop — do not start the pull.
+   2. Otherwise run `lemonade pull <model>` once and watch for completion.
+   3. A healthy pull prints rising `Progress: NN%` and ends with a success
+      line. A **broken** pull is easy to mistake for a slow one, because the
+      write/permission/quota failure may surface only in the server log while
+      the console keeps printing `Progress: NN%`. If the pull stalls or does not
+      finish in a reasonable time, treat it as failed: find the server log
+      (typically named `lemonade-server.log` in the OS temp directory; if unsure
+      of the path, check the Lemonade docs) and read its most
+      recent lines for the underlying error — for example a download/write error
+      (such as `CURL code 23`) or an out-of-space message. Surface that line
+      to the user rather than waiting through silent retries.
 4. Only after that, ask the user before falling back to a cloud provider.
    Never silently fall back; the whole point of this rule is predictable
    cost.