feat: Enhance FaceAI functionality with storage management and update deployment instructions

.github/instructions/regalamiunsorriso-faceai-pve02docker.instructions.md

@@ -0,0 +1,162 @@
+---
+description: 'Use when: debugging, inspecting, or updating the FaceAI Docker deployment on root@pve02docker.maddo.science, especially for faceai/** and stacks/faceai.yml changes.'
+applyTo: 'faceai/**, stacks/faceai.yml'
+---
+
+# Regalami Un Sorriso FaceAI Docker Host
+
+Instructions in this file are specific to the FaceAI Docker deployment reachable as `root@pve02docker.maddo.science` through the preconfigured SSH tunnel and stored credentials.
+
+## Host Access
+
+- SSH target: `root@pve02docker.maddo.science`
+- Plain `ssh root@pve02docker.maddo.science` works in the current environment.
+- The remote shell is `/bin/bash`, not `tcsh`.
+- Do not add manual tunnel, key, or credential flags unless the current workflow is revalidated.
+
+## Preferred SSH Workflow
+
+For routine inspection, use plain SSH:
+
+```powershell
+ssh root@pve02docker.maddo.science
+```
+
+From PowerShell on Windows, prefer invoking the SSH binary directly instead of wrapping it in `cmd /c`:
+
+```powershell
+& 'C:\Windows\System32\OpenSSH\ssh.exe' 'root@pve02docker.maddo.science'
+```
+
+When you must run a single remote command non-interactively, pass the whole remote command as one SSH argument.
+
+## Shell Behavior From PowerShell
+
+- Prefer one remote command per SSH invocation when doing reconnaissance. Complex commands with pipes, grouped expressions, or escaped parentheses are more likely to break under PowerShell-to-SSH quoting.
+- On Windows PowerShell, avoid `cmd /c "ssh ..."` wrappers for anything nontrivial. Nested quoting can collapse before SSH runs and spill later tokens into the local PowerShell session.
+- Prefer the PowerShell call operator form `& 'C:\Windows\System32\OpenSSH\ssh.exe' ...` and pass the remote command as a single argument when you must stay non-interactive.
+- If PowerShell shows the continuation prompt `? >`, the command was malformed locally before SSH executed it. Cancel it and rerun a simpler command instead of trying to answer the prompt.
+- When running remote commands from PowerShell, quoting can break if the command contains both nested quotes and file paths with spaces.
+- For read-only verification commands from PowerShell, prefer `ssh ... --% <remote command>` so the remote command is passed verbatim.
+- If repeated SSH commands start cancelling or interleaving poorly in the same terminal, rerun them sequentially instead of in parallel.
+- The remote shell is normal `bash`, so standard POSIX shell constructs usually work once they reach the host intact.
+
+## Docker Runtime Facts
+
+- The FaceAI deployment is currently managed by Docker Compose, not Docker Swarm.
+- Compose project: `faceai`
+- Compose working directory: `/data/compose/4`
+- Compose file: `/data/compose/4/docker-compose.yml`
+- Main containers:
+  - `regalami-faceai`
+  - `regalami-faceai-processor`
+  - `regalami-faceai-redis`
+
+## Container Roles
+
+- `regalami-faceai`: public HTTP application
+- `regalami-faceai-processor`: background queue worker that runs the matcher jobs
+- `regalami-faceai-redis`: Redis queue and state store
+
+## Useful Runtime Paths
+
+- Runtime data: `/mnt/storage/data/faceai/runtime`
+- Persistent logs: `/mnt/storage/data/faceai/logs`
+- Read-only PKL dataset: `/mnt/nas12/nas2/RUS`
+- In-container runtime root: `/data/runtime`
+- In-container log root: `/data/logs`
+- In-container PKL root: `/data/pkl`
+
+## Logs And Health Checks
+
+Prefer Docker logs first for quick inspection:
+
+```bash
+docker logs --tail 200 regalami-faceai
+docker logs --tail 200 regalami-faceai-processor
+docker logs --tail 200 regalami-faceai-redis
+```
+
+Persistent host logs are also available directly:
+
+- `/mnt/storage/data/faceai/logs/backend.log`
+- `/mnt/storage/data/faceai/logs/processor.log`
+- `/mnt/storage/data/faceai/logs/searches/<searchId>/worker.log`
+- `/mnt/storage/data/faceai/logs/searches/<searchId>/matcher.log`
+
+Operational notes:
+
+- `regalami-faceai` has shown `ECONNREFUSED` errors when Redis was not yet reachable, then recovered once Redis became healthy.
+- `docker ps` health output is meaningful here because the public app has an HTTP healthcheck and Redis has a readiness check.
+- If the public app is running but marked `unhealthy`, inspect both `docker logs regalami-faceai` and `/mnt/storage/data/faceai/logs/backend.log` before changing anything.
+
+## Read-Only Debugging Commands
+
+Use these patterns before considering any state-changing action:
+
+```bash
+docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}'
+docker compose -f /data/compose/4/docker-compose.yml ps
+docker inspect regalami-faceai
+docker inspect regalami-faceai-processor
+docker inspect regalami-faceai-redis
+```
+
+When you need recent logs without attaching to a live stream:
+
+```bash
+docker logs --tail 200 regalami-faceai
+docker logs --tail 200 regalami-faceai-processor
+docker logs --tail 200 regalami-faceai-redis
+```
+
+When you need file-backed diagnostics:
+
+```bash
+tail -n 200 /mnt/storage/data/faceai/logs/backend.log
+tail -n 200 /mnt/storage/data/faceai/logs/processor.log
+```
+
+## Updates And Container Management
+
+If the user explicitly approves a rollout or image refresh, the Compose-managed update path is from `/data/compose/4`:
+
+```bash
+cd /data/compose/4
+docker compose pull
+docker compose up -d
+```
+
+After any approved update, verify with:
+
+- `docker compose -f /data/compose/4/docker-compose.yml ps`
+- `docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.RunningFor}}'`
+- `docker logs --tail 200 regalami-faceai`
+- `docker logs --tail 200 regalami-faceai-processor`
+
+## Consent Rules
+
+Read-only inspection may proceed without additional confirmation.
+
+Any destructive or service-affecting action requires the user's express consent, and that consent must be collected through the `vscode_askQuestions` tool before running the command.
+
+Treat all of the following as consent-gated actions:
+
+- `docker compose pull`
+- `docker compose up -d`
+- `docker compose down`
+- `docker restart`, `docker stop`, `docker kill`, `docker rm`
+- `docker exec` commands that modify files, data, or runtime state
+- deleting logs, runtime files, volumes, images, networks, or containers
+- `docker system prune`, `docker volume prune`, and similar cleanup commands
+- editing files under `/data/compose/4` or the mounted FaceAI host paths
+
+Before any consent-gated action, ask a concise confirmation question that names the exact action and the affected services.
+
+## Safety Boundaries
+
+- Default to inspection first. Do not jump directly to restarts or updates when logs or status already explain the issue.
+- Do not run cleanup commands opportunistically.
+- Do not edit Compose files on the host unless the user explicitly asks for that change.
+- Do not assume that `regalami-faceai` startup errors are frontend issues. Check Redis reachability, processor availability, and mounted log files first.
+- If a command may produce a long interactive stream, prefer a bounded `docker logs --tail ...` read before following with a live stream.