# Ecosystem Personal Timeline PRD

> **Status:** Hardened baseline
> **Owner:** `learning_ai_common_plat`
> **Purpose:** Define a shared user activity timeline that makes cross-product behavior visible and useful.

---

## 1. Problem

The ecosystem can produce many meaningful user events and artifacts, but users cannot yet see them as one coherent stream.

Examples:

- transcript captured in LysnrAI
- note created in NoteLett
- memory created in MindLyst
- plan created in FlowMonk
- routine executed in ChronoMind
- agent run completed in Cowork
- approval granted in Auth App

Without a personal timeline:

- the ecosystem feels fragmented
- provenance is hard to understand
- “one action, many outcomes” is invisible

---

## 2. Product Goal

Give Saravana and future users one place to answer:

- what happened?
- what created it?
- what did it affect?
- what needs follow-up?

---

## 3. Timeline Inputs

The timeline should consume:

- canonical ecosystem events
- canonical artifact envelopes
- approval records
- selected trust/risk changes

---

## 4. Phase-1 User Stories

- [x] As a user, I can see that one dictated transcript became a note and a memory candidate.
- [x] As a user, I can see that one plan generated a routine and a habit.
- [x] As a user, I can see that one Cowork run produced an output and required an approval.
- [x] As a user, I can trace each item back to its source product and action.

---

## 5. Minimum Timeline Item Shape

```ts
type TimelineItem = {
  itemId: string;
  occurredAt: string;
  eventName: string;
  productId: string;
  title: string;
  summary?: string | null;
  artifactRefs: string[];
  relatedEventIds: string[];
  actorType: 'user' | 'agent' | 'system' | 'device';
  visibility: 'private' | 'org' | 'shared' | 'local-only';
};
```

---

## 6. Noise Filtering Rules

Not every ecosystem event belongs in the first user-facing timeline.

Default include:

- artifact creation and linking
- accepted memory creation
- plan, routine, and habit outcomes
- approvals that materially affected execution
- agent run milestones with user-visible outcome

Default suppress or collapse:

- low-level polling or sync churn
- internal projection or materialization events
- repeated update noise without a user-visible state change
- internal retry attempts unless they become failures or user-facing delays

Grouping rules:

- collapse dense chains by `correlationId` when they belong to one user-visible outcome
- show source event and primary derived outcomes first
- allow drill-in for the detailed chain rather than making the main timeline noisy

## 7. Hosting Choice

Current baseline choice:

- internal hosted timeline remains in `admin-web`

Near-term product rule:

- keep the current timeline in `admin-web` while the event vocabulary and filtering model stabilize
- defer public user-facing timeline placement until the product semantics are less admin-centric

Longer-term options:

1. a user-facing portal shell in `learning_ai_common_plat`
2. a NoteLett or MindLyst embedded personal activity view
3. a dedicated cross-product "home" surface if the ecosystem grows materially

## 8. Open Decisions

1. How should local-only events from local-memory products be represented?
2. Should timeline items stay materialized, or should some views query live from source systems?
3. When should the timeline graduate from admin-web into a user-facing home surface?

---

## 9. Acceptance Criteria

1. The two phase-1 golden flows can be rendered in one unified timeline.
2. Timeline items can link back to underlying artifacts and source products.
3. Users can tell which outputs were created automatically vs manually.
4. Approval and trust transitions can be surfaced when relevant.

---

## 10. Implementation Checklist

- [x] define timeline item contract
- [x] define event-to-timeline inclusion rules
- [x] define artifact linking behavior
- [x] define noise filtering rules
- [x] define phase-1 UI hosting choice
- [x] define verification flow using golden paths

Commits:

- `7a86a76` drafted the initial version
- `3f2482b` added the baseline `TimelineItem` schema and event-to-timeline aggregator
- `617d970` tracked timeline hardening as remaining work
