# Lead Activity Timeline Actions

## Problem Statement

Sales users can open Lead records, but the Activity tab does not reliably provide the activity timeline and logging actions they need for day-to-day Lead follow-up. Issue #1485 is still open as of 2026-06-02. The first observed failure was the Activity tab falling back to `No sections configured for Activity.` Later regression evidence on build v17795475, recorded on 2026-05-27, showed the Activity tab present but missing action buttons such as Log a Call, Email, and Weekly Update.

The user-facing problem is that a sales rep cannot treat a Lead as an activity-bearing CRM record. Existing Lead follow-up Tasks can be created through the API and related to the Lead, but the browser record surface does not prove the full discover, render, submit, and read-back path.

## Salesforce-Compatible Implementation Understanding

Salesforce models Lead activities through the standard activity model. Lead and Contact are person-side records, so Task and Event records relate to them through the Name relationship, represented by `WhoId`. Account, Opportunity, Order, Contract, Campaign, and similar non-person records relate to activities through `WhatId`.

The Salesforce Activity tab is not a normal layout-section tab. It is a specialized activity timeline surface that reads related Tasks and Events and exposes user-invokable activity logging affordances such as calls, emails, tasks, and events. A Salesforce-shaped implementation therefore has two separate concerns:

- the Activity timeline must mount from record-page metadata rather than from generic layout sections
- activity create affordances must be discoverable through one authoritative action surface and must create records linked through the correct relationship field

NexusCRM currently carries an explicit implementation delta from pure Salesforce Quick Actions. Quick Action describe and execute are not the active owner path for this slice. The current accepted owner path is Standard Actions: action discovery, schema/defaults, renderer lookup, standard-action invoke, flow-backed persistence, and timeline refresh.

## Status Quo

The original #1485 root-cause comment said the upstream CRM frontend registry had an applicability list that omitted Lead. That diagnosis is stale against current upstream main on 2026-06-02. The current CRM registry binds the activity timeline renderer globally by renderer id. Record-panel renderability is now determined by two facts: whether the layout declares a panel with that renderer id, and whether the renderer has been registered.

The official standard CRM pack declares the Lead layout with Details and Activity tabs, plus an Activity record panel using the bundled CRM activity timeline renderer. Opportunity, Account, Contact, and other CRM objects use the same panel shape.

The downstream final pack is the canonical tested artifact, and today its assembly path disables the official `Lead/default` page layout along with several other official layouts. The resulting final pack does not carry the official Lead Activity record panel. That makes the Activity tab mount failure a real current final-pack blocker, not just possible install drift. If a deployed environment still shows `No sections configured for Activity.`, the first pack-side explanation is that the final installed pack lacks a renderable Lead Activity record panel.

The current upstream activity implementation already knows that Lead and Contact use `WhoId`; other objects use `WhatId`. The quick-create renderer also knows this rule and only sends the relation slot that belongs to the current Activity Timeline context.

The current downstream PingCAP pack carries metadata-owned activity quick-create standard actions:

- `taskCall` renders Log a Call and creates a Task through the standard create-task activity flow
- `taskEmail` renders Email and creates a Task through the same flow
- `taskWeeklyUpdate` renders Weekly Update and creates a Task through the same flow

However, in the current downstream pack, `taskCall` and `taskEmail` target Case, Contact, Contract, Opportunity, and Order, but not Lead. `taskWeeklyUpdate` targets Opportunity only. Because the Activity panel filters action discovery by `targetObjects`, a mounted Lead Activity panel discovers no Lead activity actions from these rows.

The API-side watchdog already proves a Task can be created against a Lead through `WhoId`, and the story test-data catalog contains a Lead activity sample. That is necessary but insufficient: it does not prove the browser Activity panel discovers Lead actions, renders the correct modal, posts through the standard-action path, and refreshes to show the newly created activity.

## Solution

Close #1485 by making Lead a first-class Activity Timeline target across the installed CRM pack and the deployed frontend/runtime contract.

For every unconverted Lead record that a sales user can read, the Activity tab must mount the CRM Activity Timeline record panel instead of falling back to layout sections. This requires the final installed pack to carry a Lead page layout that declares the Activity record panel. The panel must show existing Tasks and Events related to the Lead through `WhoId`.

The Lead Activity panel must expose metadata-owned quick-create actions for Log a Call and Email. Those actions must use the same Standard Action owner path as the existing activity quick-create family: discovery by target object, schema/defaults from action metadata, renderer lookup, standard-action submit, flow-backed Task creation, and panel refresh.

The third Lead affordance for this PRD is Weekly Update. This follows the active #760 AC4 and #2023 UAT wording. The older #977 wording, Engagement, remains source-history context and should not be shipped under #1485 unless product explicitly reopens that terminology. Lead Weekly Update should be a Lead-targeted standard action with its own metadata contract, not a silent widening of the Opportunity Weekly Update contract.

## Canonical Behavior Contract

| Surface | Required Lead behavior |
| --- | --- |
| Activity tab mount | Lead layout contributes an Activity record panel, and the registered CRM activity renderer makes the tab a record-panel tab rather than a section tab |
| Timeline query | Task and Event records are queried with `WhoId = Lead.Id` |
| Log a Call | Action is discoverable for Lead, opens from the Activity panel, defaults a Task call, writes `WhoId`, and refreshes the timeline |
| Email | Action is discoverable for Lead, opens from the Activity panel, defaults an Email-style Task, writes `WhoId`, and refreshes the timeline |
| Weekly Update | Action is discoverable for Lead, opens from the Activity panel, creates a Task with the Weekly Update type/defaults, writes `WhoId`, and refreshes the timeline |
| Existing activities | Existing Task/Event rows related through `WhoId` appear in the same timeline after page load or refresh |
| Wrong relation field | Lead activity quick-create must not write `WhatId` to the Lead id |
| Missing renderer/layout | The failure is observable in tests; the product should not silently pass with only a generic empty section state |
| Converted Lead | The timeline must not crash; it may show historical closed activities that still point at the Lead, but it is not required to follow activities relinked to the converted Contact |

## User Stories

1. As a sales rep, I want to open a Lead record and see an Activity tab, so that I can review the Lead's follow-up history without leaving the record.

2. As a sales rep, I want the Lead Activity tab to render the Activity Timeline, so that I do not see a generic `No sections configured for Activity.` message.

3. As a sales rep, I want existing Lead Tasks to appear in the timeline, so that I can see prior calls, emails, and follow-ups.

4. As a sales rep, I want existing Lead Events to appear in the timeline, so that meetings and scheduled interactions are visible next to Tasks.

5. As a sales rep, I want to click Log a Call from the Lead Activity timeline, so that I can record a completed call against the Lead.

6. As a sales rep, I want Log a Call to default the expected call fields, so that I only fill the details that matter.

7. As a sales rep, I want the saved call to appear in the same Lead timeline after save, so that I get immediate confirmation that it was linked correctly.

8. As a sales rep, I want to click Email from the Lead Activity timeline, so that I can record an email-style activity against the Lead.

9. As a sales rep, I want the saved email activity to appear in the Lead timeline after save, so that I can continue working without manually refreshing.

10. As a sales rep, I want a Weekly Update affordance on the Lead Activity timeline, so that I can capture the UAT-required non-call, non-email Lead follow-up action.

11. As a sales rep, I want required activity fields to be visible when no default is available, so that I can complete the form without a hidden validation failure.

12. As a sales rep, I want owner and due-date defaults to be filled from action metadata and session context, so that common activity logging stays quick.

13. As a sales rep, I want a clear error when an activity cannot be saved, so that I know whether the issue is permission, missing metadata, or runtime failure.

14. As a sales manager, I want Lead activities to be linked through the Lead relationship, so that Lead timeline, reporting, and conversion follow-up use the same source of truth.

15. As a sales manager, I want Lead and Contact activities to follow the same person-record relationship rule, so that activity behavior is predictable across people.

16. As a sales operations admin, I want Lead activity buttons to be controlled by action metadata, so that I can reason about availability without reading frontend code.

17. As a sales operations admin, I want Lead Weekly Update behavior to be explicitly declared, so that Lead activity closure does not accidentally mutate Opportunity Weekly Update semantics.

18. As a pack maintainer, I want standard CRM activity behavior to live in the standard CRM app-pack layer when possible, so that downstream overlays do not permanently own generic CRM facts.

19. As a downstream maintainer, I want any temporary PingCAP overlay action rows to be explicit, so that they can be removed after the official standard pack carries the same behavior.

20. As a QA owner, I want a browser watchdog case for Lead Activity actions, so that a panel that merely contains the word Activity cannot be mistaken for a working activity workflow.

21. As a QA owner, I want API coverage for create and read-back, so that the flow-backed write path is pinned independently from browser flakiness.

22. As a release owner, I want build verification to fail when the final installed pack lacks the Lead Activity record panel or the Lead activity action rows, so that staging cannot regress silently.

23. As an upstream maintainer, I want generic record detail code to remain free of Task/Event/WhoId/WhatId branches, so that CRM facts stay in the CRM app-pack adapter while the platform stays app-neutral.

24. As an upstream maintainer, I want the action renderer and record-panel renderer contracts reused, so that Lead activity does not introduce a second page-local registry.

25. As a migration operator, I want imported Lead activities related by `WhoId` to display without rewrite, so that migrated data validates against the same Activity Timeline path as newly created data.

## Implementation Decisions

- Treat the `register.ts` applicability-list RCA as historical, not current. The current design must test layout presence, renderer registration, and action metadata rather than patching a nonexistent Lead applicability list.

- Keep generic record detail behavior unchanged. The generic host should continue to read record-panel descriptors from layout metadata and look up renderers by opaque renderer id.

- Keep CRM activity relationship semantics inside the CRM app-pack adapter: Lead and Contact use `WhoId`; non-person CRM records use `WhatId`.

- Make Lead activity action availability metadata-owned. The Activity Timeline should discover actions through the existing Standard Action path and filter by the Lead target object.

- Restore or replace the Lead page layout in the final installed pack. The current final-pack assembly disables `Lead/default`; #1485 cannot close while the canonical final artifact omits the Lead Activity record panel.

- Add Lead to the target object set for standard Log a Call and Email activity actions in the owning CRM pack metadata. If these rows stay in the downstream overlay as a transition, document that they are compatibility content and not the preferred permanent owner.

- Do not add a page-local Lead branch, a frontend-only Lead action registry, or a second action discovery endpoint.

- Keep Log a Call and Email backed by the existing standard create-task activity flow unless implementation proves the flow cannot satisfy the Lead `WhoId` path.

- Make Weekly Update available on Lead through a distinct Lead-targeted standard action. It should use the same create-task activity flow, label `Weekly Update`, target Lead, write `WhoId`, and default Task Type to `Weekly Update`, Status to `Completed`, Priority to `Normal`, Activity Date to today, and Owner to the current user unless product supplies a different Lead-specific default contract.

- Do not let Lead Weekly Update changes alter Opportunity Weekly Update required fields, defaults, visibility, or read-back behavior.

- Keep Event creation out of this closure unless separately specified. The Activity Timeline must read existing Events on Lead; this PRD only requires Task-backed quick-create actions for Log a Call, Email, and the declared third Lead activity.

- Keep Quick Actions out of the current closure. The current accepted owner path is Standard Actions because Quick Action describe/execute is not the execution-ready substrate for this slice.

- Regenerate the final downstream pack after any pack metadata change and make the generated artifact line up with the official pack plus PingCAP overlay contract.

- Add a deploy/readiness check that distinguishes three failure modes: missing Lead record panel metadata, missing renderer registration, and missing Lead-targeted ActivityTimeline standard actions.

- When the hidden Lead layout disablement is removed or superseded, update the downstream compatibility notes so future maintainers know why `Lead/default` used to be excluded and what replaced that stop-loss.

## Testing Decisions

- The highest test seam is an installed-pack browser workflow: open a seeded Lead, click Activity, verify the Activity Timeline panel renders, verify Log a Call and Email are visible, create one activity, and verify it appears in the timeline without manual database inspection.

- Add or update an API watchdog case that invokes the standard action for a Lead and then queries the created Task by `WhoId`. Direct Task create remains useful, but it is not enough to prove the standard-action contract.

- Add a pack metadata test that verifies Lead is included in the Log a Call and Email target objects for the installed pack, and that the Lead Weekly Update action targets Lead with the expected defaults.

- Extend the final-pack metadata audit to fail when the final pack lacks `Lead/default`, when that layout lacks the Activity record panel, or when `taskCall`, `taskEmail`, or the Lead Weekly Update action omit Lead from their target objects. The existing `scripts/audit_final_pack_metadata.py` is the natural audit target.

- Add a browser watchdog assertion that fails on the literal empty-section state for the Lead Activity tab. A broad assertion that merely finds the word Activity is not sufficient.

- Reuse upstream record-panel registry tests as prior art for renderer registration and panel descriptor renderability. Add a Lead-shaped case if the upstream work happens there.

- Reuse upstream activity quick-create renderer tests as prior art for relation-field payload semantics. The test should prove a Lead context submits `WhoId` and omits `WhatId`.

- Reuse upstream standard-action dispatcher tests as prior art for defaults, required fields, and hidden input materialization.

- Keep Opportunity Weekly Update regression coverage in place. Lead activity changes must not remove Opportunity's Weekly Update affordance or alter its required fields.

- Keep the existing API case that creates a Lead Task through `WhoId`; it is useful as lower-level data-path proof.

- Converted Lead verification is a stability check, not a full workflow check. Conversion intentionally relinks open Lead Tasks to the converted Contact, so the converted Lead timeline only needs to avoid the empty-section fallback and display any historical activities that still point at the Lead.

## Out of Scope

- Rebuilding the generic pack-declared related-surface substrate beyond the existing record-panel host.

- Implementing Salesforce Quick Action describe/execute for this fix.

- Introducing a new Event quick-create modal.

- Reworking EmailMessage, Einstein Activity Capture, or external email sending.

- Changing Opportunity Weekly Update business semantics as part of Lead activity closure.

- Reintroducing Engagement as a Lead button under #1485 without a separate product decision.

- Hot-patching production metadata outside the pack/deploy contract.

- Adding PingCAP-specific branches to generic record detail code.

## Further Notes

The likely current fix is smaller than the original #1485 comment implies, but the validation surface is broader than a one-line target-object change. A complete closure must prove the full user path: Lead layout panel, renderer registration, standard-action discovery, modal payload, flow write, and timeline read-back.

The design intentionally separates standard CRM behavior from PingCAP-specific overlay behavior. Log a Call and Email are standard CRM activity affordances and should eventually be owned by the official standard CRM app pack. Weekly Update is treated as the active PingCAP/UAT requirement for Lead in this PRD.

If "Activity Timeline standard action" becomes a recurring term across PRDs, add it to the root glossary as the canonical name for a metadata-owned Standard Action surfaced inside the CRM Activity Timeline panel.