docs: add project orientation notes

docs/client-iteration-summary.md

@@ -0,0 +1,146 @@
+# Client Iteration Summary
+
+Date: 2026-04-01
+
+## What was implemented
+
+This iteration focused on client-side share capture, local-first structure, and
+safer person assignment.
+
+Implemented:
+
+- generic shared payload normalization for:
+  - plain text
+  - URL
+  - text + URL
+- a review-first share capture sheet for:
+  - assign to existing person
+  - create person quickly
+  - save to inbox
+- richer local person model support:
+  - aliases / nicknames
+  - last updated / last interacted timestamps
+- richer local knowledge entities:
+  - structured captured facts
+  - important dates
+  - source/provenance metadata
+  - sensitive flag scaffolding
+- inbox triage improvements:
+  - draft mapping to note / like / dislike / date / gift / place / activity / misc
+  - create person directly from inbox
+  - resolve to existing person with fact mapping
+- people profile UI improvements:
+  - aliases visible in profile context
+  - captured facts section
+  - important dates section
+  - edit/delete support for facts and dates
+- Android native text share entry:
+  - `ACTION_SEND` text intent filter added to `AndroidManifest.xml`
+- trust/privacy wording:
+  - clearer local-first copy in settings
+- tests:
+  - generic share payload parser tests
+  - repository tests for inbox-to-fact and date persistence
+  - updated share inbox widget test flow
+
+## Architecture decisions
+
+### Kept the existing repository-centered local architecture
+
+`LocalRepository` remains the orchestrator for local persistence and ingest.
+This avoided a risky refactor and let the new share pipeline build on existing
+person/source-link/moment infrastructure.
+
+### Added structured fact/date entities instead of overloading notes
+
+This creates a cleaner bridge to future recommendation, summarization, and sync
+work. Shared captures can now produce auditable, typed local knowledge instead
+of only raw note blobs.
+
+### Used a review-first share flow for safety
+
+Rather than silently guessing in generic share cases, the app now asks for a
+target person or lets the user save to inbox. This is the safer default for a
+relationship product.
+
+## Known limitations
+
+- iOS still does not have a real share extension target configured. The Flutter
+  share logic exists, but native iOS share-sheet presence remains deferred.
+- Android share support added here is text-focused only.
+- Generic share flows do not infer advanced semantic structure automatically
+  beyond the existing preference extractor.
+- Captured facts and important dates are local-only and not yet mapped into the
+  backend sync protocol.
+- Inbox triage currently converts one structured draft per inbox item. It does
+  not yet split a single payload into multiple facts.
+- Search is still strongest in People and not yet expanded across facts/dates/
+  inbox.
+
+## What should happen next in a backend / LLM session
+
+1. Define backend entity contracts for:
+   - person aliases
+   - structured facts
+   - important dates
+   - shared payload provenance
+2. Add sync-envelope mappings for the new local entities.
+3. Introduce optional AI-assisted extraction that proposes:
+   - multiple facts from one payload
+   - date detection
+   - confidence scoring
+   - recommendation context packaging
+4. Add server-compatible merge/reconciliation rules for conflicting profile
+   facts and dates.
+5. Implement explicit privacy controls for any future cloud or AI sharing.
+
+## Manual walkthrough
+
+### 1. Create person
+
+- Open `People`.
+- Tap `Add person`.
+- Enter:
+  - `Name`
+  - `Relationship`
+  - optional `Aliases`
+  - optional notes/tags/location
+- Save.
+
+### 2. Share text into app
+
+- On Android, share any text snippet into the app from another app.
+- Or use `Settings` -> `Simulate Share Capture`.
+- The review sheet should open showing the parsed text/URL preview.
+
+### 3. Resolve ambiguity
+
+- In the review sheet, choose a fact type such as `Like` or `Note`.
+- Pick an existing person from recent chips or the full dropdown.
+- Save to that person.
+
+### 4. Save to inbox
+
+- Repeat with another shared snippet.
+- In the review sheet, choose `Save To Inbox`.
+- Open `Share Inbox`.
+
+### 5. Assign later
+
+- In `Share Inbox`, open the queued item.
+- Confirm or change the fact mapping.
+- Choose `Review & Save` to match an existing person, or `Create Person`.
+- Complete the flow.
+
+### 6. Edit captured fact
+
+- Open `People`.
+- Select the person.
+- In `Captured facts`, tap `Edit` on the new fact.
+- Change the text/label/type or sensitive flag and save.
+
+### 7. Edit captured date
+
+- If the capture was saved as a date, open `Important dates`.
+- Tap `Edit`.
+- Adjust label/classification/date and save.