@pega/custom-dx-components 26.1.11 → 26.1.12-alpha.0.2

package/src/ai/catalog/pconnect-assignment-lifecycle/cookbooks/resolve-or-ignore-duplicate.md

@@ -0,0 +1,47 @@
+---
+title: Resolve or ignore a detected duplicate case
+keywords: [duplicate case, duplicate detection, merge case, ignore duplicate]
+primary_methods: [ActionsApi.resolveDuplicateCase, ActionsApi.ignoreDuplicateCase]
+related: [relate-cases]
+---
+
+# Recipe: Resolve or ignore a detected duplicate case
+
+> Part of the [Assignment & Submission Lifecycle cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+During case creation, the application flags a possible duplicate and presents an assignment asking the user to either resolve it (treat the duplicate as handled) or ignore the warning and continue with the new case as-is.
+
+## Solution
+
+Uses [`ActionsApi`](../../references/pconnect-actions-api.md).
+
+```typescript
+async function resolveDuplicate(containerItemID) {
+  // Also finishes the assignment — do not call finishAssignment afterward.
+  await pConn.getActionsApi().resolveDuplicateCase(containerItemID);
+}
+
+async function ignoreDuplicateAndContinue(containerItemID) {
+  // Also finishes the assignment — do not call finishAssignment afterward.
+  await pConn.getActionsApi().ignoreDuplicateCase(containerItemID);
+}
+```
+
+If the user instead wants to keep both cases as distinct but linked records (rather than treating one as resolved), relate them explicitly instead of using either duplicate-decision method:
+
+```typescript
+const { addRelatedCases } = PCore.getRelatedCasesApi();
+await addRelatedCases(caseID, [{ caseID: duplicateCaseID }], context);
+```
+
+## Discussion
+
+**MUST NOT** call `finishAssignment` after `resolveDuplicateCase`/`ignoreDuplicateCase` — both already finish the assignment as part of recording the decision.
+
+**MUST** pick one path per duplicate warning — resolving/ignoring a duplicate is a distinct decision from relating two cases together via [`RelatedCasesApi`](../../pconnect-case-collaboration/cookbooks/relate-cases.md); do not call both for the same pair of cases unless the business process genuinely calls for the case to be both linked and marked resolved.
+
+## Related recipes
+
+- [Relate two cases together and confirm the relationship](../../pconnect-case-collaboration/cookbooks/relate-cases.md)

package/src/ai/catalog/pconnect-assignment-lifecycle/cookbooks/safe-case-deletion.md

@@ -0,0 +1,36 @@
+---
+title: Delete a case safely (create stage vs. an existing work object)
+keywords: [delete case, cancel case, remove work object, create stage]
+primary_methods: [ActionsApi.deleteCaseInCreateStage, ActionsApi.deleteWork]
+related: [modal-assignment-submit]
+---
+
+# Recipe: Delete a case safely (create stage vs. an existing work object)
+
+> Part of the [Assignment & Submission Lifecycle cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A case needs to be deleted, but which `ActionsApi` method to call depends on whether the case has already left its create stage.
+
+## Solution
+
+Uses [`ActionsApi`](../../references/pconnect-actions-api.md).
+
+```typescript
+if (isInCreateStage) {
+  // The case has no confirmed ID yet — use the create-stage-specific delete.
+  await pConn.getActionsApi().deleteCaseInCreateStage(containerItemID);
+} else {
+  // The case is already persisted — use deleteWork, which shows a confirmation dialog by default.
+  await pConn.getActionsApi().deleteWork(workId, caseTypeID);
+}
+```
+
+## Discussion
+
+**NEVER** call `deleteWork` on a case still in its create stage, or `deleteCaseInCreateStage` on an already-persisted case — there is no single `deleteCase()` method that handles both, and calling the wrong one for the case's stage is a common mistake.
+
+## Related recipes
+
+- [Open an assignment in a modal, edit, validate, submit, and close](./modal-assignment-submit.md)

package/src/ai/catalog/pconnect-case-collaboration/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: pconnect-case-collaboration
+description: 'Reference catalog and cookbook for PCore/PConnect APIs governing case collaboration and relationships — StakeholderUtils, CaseFollowerApi, RelatedCasesApi, TagUtils, FeedUtils, AttachmentUtils, and UserApi — with recipes for adding a participant and follower, relating two cases, tagging a case to find related cases, listing/updating participants, posting and managing feed messages, listing/editing/deleting attachments, and looking up operator details. Use when you need the exact signature for these APIs, or the correct order to call them to manage participants, relationships, feed messages, attachments, or tags on a case.'
+user-invocable: true
+argument-hint: 'Use when adding a participant/follower to a case, relating two cases, or tagging a case to find similar ones — for the exact StakeholderUtils/CaseFollowerApi/RelatedCasesApi/TagUtils signature, or the correct call order.'
+metadata:
+  verified-against: 'latest 26.x'
+---
+
+# Case Collaboration & Relationships — PCore/PConnect Skill
+
+This skill covers the PCore/PConnect APIs and recipes for **case collaboration and relationships**: participants, followers, related cases, and tags. It is one of the PCore/PConnect API skills — see the [skills index](../README.md) for the full method catalog, architecture primer, and the other five skills.
+
+## When to Use This Skill
+
+Load this skill when:
+
+- You need the exact parameters, return type, or purpose of a `StakeholderUtils`, `CaseFollowerApi`, `RelatedCasesApi`, or `TagUtils` method.
+- You're adding a user to a case in a role and/or as a follower.
+- You're linking two cases together, or applying an informal tag/label and browsing other cases sharing it.
+
+If your task is about the case's own submission/deletion lifecycle rather than its participants or relationships, see [pconnect-assignment-lifecycle](../pconnect-assignment-lifecycle/SKILL.md) instead.
+
+New to PCore/PConnect? Start with [Architecture at a Glance](../references/architecture-overview.md).
+
+## Key Reference Files
+
+| File                                                                                                                     | Class(es)                                                            | Obtained via          |
+| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | --------------------- |
+| [../references/pcore-case-collaboration-details.md](../references/pcore-case-collaboration-details.md)                   | `StakeholderUtils`, `CaseFollowerApi`, `RelatedCasesApi`, `TagUtils` | `PCore.get*()`        |
+| [../references/pcore-case-collaboration-genai.md](../references/pcore-case-collaboration-genai.md)                       | Stakeholders, tags, related cases (accessor-level)                   | `PCore.get*()`        |
+| [../references/pconnect-case-info-data-info-localization.md](../references/pconnect-case-info-data-info-localization.md) | `CaseInfo`                                                           | `pConn.getCaseInfo()` |
+
+See the [full reference index](../README.md) for every other PCore/PConnect method not directly related to this skill's topic.
+
+## Cookbooks
+
+Multi-method, ordering/cleanup recipes for this skill's topic live in [cookbooks/README.md](./cookbooks/README.md): adding a participant and follower, relating two cases, tagging a case to find related cases, listing/looking up/updating participants, posting and managing feed messages, listing/editing/deleting existing attachments, and looking up operator details.
+
+Use the reference files above for a single method's signature. Use the cookbook index when you need the **order** multiple methods should be called in to complete a task.
+
+For testing components that call these APIs, security considerations (sanitizing rendered feed/comment content), performance (avoiding redundant tag/related-case lookups), announcing feed/stakeholder updates accessibly, or troubleshooting a call that isn't behaving as documented, see [Cross-Cutting Best Practices](../best-practices/README.md).

package/src/ai/catalog/pconnect-case-collaboration/cookbooks/README.md

@@ -0,0 +1,36 @@
+---
+title: Case Collaboration & Relationships Cookbook — Recipe Index
+description: Multi-method recipes for participants, followers, related cases, and tags, indexed by symptom/keyword and primary method for AI/RAG retrieval.
+---
+
+# Cookbook: Case Collaboration & Relationships
+
+> Part of the [Case Collaboration & Relationships skill](../SKILL.md).
+
+Every file in [`../../references/`](../../references/) documents one method at a time. Each file in this folder shows how to **chain multiple documented methods together** to complete one common real-world task. Every recipe only uses methods already cataloged in `references/` — follow the links in each recipe for full signatures. Nothing here invents a new API; every call is a direct composition of already-documented methods.
+
+Each recipe is a single, self-contained file with:
+
+- YAML frontmatter (`keywords`, `primary_methods`, `related`) for structured/metadata search.
+- A **Problem** statement — what you're trying to accomplish, in plain language.
+- A **Solution** — the minimal correct code, linking to the individual reference files for each method used.
+- A **Discussion** — the ordering/cleanup/gotcha pitfall that makes this worth documenting as a recipe instead of assembling from scratch.
+- **Related recipes** — links to recipes that share a pattern (lifecycle, cleanup, error handling, etc.), including recipes in sibling skills.
+
+## Recipe Index
+
+Search by symptom or keyword before assembling a sequence of calls from scratch — there is a good chance the ordering/cleanup pitfalls have already been worked out below.
+
+| Recipe                                                                      | Keywords                                                                                     | Primary methods                       |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------- |
+| [Add a participant and follower](./participant-and-follower.md)             | stakeholder, participant, role, follower, notify a user                                      | `StakeholderUtils`, `CaseFollowerApi` |
+| [Relate two cases](./relate-cases.md)                                       | related case, link cases, case relationship                                                  | `RelatedCasesApi`                     |
+| [Tag a case and find related cases](./tag-case-and-find-related.md)         | tag, label, categorize case, find similar cases, tags landing page                           | `TagUtils`                            |
+| [List, look up, and update participants](./manage-case-participants.md)     | participants list, stakeholder list, team panel, participant roles, edit participant         | `StakeholderUtils`                    |
+| [Post, edit, and delete feed messages](./post-and-manage-feed.md)           | feed, pulse, comment, post message, discussion, reply                                        | `FeedUtils`                           |
+| [List, edit, and delete existing attachments](./manage-case-attachments.md) | attachment list, attachment panel, edit attachment, delete attachment, attachment categories | `AttachmentUtils`                     |
+| [Look up operator details](./look-up-user-details.md)                       | operator lookup, user profile, glimpse, avatar, display name                                 | `UserApi`                             |
+
+Use the individual reference files in [`../../references/`](../../references/) to look up a single method's exact signature. Use a recipe here when you need to know the **order** multiple methods should be called in to complete a task.
+
+As more cookbooks are added, add one file per recipe (not more content to an existing recipe file) and a row here — see any existing recipe file for the expected frontmatter/structure.

package/src/ai/catalog/pconnect-case-collaboration/cookbooks/look-up-user-details.md

@@ -0,0 +1,43 @@
+---
+title: Look up operator details to display in a participant or feed card
+keywords: [operator lookup, user profile, glimpse, avatar, display name]
+primary_methods: [UserApi.getOperatorDetails]
+related: [manage-case-participants]
+---
+
+# Recipe: Look up operator details to display in a participant or feed card
+
+> Part of the [Case Collaboration & Relationships cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A participant card, feed entry, or follower row only has a raw operator/user ID and needs to render a display name, role, and other profile details.
+
+## Solution
+
+Uses `UserApi` (via `PCore.getUserApi()`, see [pcore-case-collaboration-details.md](../../references/pcore-case-collaboration-details.md)).
+
+```typescript
+const { getOperatorDetails } = PCore.getUserApi();
+
+// The typedefs type the result as a bare `object`; at runtime it is an Axios-style response, so cast to read `.data`.
+const { data } = (await getOperatorDetails(operatorID)) as { data: Record<string, unknown> };
+// data typically includes display name and other glimpse/profile fields — render defensively,
+// since the exact shape depends on what the operator's profile has configured.
+```
+
+If `isBusinessID` is true for the caller's identifier type, pass it explicitly:
+
+```typescript
+const { data } = (await getOperatorDetails(businessID, true)) as { data: Record<string, unknown> };
+```
+
+## Discussion
+
+**SHOULD** cache the result per operator ID within a single view render (for example, a list of 30 feed entries from the same 3 authors) rather than calling `getOperatorDetails` once per row — the same operator's details do not change between rows in the same render pass.
+
+**MUST NOT** assume every field is present on `data` — profile completeness varies per operator; render a sensible fallback (for example, the raw ID) if a display name is missing.
+
+## Related recipes
+
+- [List, look up, and update a case's participants](./manage-case-participants.md)

package/src/ai/catalog/pconnect-case-collaboration/cookbooks/manage-case-attachments.md

@@ -0,0 +1,51 @@
+---
+title: List, edit, and delete a case's existing attachments
+keywords: [attachment list, attachment panel, edit attachment, delete attachment, attachment categories]
+primary_methods:
+  [
+    AttachmentUtils.getCaseAttachments,
+    AttachmentUtils.getAttachmentCategories,
+    AttachmentUtils.editAttachment,
+    AttachmentUtils.deleteAttachment
+  ]
+related: [post-and-manage-feed]
+---
+
+# Recipe: List, edit, and delete a case's existing attachments
+
+> Part of the [Case Collaboration & Relationships cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+An attachments panel needs to show every file already linked to a case, let the user recategorize or rename one, and remove one — this is a separate concern from the initial upload-and-link flow.
+
+## Solution
+
+Uses `AttachmentUtils` (via `PCore.getAttachmentUtils()`, see [pcore-case-collaboration-details.md](../../references/pcore-case-collaboration-details.md)).
+
+```typescript
+const { getCaseAttachments, getAttachmentCategories, editAttachment, deleteAttachment } = PCore.getAttachmentUtils();
+
+// Populate the panel's list, including thumbnails for image attachments.
+const attachments = await getCaseAttachments(caseID, context, true);
+
+// Populate a "category" dropdown before showing the edit form.
+const categories = await getAttachmentCategories(caseID, 'File', context);
+
+// Rename/recategorize an existing attachment.
+await editAttachment(attachmentID, { name: 'Signed contract.pdf', category: 'Legal' }, context);
+
+// Remove an attachment (confirm first — see the destructive-action confirmation recipe).
+await deleteAttachment(attachmentID, context);
+```
+
+## Discussion
+
+**SHOULD** gate `deleteAttachment` behind a confirmation prompt — see [Show a custom confirmation dialog before a destructive action](../../pconnect-assignment-lifecycle/cookbooks/confirm-before-destructive-action.md) — since it is irreversible from the component's perspective.
+
+**MUST** re-fetch with `getCaseAttachments` (or update local state directly) after `editAttachment`/`deleteAttachment` — neither returns the full refreshed attachment list.
+
+## Related recipes
+
+- [Upload a file, attach it to a case, and handle a failed upload](../../pconnect-assignment-lifecycle/cookbooks/attachment-upload.md)
+- [Show a custom confirmation dialog before a destructive action](../../pconnect-assignment-lifecycle/cookbooks/confirm-before-destructive-action.md)

package/src/ai/catalog/pconnect-case-collaboration/cookbooks/manage-case-participants.md

@@ -0,0 +1,52 @@
+---
+title: List, look up, and update a case's participants
+keywords: [participants list, stakeholder list, team panel, participant roles, edit participant]
+primary_methods:
+  [
+    StakeholderUtils.getParticipants,
+    StakeholderUtils.getParticipant,
+    StakeholderUtils.getParticipantRoles,
+    StakeholderUtils.updateParticipant
+  ]
+related: [participant-and-follower, look-up-user-details]
+---
+
+# Recipe: List, look up, and update a case's participants
+
+> Part of the [Case Collaboration & Relationships cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A "Team" panel needs to display every participant on a case, let the user drill into one participant's details, and save an edit to that participant — distinct from adding a brand-new participant.
+
+## Solution
+
+Uses `StakeholderUtils` (via `PCore.getStakeholderUtils()`, see [pcore-case-collaboration-details.md](../../references/pcore-case-collaboration-details.md)).
+
+```typescript
+const { getParticipants, getParticipant, getParticipantRoles, updateParticipant } = PCore.getStakeholderUtils();
+
+// Populate the panel's list.
+const participants = await getParticipants(caseID, pConn);
+
+// Fetch the roles configured for the case (for example, to offer role choices when adding a participant).
+const availableRoles = await getParticipantRoles(caseID, pConn);
+
+// Drill into one participant when the user selects a row.
+const participant = await getParticipant(caseID, participantID, pConn);
+
+// Save an edit to that participant. ParticipantData is { content: Record<string, string>; pageInstructions?: object[] },
+// so the edited participant fields go inside `content`.
+await updateParticipant(caseID, participantID, { content: { pyFirstName: 'Sam', pyLastName: 'Smith' } }, pConn);
+```
+
+## Discussion
+
+**SHOULD** re-fetch with `getParticipants` after `updateParticipant` if the list view needs to reflect the change immediately — `updateParticipant` does not return the full refreshed list.
+
+**MUST** call `getParticipantRoles` to populate role choices from configuration rather than hardcoding role IDs in the component — available roles are case-type-specific and can change without a component release.
+
+## Related recipes
+
+- [Add a participant to a case and make them a follower](./participant-and-follower.md)
+- [Look up operator details for display](./look-up-user-details.md)

package/src/ai/catalog/pconnect-case-collaboration/cookbooks/participant-and-follower.md

@@ -0,0 +1,40 @@
+---
+title: Add a participant to a case and make them a follower
+keywords: [stakeholder, participant, role, follower, notify a user]
+primary_methods: [StakeholderUtils.createParticipant, CaseFollowerApi.addCaseFollower]
+related: [relate-cases]
+---
+
+# Recipe: Add a participant to a case and make them a follower
+
+> Part of the [Case Collaboration & Relationships cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A user needs to be added to a case in a specific role, and separately opted in to update notifications.
+
+## Solution
+
+Uses `StakeholderUtils` and `CaseFollowerApi` (both via `PCore.get*()`, see [pcore-case-collaboration-details.md](../../references/pcore-case-collaboration-details.md)).
+
+```typescript
+const { createParticipant } = PCore.getStakeholderUtils();
+const { addCaseFollower } = PCore.getCaseFollowerApi();
+
+// participantData is { content: Record<string, string>; pageInstructions?: object[] },
+// for example { content: { pyFirstName: 'Sam', pyLastName: 'Smith', pyEmail1: 'sam.smith@example.com' } }.
+// createParticipant resolves to void — it does not return the new participant.
+await createParticipant(caseID, roleID, participantData, pConn);
+
+// Following is a separate concept from being a participant — add both if the user should get updates.
+// addCaseFollower takes an array of user IDs.
+await addCaseFollower(caseID, [userID], context);
+```
+
+## Discussion
+
+**MUST** call both APIs if the user needs both roles — creating a participant does NOT automatically make them a follower. They are independent concepts.
+
+## Related recipes
+
+- [Relate two cases together and confirm the relationship](./relate-cases.md)

package/src/ai/catalog/pconnect-case-collaboration/cookbooks/post-and-manage-feed.md

@@ -0,0 +1,50 @@
+---
+title: Post, edit, and delete messages on a case's feed
+keywords: [feed, pulse, comment, post message, discussion, reply]
+primary_methods: [FeedUtils.getFeeds, FeedUtils.postMessage, FeedUtils.editMessage, FeedUtils.deleteMessage]
+related: [manage-case-attachments]
+---
+
+# Recipe: Post, edit, and delete messages on a case's feed
+
+> Part of the [Case Collaboration & Relationships cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A discussion/feed panel needs to load a case's existing feed entries, let the user post a new message (and reply to an existing one), and let the message's own author edit or delete it afterward.
+
+## Solution
+
+Uses `FeedUtils` (via `PCore.getFeedUtils()`, see [pcore-case-collaboration-details.md](../../references/pcore-case-collaboration-details.md)).
+
+```typescript
+const { getFeeds, postMessage, editMessage, deleteMessage } = PCore.getFeedUtils();
+
+// Initial load.
+const feed = await getFeeds(context, feedID, feedClass, filters, cancelTokenSource, pConn);
+
+// Post a new top-level message.
+await postMessage(context, 'Reviewed and approved.', pConn);
+
+// Reply to an existing message.
+await postMessage(context, 'Confirming this is resolved.', pConn, undefined, true, undefined);
+
+// Author-only edit.
+await editMessage({ messageID, message: 'Reviewed and approved — see attached notes.', pConn });
+
+// Author-only delete (void return — re-fetch or optimistically remove from local state).
+deleteMessage(messageID, false, undefined, pConn);
+```
+
+To load more/older entries in a paginated feed, call `getFeeds` again with `isLoadMore: true` rather than re-requesting from the beginning.
+
+## Discussion
+
+**MUST NOT** assume `deleteMessage` returns the updated feed — it returns `void`. Either re-call `getFeeds` or remove the message from local state directly after a successful call.
+
+**SHOULD** pass a `cancelTokenSource` to `getFeeds` so an in-flight feed request can be canceled if the user navigates away before it resolves (see [Cancel Requests That Are No Longer Needed](../../best-practices/performance-and-efficiency.md#cancel-requests-that-are-no-longer-needed)).
+
+## Related recipes
+
+- [Upload a file, attach it to a case, and handle a failed upload](../../pconnect-assignment-lifecycle/cookbooks/attachment-upload.md)
+- [List, look up, and update a case's participants](./manage-case-participants.md)

package/src/ai/catalog/pconnect-case-collaboration/cookbooks/relate-cases.md

@@ -0,0 +1,35 @@
+---
+title: Relate two cases together and confirm the relationship
+keywords: [related case, link cases, case relationship]
+primary_methods: [RelatedCasesApi.addRelatedCases, RelatedCasesApi.getRelatedCases]
+related: [participant-and-follower]
+---
+
+# Recipe: Relate two cases together and confirm the relationship
+
+> Part of the [Case Collaboration & Relationships cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+Two existing cases need to be linked as related cases, and the UI needs to refresh to show the new relationship.
+
+## Solution
+
+Uses `RelatedCasesApi` (via `PCore.getRelatedCasesApi()`, see [pcore-case-collaboration-details.md](../../references/pcore-case-collaboration-details.md)).
+
+```typescript
+const { addRelatedCases, getRelatedCases } = PCore.getRelatedCasesApi();
+
+await addRelatedCases(caseID, [{ caseID: relatedCaseID }], context);
+
+// Re-fetch to confirm the relationship was recorded and to refresh any related-cases widget.
+const relatedCases = await getRelatedCases(caseID, context);
+```
+
+## Discussion
+
+**MUST** re-fetch with `getRelatedCases` if a widget needs to reflect the new relationship immediately — `addRelatedCases` does NOT return the updated list itself.
+
+## Related recipes
+
+- [Add a participant to a case and make them a follower](./participant-and-follower.md)

package/src/ai/catalog/pconnect-case-collaboration/cookbooks/tag-case-and-find-related.md

@@ -0,0 +1,44 @@
+---
+title: Tag a case and browse other cases sharing that tag
+keywords: [tag, label, categorize case, find similar cases, tags landing page]
+primary_methods: [TagUtils.postTags, TagUtils.getTags, TagUtils.getTaggedCases, TagUtils.removeTag]
+related: [relate-cases, participant-and-follower]
+---
+
+# Recipe: Tag a case and browse other cases sharing that tag
+
+> Part of the [Case Collaboration & Relationships cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A user wants to apply an informal, ad-hoc label to a case (for example "Escalated") and later browse other cases that share tags with it — without creating a formal case relationship.
+
+## Solution
+
+Uses `TagUtils` (via `PCore.getTagUtils()`, see [pcore-case-collaboration-details.md](../../references/pcore-case-collaboration-details.md)).
+
+```typescript
+const { getTags, postTags, getTaggedCases, removeTag } = PCore.getTagUtils();
+
+await postTags(caseID, [{ Name: 'Escalated' }], pConn);
+
+// Re-fetch to get the newly-created tag's own ID — postTags does not return it.
+const tags = await getTags(caseID, pConn);
+
+const relatedByTag = await getTaggedCases(caseID, pConn);
+
+async function onRemoveTag(tagID: string) {
+  await removeTag(caseID, tagID, pConn);
+}
+```
+
+## Discussion
+
+**MUST** call `getTags` again after `postTags` if you need to reference the tag you just added (for example, to render an immediate "remove" button next to it) — `removeTag` needs the tag's own ID, not its name, and `postTags` does NOT return the created tag's ID.
+
+Tags are a distinct, lighter-weight concept from a formal case relationship: use this recipe for informal cross-cutting labels a user assigns themselves, and use [Relate two cases](./relate-cases.md) when the relationship is a structured, first-class link between two specific cases.
+
+## Related recipes
+
+- [Relate two cases](./relate-cases.md)
+- [Add a participant and follower](./participant-and-follower.md)

package/src/ai/catalog/pconnect-data-subscriptions/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: pconnect-data-subscriptions
+description: 'Reference catalog and cookbook for PCore/PConnect APIs governing data subscriptions and real-time updates — DataPageUtils, PubSubUtils, Events, MessagingServiceManager, and DataApiUtils — with recipes for subscribing to a data page with cleanup, publish/subscribe between unrelated components, subscribing to real-time server-pushed case updates, publishing a custom application-wide event, force-refreshing a stale cached data page, and querying a paginated/filterable list data view. Use when you need the exact signature for these APIs, or the correct subscribe/unsubscribe sequence to avoid orphaned handlers.'
+user-invocable: true
+argument-hint: 'Use when subscribing to a data page, publishing/subscribing between components, or reacting to real-time server-pushed case updates — for the exact DataPageUtils/PubSubUtils/MessagingServiceManager signature, or the correct subscribe/unsubscribe order.'
+metadata:
+  verified-against: 'latest 26.x'
+---
+
+# Data Subscriptions & Real-time — PCore/PConnect Skill
+
+This skill covers the PCore/PConnect APIs and recipes for **data subscriptions and real-time updates**: data page subscriptions, application-wide pub/sub between unrelated components, and server-pushed real-time case updates. It is one of the PCore/PConnect API skills — see the [skills index](../README.md) for the full method catalog, architecture primer, and the other five skills.
+
+## When to Use This Skill
+
+Load this skill when:
+
+- You need the exact parameters, return type, or purpose of a `DataPageUtils`, `PubSubUtils`, `Events`, or `MessagingServiceManager` method.
+- You're subscribing a component to a data page, an application-wide event, or a server-pushed WebSocket message, and need to avoid an orphaned subscription after unmount.
+- You're unsure whether to use `PubSubUtils` (same-tab, locally published events) or `MessagingServiceManager` (server-pushed, cross-session updates).
+
+If your task is about cascading one field from another (which also uses a subscribe/unsubscribe pattern, via `CascadeManager`), see [pconnect-forms-and-fields](../pconnect-forms-and-fields/SKILL.md) instead.
+
+New to PCore/PConnect? Start with [Architecture at a Glance](../references/architecture-overview.md).
+
+## Key Reference Files
+
+| File                                                                                     | Class(es)                                                            | Obtained via   |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------- |
+| [../references/pcore-rest-data-details.md](../references/pcore-rest-data-details.md)     | `DataPageUtils`, `DataApi`, `DataApiUtils`                           | `PCore.get*()` |
+| [../references/pcore-messaging-details.md](../references/pcore-messaging-details.md)     | `PubSubUtils`, `Events`, `MessagingServiceManager`, `MessageManager` | `PCore.get*()` |
+| [../references/pcore-rest-data-messaging.md](../references/pcore-rest-data-messaging.md) | REST client, data pages/views, cascade, messaging, refresh           | `PCore.get*()` |
+
+See the [full reference index](../README.md) for every other PCore/PConnect method not directly related to this skill's topic.
+
+## Cookbooks
+
+Multi-method, ordering/cleanup recipes for this skill's topic live in [cookbooks/README.md](./cookbooks/README.md): subscribing to a data page with cleanup, publish/subscribe between unrelated components, real-time server-pushed case update subscriptions, publishing a custom application-wide event, force-refreshing a stale cached data page, and querying a paginated/filterable list data view.
+
+Use the reference files above for a single method's signature. Use the cookbook index when you need the **order** multiple methods should be called in to complete a task.
+
+For testing subscribe/unsubscribe behavior, security considerations, performance (avoiding redundant subscriptions, canceling stale requests), resiliency when offline, accessibly announcing server-pushed updates, or troubleshooting a subscription that keeps firing after unmount, see [Cross-Cutting Best Practices](../best-practices/README.md).

package/src/ai/catalog/pconnect-data-subscriptions/cookbooks/README.md

@@ -0,0 +1,35 @@
+---
+title: Data Subscriptions & Real-time Cookbook — Recipe Index
+description: Multi-method recipes for data page subscriptions, pub/sub, and real-time case updates, indexed by symptom/keyword and primary method for AI/RAG retrieval.
+---
+
+# Cookbook: Data Subscriptions & Real-time
+
+> Part of the [Data Subscriptions & Real-time skill](../SKILL.md).
+
+Every file in [`../../references/`](../../references/) documents one method at a time. Each file in this folder shows how to **chain multiple documented methods together** to complete one common real-world task. Every recipe only uses methods already cataloged in `references/` — follow the links in each recipe for full signatures. Nothing here invents a new API; every call is a direct composition of already-documented methods.
+
+Each recipe is a single, self-contained file with:
+
+- YAML frontmatter (`keywords`, `primary_methods`, `related`) for structured/metadata search.
+- A **Problem** statement — what you're trying to accomplish, in plain language.
+- A **Solution** — the minimal correct code, linking to the individual reference files for each method used.
+- A **Discussion** — the ordering/cleanup/gotcha pitfall that makes this worth documenting as a recipe instead of assembling from scratch.
+- **Related recipes** — links to recipes that share a pattern (lifecycle, cleanup, error handling, etc.), including recipes in sibling skills.
+
+## Recipe Index
+
+Search by symptom or keyword before assembling a sequence of calls from scratch — there is a good chance the ordering/cleanup pitfalls have already been worked out below.
+
+| Recipe                                                                         | Keywords                                                                       | Primary methods           |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------- |
+| [Data page subscription cleanup](./data-page-subscription-cleanup.md)          | data page, polling, server push, memory leak, unmount, useEffect cleanup       | `DataPageUtils`           |
+| [Pub/sub cleanup](./pubsub-cleanup.md)                                         | event bus, publish, subscribe, cross-component communication, orphaned handler | `PubSubUtils`, `Events`   |
+| [Real-time case update subscription](./realtime-case-subscription.md)          | WebSocket, server push, real-time update, live case status, messaging service  | `MessagingServiceManager` |
+| [Publish a custom application-wide event](./publish-and-subscribe-events.md)   | event bus, publish, custom event, cross-component communication, broadcast     | `PubSubUtils`             |
+| [Force-refresh a stale cached data page](./refresh-and-update-data.md)         | refresh, stale cache, cache invalidation, force reload, refresh button         | `DataPageUtils`           |
+| [Query a paginated, filterable list data view](./query-paginated-list-data.md) | list query, pagination, filter, sort, data view, search results                | `DataApiUtils`            |
+
+Use the individual reference files in [`../../references/`](../../references/) to look up a single method's exact signature. Use a recipe here when you need to know the **order** multiple methods should be called in to complete a task.
+
+As more cookbooks are added, add one file per recipe (not more content to an existing recipe file) and a row here — see any existing recipe file for the expected frontmatter/structure.

package/src/ai/catalog/pconnect-data-subscriptions/cookbooks/data-page-subscription-cleanup.md

@@ -0,0 +1,41 @@
+---
+title: Subscribe to a data page and clean up on unmount
+keywords: [data page, polling, server push, memory leak, unmount, useEffect cleanup]
+primary_methods: [DataPageUtils.subscribeToDataPageUpdates, DataPageUtils.unsubscribeToDataPageUpdates]
+related: [pubsub-cleanup, cascading-dependent-fields, autosave-tracking]
+---
+
+# Recipe: Subscribe to a data page and clean up on unmount
+
+> Part of the [Data Subscriptions & Real-time cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A component needs to react to server-pushed updates to a data page, without leaking a subscription after the component unmounts.
+
+## Solution
+
+Uses `PCore.getDataPageUtils()` (see [pcore-rest-data-details.md](../../references/pcore-rest-data-details.md)) inside a component lifecycle.
+
+```typescript
+useEffect(() => {
+  const subscriptionId = 'my-component-subscription';
+
+  PCore.getDataPageUtils().subscribeToDataPageUpdates(subscriptionId, onDataPageUpdate, 'D_Cases');
+
+  return () => {
+    // Always unsubscribe on unmount — an orphaned subscription keeps firing after the component is gone.
+    PCore.getDataPageUtils().unsubscribeToDataPageUpdates(subscriptionId, 'D_Cases');
+  };
+}, []);
+```
+
+## Discussion
+
+**MUST** use the exact same `subscriptionId` and `dataPageName` pair for both subscribe and unsubscribe. **NEVER** let them drift apart — a mismatch makes the unsubscribe silently no-op, and the original callback keeps firing.
+
+## Related recipes
+
+- [Publish/subscribe between unrelated components, with cleanup](./pubsub-cleanup.md)
+- [Register cascading/dependent fields and clean them up](../../pconnect-forms-and-fields/cookbooks/cascading-dependent-fields.md)
+- [Track autosave status while editing a form](../../pconnect-forms-and-fields/cookbooks/autosave-tracking.md)