Refine backendless share intake

docs/ADR/0003-backendless-local-llm-pipeline.md

@@ -0,0 +1,64 @@
+# ADR 0003: Backendless Local LLM Pipeline
+
+## Status
+
+Accepted
+
+## Context
+
+The product goal is a phone-first relationship memory app. The user shares
+messages and text snippets from messaging apps, resolves uncertain identity
+matches over time, and receives private extraction plus useful suggestions.
+
+The app is moving away from a server-backed source of truth. Backend sync and
+the fake backend should not create or overwrite relationship data unless a
+developer explicitly enables REST sync for transport work.
+
+iOS does not provide a reliable always-running background service. Background
+work must be treated as opportunistic: run on foreground/app resume, after share
+intake, through user-initiated actions, and through scheduled background windows
+when the OS grants time.
+
+## Decision
+
+Use a backendless local-first pipeline:
+
+1. Share intake stores raw shared payloads locally.
+2. Strong identity matches attach directly to an existing person.
+3. Ambiguous, conflicting, or low-information shares stay in `Share Inbox`.
+4. Nightly extraction processes only new/resolved share batches.
+5. Weekly/on-demand recommendations use compact profile summaries plus prior
+   suggestion history to avoid repeats.
+6. Internet-grounded recommendations are generated only during the weekly or
+   manual recommendation phase, not during nightly extraction.
+7. Fake backend sync is inert by default and must not seed local relationship
+   records.
+
+## LLM Cost Controls
+
+- Batch new shares into one extraction request per run.
+- Use source fingerprints and content hashes to skip repeated extraction.
+- Store extraction run fingerprints, completed timestamps, and failures.
+- Send compact person tokens and normalized facts instead of names and raw
+  history when possible.
+- Keep grounded shopping/event prompts separate from nightly extraction because
+  web search is more expensive and time-sensitive.
+- Include accepted/dismissed/pending suggestion fingerprints in weekly prompts
+  so repeated concerts, shops, or gifts are suppressed.
+
+## iOS Background Policy
+
+- Treat scheduled nightly and weekly work as best-effort.
+- Always offer manual `Run Now` actions.
+- Prefer local notifications after work completes.
+- Do not require APNs or a server daemon for core behavior.
+- Keep work units short enough to survive iOS background expiration.
+
+## Consequences
+
+- The app remains useful without any backend.
+- Share capture and profile building are durable across weeks/months of gradual
+  user review.
+- Suggestions may run later than the configured wall-clock time on iOS.
+- REST sync can still exist as a developer/integration path, but it is not part
+  of the primary product loop.

docs/SETUP.md

@@ -25,7 +25,8 @@ flutter run --dart-define=USE_FAKE_BACKEND=true
 ## Background Sync
 
 Background sync (startup + resume + periodic ticks while authenticated) is
-enabled by default.
+disabled by default. The current product direction is backendless/local-first,
+so backend sync should be enabled only for REST transport development.
 
 In REST mode, auto-triggers are reachability-gated to avoid unnecessary sync
 attempts while offline.
@@ -78,7 +79,23 @@ Behavior notes:
 ## Phone-Only Private AI Digest
 
 The app can run without a production backend by keeping `USE_FAKE_BACKEND=true`
-and using the LLM integration only for a private weekly digest.
+and using the LLM integration for local profile extraction and private digest
+generation.
+
+Selected product flow:
+
+- share messages/text from WhatsApp, iMessage, Notes, Safari, or similar apps
+  into the app
+- auto-match only when identity evidence is strong
+- keep ambiguous or low-information shares in `Share Inbox`
+- let the user gradually resolve inbox items over days, weeks, and months
+- run local/profile-building extraction opportunistically and on scheduled
+  nightly windows when the OS allows it
+- run grounded weekly recommendations on request or on the configured digest
+  schedule
+
+Backend sync is not part of this path. The fake backend is intentionally inert
+for sync pulls and must not seed people or other relationship records.
 
 Digest behavior:
 
@@ -86,6 +103,10 @@ Digest behavior:
 - scheduled digest payloads use pseudonymous tokens such as `person_001`
 - names, aliases, sender names, source URLs, raw shared text, and sensitive
   notes are not sent in the scheduled digest prompt
+- repeated LLM work should be avoided by fingerprinting unresolved/new share
+  batches and skipping extraction when the same batch has already completed
+- weekly recommendation prompts should include previously suggested/dismissed
+  items so the model avoids repeats
 - LLM results are saved as pending AI review drafts first
 - accepting a draft creates a local idea, task, or reminder
 - dismissing a draft leaves existing local data unchanged