# JackAILocal System Behavior

## Layers

1. The Gradio Builder accepts a real hardware profile, recommends compatible models, and exports manifests or builder packages.
2. Platform builders prepare a local folder, USB drive, or external SSD and validate the resulting payload.
3. `jackailocald` serves the WebUI and routes requests only to reachable local AI engines.

## Runtime

The Rust runtime serves static WebUI files and these primary APIs:

```text
GET  /api/status
GET  /api/features
GET  /api/models
POST /v1/chat/completions
GET  /api/threads
POST /api/threads
POST /api/threads/:id/messages
POST /api/vision/analyze
GET  /api/voice/status
POST /api/voice/transcribe
POST /api/voice/synthesize
POST /api/packs/export
POST /api/packs/import
POST /api/agent/recommend
GET  /api/phone
POST /api/phone
POST /api/runtime/restart
```

Chat and SCOUT use installed Ollama models. An OpenAI-compatible `llama.cpp` server can be used as an explicit local chat fallback. Voice uses whisper.cpp and Piper binaries and models stored in the package.

`POST /api/agent/recommend` adds a local LLM-in-the-loop for client configuration and model selection review. It uses only installed local models, enforces the <=32B catalog policy, prefers Gemma 4 12B (`gemma4:12b`) when present, and returns an explicit error when a requested agent model is unavailable.

The runtime reports a feature as available only when the required local engine and model are available.

## Storage

```text
workspace/threads/       conversation JSON files
workspace/documents/     user notes
workspace/settings/      local settings and phone pairing token
workspace/exports/       encrypted packs and support ZIPs
workspace/voice/         temporary voice files
workspace/scout/         SCOUT workspace
models/ollama/           Ollama model store
models/whisper/          speech-to-text models
models/piper/            text-to-speech models
```

Threads are persistent and support filtering, rename, and individual deletion.

## Phone Access

The default bind is `127.0.0.1:4891`. Phone Access must be enabled explicitly. After restart, the runtime binds to `0.0.0.0:4891`, generates a LAN URL and QR code, and requires `X-JackAILocal-Token` for non-loopback API requests.

## Transfer Packs

Transfer packs use AES-256-GCM with PBKDF2-HMAC-SHA256. Passphrases are not stored. Imported settings are sanitized so a pack cannot silently enable Phone Access or transfer a pairing token.

## Builders

Builders install selected Ollama models, install Voice assets, generate a SHA-256 manifest, and refuse success when required files are missing. The source package and target path must not overlap.

## Offline Boundary

Normal use does not require internet after models and Voice assets are present. The runtime has no cloud inference fallback. A capability that cannot run locally returns an explicit unavailable or error response.