Starting Point

Pip started as a global assistant overlay attached to the native SwiftUI app. The first version could read a compact `PipGameContext`, hand that context to Apple's FoundationModels APIs when available, and fall back to deterministic Swift text when Apple Intelligence failed. This was enough for flavor, but not enough for reliable game help.

Initial architecture

SwiftData persisted the game. SwiftUI showed the chat. `PipGameChatService` built a response from broad screen facts, recent archive records, and a generic FoundationModels prompt. It was useful for atmosphere, but weak at precise mechanics and yes/no answers.

Observed failure mode

Pip sometimes meandered, answered adjacent mechanics, dumped raw current state, or used Apple Intelligence for questions that should have been deterministic. The assistant needed a verified retrieval layer and intent-aware routing before prose generation.

Final Architecture

The new system separates truth, retrieval, routing, and editorialization. SwiftData remains the source of truth. SQLite FTS is a local secondary index. The router decides when a question is a mechanics query, action audit, next move, memory editorial request, or general screen question. Apple Intelligence is used only after deterministic systems have bounded the context.

Truth
SwiftData Game State Player, bots, missions, discoveries, memories, projects, guild, prestige, inventory, and entitlements.
Context
PipGameContext Builds live facts, action audits, spending context, entitlement context, archive items, and search documents.
Retrieve
SQLite FTS5 Indexes mechanics and live records locally so Pip can retrieve relevant facts without scanning the whole archive.
Route
Question Intents Classifies mechanics, availability, next action, spending, memory, guild, project, item, store, and general questions.
Answer
Deterministic + Apple Swift answers rules and state. Apple Intelligence adds concise editorial synthesis when useful.

What Changed

1. Pip stopped treating every question as prose generation

Questions like "Can bots be upgraded directly?", "Does Discovery Momentum cap?", and "What should I focus on next?" now bypass Apple Intelligence and resolve through local Swift logic. That keeps answers precise, short, and inspectable.

2. Mechanics became router-level intents

The routing layer now recognizes mechanics intents such as mission success chance, Discovery Momentum caps, Data Pack use, Premium benefits, Jockey level cost, bot direct upgrades, Memory Archive unlocks, and Guild automation requirements. This is more durable than wiring one-off Q&A pairs.

3. Retrieval became local and bounded

`PipSearchIndexService` mirrors SwiftData-derived documents into SQLite FTS5. It indexes mechanics, memories, discoveries, archive summaries, bots, missions, opportunities, projects, items, Pip caches, guild state, rivals, logs, and Prestige. Search results are ranked locally before any generative step.

4. Apple Intelligence became an editorial layer

FoundationModels now receives verified facts, local mechanics records, FTS-ranked hits, relevant archive records, and a small rolling Pip memory. It is asked to synthesize, not invent. Deterministic fallbacks remain mandatory.

iOS And Apple Intelligence Notes

The app remains local-first. SwiftUI owns the interface, SwiftData owns persistence, StoreKit 2 owns subscription testing, and FoundationModels is optional. Pip must work even when Apple Intelligence is unavailable, unsupported in the simulator, or unable to answer. That constraint pushed the architecture toward deterministic game services first and generative narration second.

SwiftUI

Pip appears as a global chat overlay that can answer across Core, Console, Projects, Guild, and Items without owning those screens.

SwiftData

All game state remains local and canonical. The search index is disposable and can be rebuilt from SwiftData-derived context.

SQLite FTS5

The local index improves relevance as archives grow, especially for memories, discoveries, items, and mechanics lookup.

FoundationModels

Apple Intelligence is used for concise editorialization, memory synthesis, and natural phrasing after local retrieval and routing.

Implementation Notes

The most important implementation decision was to make the assistant testable. Pip's intelligence now lives in small services rather than inside the SwiftUI overlay.

Core services
PipQuestionRouter
PipGameContextService
PipGameChatService
PipKnowledgeBase
PipSearchIndexService
PipMemoryPersistenceService
Answer flow
User question
  -> normalize and classify route
  -> resolve deterministic mechanics/action questions
  -> refresh SQLite FTS index if context changed
  -> retrieve bounded local search hits
  -> optionally call FoundationModels with verified context
  -> persist daily chat summary locally
Verification loop
Ask targeted Pip questions
Check deterministic answer quality
Patch routing intent, not one-off prose, when possible
Build for iPhone simulator
Retest the same questions plus nearby variants

Result

Pip moved from a charming chat overlay to a local game intelligence layer. It can answer mechanics, audit available actions, recommend next steps, retrieve archive context, and use Apple Intelligence for higher-quality memory editorialization. The final lesson is simple: reliable in-game AI does not start with a bigger prompt. It starts with trusted state, explicit routing, bounded retrieval, and a clear line between deterministic truth and generative prose.