ai-spel-frontend/AGENTS.md

AI-spel frontend instructions

• This repository owns only the static, accessible web client and its container/chart packaging.
• Rust remains the sole authority for game state. The frontend calls the backend through same-origin /api/... and /version paths.
• Keep frontend and backend behind ai-spel.k3s.k0.nu so session cookies remain same-origin.
• The public footer displays frontend, static-service, and API versions; load static-service version from uncached /static/version.json.
• VERSION is the only release-version source in this repository. Use scripts/bump-version.py; do not manually edit chart versions.
• Changes are written locally and built, checked, published, and exercised by Gitea Actions on the existing large runner and Kubernetes. Never run apps, tests, containers, images, or binaries locally. Do not create or register runners.
• Never commit secrets, generated credentials, kubeconfigs, or environment files.
• Helm charts are published to harbor.k3s.k0.nu/ai-spel; Argo CD uses the existing ai-spel project and namespace.
• Player-facing speech uses the local Piper WebAssembly adapter when the player has activated audio. The separate ai-spel-static Nginx service serves pinned Swedish Piper models and ONNX/Piper runtime files from same-origin /static/piper-wasm-v1/ URLs with immutable caching. Game text is synthesized on-device and must never be sent to a TTS provider.
• This pipeline bundles only the Piper worker/client glue. Model/runtime downloads, image builds, and deployment belong to ai-spel/ai-spel-static and the existing large runner. Never build or run these assets locally.
• Browser local AI loads its client adapter, Wllama runtime, WebAssembly, Gemma model, manifest, YAML prompt, and license resources only from the same-origin /static/wllama-gemma3-v1/ path owned by ai-spel/ai-spel-static. Do not add browser CDN, npm, or model-hub fallbacks. The player must be shown and accept applicable model terms before the model downloads or runs. Acceptance, model failure, or local-AI opt-out must never block play. Incompatible asset changes require a new immutable static path and a coordinated frontend release.
• Local model output is advisory only. Preserve the original player input, send local hints only as untrusted context to Rust, and label offline replies as unsaved. Local diagnostic logging is opt-in, browser-local, exportable/deletable, and expires after 30 days.