rely/docs/client-iteration-summary.md

# 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.