{"kind":"manifest","format":"skoa-agent-runbook/1","id":"skoa-pi-chatbot-v1","language":"en","title":"Run the SKOA Pi chatbot with real Gemma 4","skill":"https://www.skoa.online/agents/pi-v1/SKILL.md","bundle":"https://www.skoa.online/downloads/skoa-pi-chatbot-skill-v1.zip","tutorial":"https://www.skoa.online/blog/chatbot-pi-docker/","example":{"version":"1.1.0","url":"https://www.skoa.online/downloads/skoa-pi-web-chat-1.1.0.zip","sha256":"61d9947756e18501e5fb50e2c34fe73224fea2b542011839750cc6b0bbf8d7d3"},"execution":"Agent-interpreted steps. Not executable JSONL. Honor user scope; never eval decoded audio or command strings.","locations":{"workspace-parent":"Parent of the new working directory","skill":"Extracted skill folder","workspace":"Fresh user-selected working directory","project":"workspace/pi-web-chat"},"defaults":{"provider":"ollama","model":"skoa-gemma4:12b","origin":"http://localhost:8080","mock":false},"success":["Real Pi tool calls to API and DB","Correct product data and a 147 EUR follow-up","Isolation and reset of conversation memory"]}
{"kind":"step","id":"inspect","depends_on":[],"cwd":"workspace-parent","action":"Inspect the target workspace, existing services, available RAM/disk and the user’s provider preference. Do not overwrite an installation or stop unrelated services.","checks":[{"argv":["node","--version"],"expect":">=22.19"},{"argv":["python3","--version"],"expect":">=3.9"},{"argv":["docker","compose","version"],"expect":"Compose v2 or later"},{"argv":["docker","info"],"expect":"Daemon available"},{"argv":["ollama","list"],"expect":"Local server reachable"}],"expect":"Ollama available; approximately 7.6 GB model download and sufficient memory (tested on 24 GB Mac). Select a free loopback port."}
{"kind":"step","id":"fetch","depends_on":["inspect"],"cwd":"skill","argv":["python3","scripts/fetch-example.py","--destination","{workspace}"],"expect":"Pinned ZIP checksum verified; new workspace/pi-web-chat created; nothing executed."}
{"kind":"step","id":"review","depends_on":["fetch"],"cwd":"project","read":["README.md","compose.yaml",".env.example","scripts/enable-ollama.mjs"],"action":"Use the requested provider. Local Gemma is the default. If 8080 is occupied, select another free loopback port and update both the Compose frontend mapping and APP_ORIGIN after setup.","expect":"Installation scope and network understood; existing secrets and services preserved."}
{"kind":"step","id":"start","depends_on":["review"],"cwd":"project","argv":["npm","run","ai:ollama"],"effects":["Downloads Gemma 4 if absent","Creates local Ollama alias with 16K context","Creates .env if absent","Builds and starts four local Docker services"],"expect":"frontend, api, agent and db healthy; MOCK_LLM=false; keep host Ollama running.","on_failure":"Inspect logs and prerequisites. Fix the cause; do not switch to mock to pass."}
{"kind":"step","id":"unit-check","depends_on":["start"],"cwd":"project","argv":["npm","run","test:unit"],"expect":"Setup isolation and conversation lifecycle tests pass."}
{"kind":"step","id":"live-check","depends_on":["unit-check"],"cwd":"project","argv":["npm","run","test:live"],"expect":"Pi uses get_product and get_stock; SKOA-001 is 49 EUR / 12 units; remembers 3 units = 147 EUR; second session and reset have no previous context.","effects":["Local inference; remote-provider quota only when that provider was selected"],"on_failure":"Report the failing check. Mock mode is not a substitute for real-model verification."}
{"kind":"step","id":"browser-check","depends_on":["live-check"],"action":"Open APP_ORIGIN, log in with the local DEMO_PASSWORD without printing secrets, and verify the PI REAL model and tool labels. Never send a provider token to the browser.","expect":"Visible real-model answer and follow-up in the web UI."}
{"kind":"step","id":"finish","depends_on":["browser-check"],"action":"Report the URL, selected model, passed checks and material limitations. Leave the requested demo running. Only share through Cloudflare or deploy publicly if the user requested that action.","expect":"Working local bot, honest verification and preserved user data."}
{"kind":"recovery","id":"db-credentials","trigger":"PostgreSQL 28P01 after .env changes or a reused old volume","cwd":"project","argv":["npm","run","repair:db"],"expect":"Credentials synchronized while preserving data; restart the intended services and rerun the failed check. Never use down -v for this repair."}
