docs/MACOS_USER_FLOW.md

macOS User Flow

JackAILocal must support macOS without requiring the user to understand manifests, model folders, Ollama, llama.cpp, or terminal commands.

Hackathon/MVP flow

1. The user downloads the JackAILocal builder ZIP from the SaaS.
2. Safari usually extracts the ZIP automatically. If not, the user double-clicks it.
3. The user inserts a USB/SSD.
4. The user double-clicks BUILD-USB-MAC.command.
5. The builder finds the embedded manifest automatically.
6. The builder detects external volumes under /Volumes.
7. The user confirms the target volume.
8. The builder writes the runtime, config, manifest, folders, and planned models.
9. If Ollama is available, the builder downloads selected Ollama models to the USB/SSD.
10. The user opens the prepared USB/SSD and double-clicks START-HERE.command.

Production flow

For a real non-technical product, replace .command files with a signed and notarized .app bundle:

• JackAILocal Builder.app
• JackAILocal.app on the prepared key

This avoids Gatekeeper confusion and reduces the visible terminal experience.

macOS constraints

• Gatekeeper may block unsigned apps or downloaded shell scripts.
• Code signing and notarization are required for a commercial Mac experience.
• Apple Silicon uses unified memory, not discrete VRAM. Model policy should consider total RAM and chip family.
• Metal-enabled llama.cpp builds are important for Apple Silicon performance.
• The Mac version should not promise the same GPU behavior as Windows/NVIDIA.