Skip to content
Puzzak edited this page Nov 20, 2026 · 1 revision

Frequently Asked Questions (FAQ)

Everything you need to know about PAIOS (Personal AI Operating System, page.puzzak.paios) as of v1.8.9+26112001: 100% offline on-device Gemini Nano inference, Android AICore troubleshooting (ErrorCode 601/606/-101), v3 vs v4 model variants, System Assistant Overlay & on-demand inspect_screen, M3x Mesh extensions, localization (zh-Hans), custom .md prompts, and Nightly builds.

Table of Contents


Privacy, Offline Architecture & Storage

1. How does PAIOS work 100% offline? Does it send data to external servers?

PAIOS runs inference 100% locally on your phone's NPU/TPU via Android AICore (com.google.android.aicore) and Google's ML Kit GenAI Prompt API (com.google.mlkit:genai-prompt:1.0.0-beta5). No prompt text, chat history, camera photo, gallery image, or screen context is ever sent to cloud LLM APIs, and PAIOS requires zero API keys.

The only optional network activity in PAIOS is strictly non-conversational or opt-in:

  • Opt-in online extension modules (Wikipedia paios.wikipedia, DuckDuckGo Instant Answer paios.search, and Open-Meteo Weather paios.weather) are disabled by default in Settings -> Extensions.
  • Translation & Documentation SWR sync: Fetches updated translation JSONs or Google .md.txt documentation pages when refreshed (with bundled offline fallbacks and captive-portal protection).
  • Optional anonymous analytics/crash reporting, if enabled.

2. Why does PAIOS refuse system/network commands (like ping) or arbitrary web access?

Because PAIOS is designed around a strict on-device sandbox:

  • No arbitrary web browsing: Gemini Nano executes locally inside AICore and cannot open URLs or fetch live pages on its own.
  • No shell execution: PAIOS cannot spawn terminal commands or access arbitrary OS internals.
  • Explicit M3x Mesh tools only: Actions and live data run strictly through registered M3x Mesh tools (for example, PTK page.puzzak.ptk exposes TCP ping and Statuspage diagnostics, while opt-in built-in modules handle Wikipedia/DuckDuckGo/Open-Meteo). If a requested tool is missing or disabled, PAIOS refuses honestly rather than fabricating output.

3. Where are my chats, overlay sessions, and settings stored?

Conversations, personas, preferences, and cached resources are stored locally inside the app sandbox using Hive ('paios_storage') and Android SharedPreferences (page.puzzak.paios).

Sessions started in the native Kotlin System Assistant Overlay (MeshOverlayActivity) are automatically queued into flutter.pending_assistant_chats on dismissal and drained into your main Hive chat history both on cold boot and immediately on foreground resume (AppLifecycleState.resumed in v1.8.9). See the Security Policy for local security guidance.


Supported Devices, AICore Errors & Bootloaders

4. Why does PAIOS say my device or Android AICore is unsupported?

PAIOS is a client for Android AICore / ML Kit GenAI (Gemini Nano), so Google controls hardware and firmware eligibility. Check the Supported Devices & AICore Error Taxonomy guide for the full matrix, and verify these prerequisites:

  1. Supported Hardware: Pixel 8/9/10 (note: Pixel a-series such as 9a/10a are restricted by Google unless Google enables them), Samsung Galaxy S24/Z6/S25/S26+, or supported Snapdragon 8 Gen 3/Elite / Dimensity 9300+ flagships.
  2. Android 14+ (minSdk = 34) with Google Play Services and Android AICore (com.google.android.aicore) installed and updated from Google Play.
  3. 8 GB+ RAM (12 GB+ recommended for multimodal tasks) and 2.5–3.5 GB free internal storage for model weights.
  4. Pixel 8 / 8a Developer Options: On some devices (especially Pixel 8/8a), open Settings -> System -> Developer options -> AICore Settings and enable Enable on-device Gemini Nano and Enable Aicore Persistent Mode.

5. Why do unlocked bootloaders and custom ROMs fail with AICore?

Google AICore enforces device attestation and Play Integrity before provisioning or running Gemini Nano:

  • Unlocked bootloader: AICore intentionally disables on-device Gemini Nano model downloads and Prompt API access on devices with an unlocked bootloader (usually surfacing ErrorCode 606 - FEATURE_NOT_FOUND).
  • Custom ROMs / Non-GMS builds: ROMs without certified Google Play Services and OEM AICore feature provisioning cannot bind to or download Gemini Nano weights.

PAIOS cannot bypass Google's AICore hardware/bootloader attestation checks.

6. What do AICore ErrorCode 601, 606, and -101 mean, and how do I fix them?

Error Code Constant Cause How to Fix
601 BINDING_FAILURE (4-CONNECTION_ERROR) Failed to bind to the Android AICore system service (common right after phone setup or an AICore update). Update Android AICore on Google Play, reboot your device, or reinstall PAIOS.
606 FEATURE_NOT_FOUND (3-PREPARATION_ERROR) AICore stub is present, but Google Play / OEM firmware has not provisioned the Gemini Nano feature catalog yet (also appears on unlocked bootloaders and some Xiaomi/Poco firmwares). Since v1.8.8, PAIOS shows a dedicated OEM provisioning diagnostic card in Setup and Model Settings. Keep internet connected, update AICore + Play System Update, and reboot.
-101 AICORE_INCOMPATIBLE AICore APK is missing or too old for ML Kit GenAI 1.0.0-beta5 (note: runtime hardware busy is ErrorCode.BUSY = 9, which PAIOS auto-retries). Install or update Android AICore (com.google.android.aicore) from the Play Store.

For the full table (9, 12, 4/11, 27, 30, 8/16, 1-DOWNLOAD_ERROR), see Supported Devices & AICore Error Taxonomy.


Gemini Nano Variants (v3 vs v4) & Response Behavior

7. What is the difference between Gemini Nano v3 and v4?

PAIOS lets you switch channels and download supported variants in parallel via the header "nano-v3"/"nano-v4" chip or Settings -> Model (see Architecture & Model Variants):

Aspect Gemini Nano v3 (Stable) Gemini Nano v4 (Preview / Beta)
Internal Variants gemini-nano-v3 (stable/full, stable/fast) gemini-nano-v4-full, gemini-nano-v4-fast
Context Window 4,096 tokens Up to 8,192 tokens
Thinking Mode Not supported Native thoughtProcess collapsible reasoning blocks
Tool Calling JSON / Prompt-guided tool calls Native <ctrl42>call:... & FunctionCall streaming capture
Acceleration & Stability Production NPU/TPU acceleration on supported devices Preview/Beta in AICore; on some devices v4 may run experimentally (or CPU-bound) depending on AICore beta rollout

Since v1.8.9, both variants benefit from ML Kit 1.0.0-beta5 model.warmup(), PromptPrefix KV-caching, native multi-image ImagePart lists, and countTokens / getTokenLimit telemetry.

8. Why are answers shorter, cut off, or different from cloud LLMs?

Gemini Nano is a compact local model tuned for mobile NPU memory, latency, and battery—not a massive server-side model:

  • 256-token output ceiling & 25s watchdog: Google AI Core caps each single generation call at 1–256 tokens (Settings -> Model parameters -> Max response tokens). PAIOS automatically bridges cutoffs with tail-bounded [CONTINUATION] turns (maxProseContinuations = 3, up to 10 for open code blocks), overlap/stutter loop deduplication, and trimTrailingIncompleteSentence cleanup.
  • Safety filters: Profanity or sensitive content can trigger AICore safety errors (4 / 11). PAIOS automatically applies [POLICY FALLBACK RETRY] sanitization or surfaces a clean error state instead of stalling.
  • Context budget: Long chat histories are pruned dynamically via PAIOS's token-budgeted sliding window (historyBudget) to avoid REQUEST_TOO_LARGE (12).

System Assistant Overlay, inspect_screen & Vision

9. How does the System Assistant Overlay work?

When you set PAIOS as Android's Default digital assistant app, PaiosVoiceInteractionService launches MeshOverlayActivity—a native Kotlin Material 3 Expressive bottom sheet running in a separate task (page.puzzak.paios.overlay) without initializing the Flutter engine. This gives near-instant launch speed over any app, full tool-calling & Markdown support, Thinking Mode display, and a Open in Full App handoff button. See System Assistant Overlay & Screen Inspection.

10. How does on-demand inspect_screen work, and when is screen context used or ignored?

Earlier assistant builds injected screenshots on every turn, causing unrelated questions to misread background apps and burn vision tokens. Since v1.8.5–v1.8.9, PAIOS uses lazy on-demand inspect_screen:

  1. Silent 3-turn buffer (SCREEN_CONTEXT_TTL_TURNS = 3): When summoned over another app (skipped automatically when opened inside PAIOS itself), the overlay trims system bars/cutouts and holds the screenshot + filtered AssistStructure privately for up to 3 turns.
  2. Never force-injected: The screenshot is not attached to general prompts. Instead, Gemini Nano only sees the inspect_screen tool definition.
  3. Used only when asked: If you ask about your screen ("Summarize this page", "Explain this error"), Gemini Nano invokes inspect_screen.
  4. Auto-discarded: Unrelated prompts, M3x Mesh tool queries, or photo attachments ignore the screen buffer, and after 3 turns (or on image attachment/reset) the screenshot bitmap is recycled and dropped.

11. How do I turn off passive screen capture or text reading?

To disable screen capture and UI hierarchy access system-wide:

  1. Open Android Settings -> Apps -> Default apps -> Digital assistant app.
  2. Tap the gear icon (or Digital assistant app details, depending on your OEM).
  3. Toggle off Use screenshot and/or Use text from screen (AssistStructure).

You can still attach images manually anytime via Gallery or Camera inside the overlay.

12. How do Camera and Gallery attachments work, and why does attaching a photo replace the screenshot?

  • Camera (Take Photo): Uses Android's ACTION_IMAGE_CAPTURE with a secure FileProvider cache URI, so PAIOS does not need the runtime CAMERA permission. Captures are EXIF-orientation corrected and temporary cache files are cleaned up.
  • Gallery & Multi-Image (beta5): In v1.8.9, multiple attached images are passed natively as ImagePart entries (instead of vertical bitmap stitching), with optional 768px fast NPU downsampling and explicit .recycle() memory cleanup.
  • Replacing passive screenshots: Attaching a photo from Camera or Gallery immediately drops any buffered background screenshot and clears prior visual memory so 100% of Gemini Nano's vision resolution budget is dedicated to your photo.

13. Does the Assistant Overlay remember my attached photo on follow-up questions?

Yes. Within an active Assistant Overlay session, PAIOS summarizes the visual turn in the background after the initial reply so text-only follow-up questions retain context about your photo without re-encoding raw bitmaps on every turn. Resetting/closing the overlay, removing the attachment, or attaching a new image clears that visual memory.


M3x Mesh Ecosystem & Extensions

14. What is M3x Mesh, and which built-in and companion extensions exist (PTK, Alerts, Speech Services)?

M3x Mesh (packages/m3x_mesh) is PAIOS's on-device Android IPC protocol (ContentProvider authorities matching *.mesh, 16s execution timeout, up to 6 chained tool turns per prompt) with zero cloud relays. See M3x Mesh Ecosystem & Extensions.

  • Built-in Offline Modules (Enabled by default):
    • paios.docs (query_aicore_documentation / about_paios): Offline/SWR search over all 23 bundled ML Kit GenAI & PAIOS self-knowledge docs.
    • paios.device (get_battery_status): Live battery level & charging state.
    • Overlay inspect_screen: Lazy 3-turn screen + AssistStructure inspection.
  • Built-in Online Modules (Opt-in, Disabled by default):
    • paios.wikipedia (wikipedia_summary, wikipedia_details), paios.search (duckduckgo_search), and paios.weather (weather_forecast via Open-Meteo).
  • Compatible & Planned Companion Apps:
    • PTK (Puzzak's ToolKit) (page.puzzak.ptk): Server telemetry, Statuspage incident monitoring, and TCP ping diagnostics.
    • Alerts (page.puzzak.alerts): Ukraine air raid alerts and map status.
    • Speech Services (TinyASR & TTS) (page.puzzak.speech, planned): A dedicated standalone companion APK delivering offline Rust TinyASR + Silero VAD speech-to-text and neural TTS over android.speech.RecognitionService and M3x Mesh—keeping heavy native ASR runtimes out of page.puzzak.paios.

15. How do I enable, disable, or inspect connected extensions?

Open Settings -> Extensions:

  • First-party Puzzak extensions (page.puzzak.*, com.puzzak.*) are enabled by default.
  • Third-party extensions are disabled by default until you toggle them individually or enable "Allow all new extensions".
  • Tap any extension to open the schema inspector and inspect its package ID, live status, exposed tools, and parameter schemas. Disabled extensions are excluded from both system prompts and tool execution.

Localization (zh-Hans) & Custom Markdown Prompts

16. Which languages are supported, and how does Simplified Chinese (zh-Hans) detection work?

PAIOS supports 6 languages across both the Flutter app and native Kotlin Assistant Overlay:

  • en (English), uk (Українська), zh (繁體中文 / Traditional Chinese), zh-Hans (简体中文 / Simplified Chinese), de (Deutsch), and tr (Türkçe).

Since v1.8.8 and completed with 100% key parity (469 keys) in v1.8.9 (forward-ported from PR #36), both Dictionary.resolveSupportedLocaleCode (Dart) and MeshOverlayActivity.resolveOverlayLanguage (Kotlin) perform script- and region-aware locale detection:

  • Tags containing Hans, CN, SG, or MY resolve automatically to zh-Hans.
  • Tags containing Hant, TW, HK, MO (or generic zh) resolve to zh.

PAIOS also runs a mojibake self-healing check (Dictionary.hasMojibake / repairMojibake) so corrupted cache or remote entries can never overwrite clean bundled translations. See Localization & Prompts.

17. How do custom .md system prompts and SAF folder sync work?

Open Settings -> Prompts to browse, clone, edit, import, or export [USER INSTRUCTIONS] personas in Markdown:

  • Slim default prompt: system_default.md is intentionally kept to 2 sentences and refreshed from bundled assets on startup, freeing token headroom while delegating PAIOS self-knowledge to query_aicore_documentation.
  • Android SAF UTF-8 Sync: Link any folder via Storage Access Framework (pickPromptsFolder) to immediately import .md files and export custom personas (FileAccessService.exportMd uses explicit utf8.encode and preserves Unicode letters/digits in filenames via nameToFilename).

Nightly Builds, Legacy Versions & Support

18. How do I join PAIOS Nightly / Beta releases?

  1. Join the Tester Google Group (required for Play Store Nightly access): PAIOS Nightlies Google Group.
  2. Opt in to Google Play Testing: Open Google Play Testing (page.puzzak.paios) using the same Google account.
  3. Or sideload from GitHub: Signed APKs and nightly prereleases are published on Puzzaks/PAIOS Releases.

19. Why do older versions (below 1.1.2) fail to work or update?

Versions earlier than 1.1.2 used the legacy page.puzzak.geminilocal package ID and older AICore bindings. PAIOS now uses page.puzzak.paios (and automatically sanitizes legacy geminilocal links in cached resources). Install the current release from Google Play or GitHub Releases.

20. Where can I check device compatibility or report a bug?


Related Pages: Home · Supported Devices & AICore Error Taxonomy · Architecture & Model Variants · System Assistant Overlay & Screen Inspection · M3x Mesh Ecosystem & Extensions

Clone this wiki locally