Fill gaps from assistant conversations: nested hierarchy modeling

async-collaboration/activity/overview.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Activity Logs"
 sidebarTitle: "Overview"
+description: "Track every collaboration event—comments, reactions, recordings, CRDT edits, and custom app events—in one real-time, filterable audit timeline."
 ---
 
 Every collaboration event in your app, every comment, approval, edit, and review, generates a question someone eventually asks: "Who did what, and when?" Activity Logs gives you a complete, real-time record of everything that happens across your product.
@@ -47,7 +48,9 @@ This lets you merge application-level events (deployments, escalations, status t
 
 - **Org-wide feed:** No filters. Returns all activity across every document in the organization. Useful for admin dashboards and team lead overviews.
 - **Per-document timeline:** Filter by `documentId` to show the full history of a single document, from first draft to final approval. Useful for inline review panels and document sidebars.
+- **Cross-document rollup:** Pass multiple IDs in `documentIds` to merge the timelines of several Documents into one feed — useful for hierarchies like `Folder → Documents` or `Parent entity → Child entities`, where each child is its own Document. Resolve the descendant Documents with the [Get Folders REST API](/api-reference/rest-apis/v2/folders/get-folders) (`maxDepth` returns nested subfolders) and pass the collected IDs to `getAllActivities()`.
 - **Feature-scoped feed:** Filter by feature type (e.g., only Comments or only CRDT edits) to reduce noise for specific views.
+- **Custom hierarchy metadata:** The subscription config does not support filtering by arbitrary custom fields. To roll up or filter by your own hierarchy fields (`entityType`, `parentEntityId`, etc.), attach them via `entityData` / `entityTargetData` on [`createActivity()`](/api-reference/sdk/api/api-methods#createactivity) and filter client-side after subscribing.
 
 ## Immutability
 

key-concepts/overview.mdx

@@ -1,3 +1,7 @@
+---
+title: "Key concepts: Organizations, Folders, Documents, Locations"
+description: "Understand how Velt models collaborative data with Organizations, Folders, Documents, Locations, Users, and access control across your product."
+---
 
 ## Overview
 
@@ -843,11 +847,22 @@ For instance:
 - Any user with access to the document will have access to all locations in the document.
 - Access controls cannot be set at the location level.
 - Locations automatically generate location groups in the sidebar and organizes the comments within the group.
+- Locations are **flat** — a location cannot contain another location. The `id` and `locationName` fields are scoped to a single document and are not hierarchical.
 - The location object has these fields:
   - `id` (optional when `locationName` is set): A unique string or numeric identifier. An id of `0` is valid and takes precedence over `locationName`.
   - `locationName` (optional when `id` is set): A non-empty, human-readable name displayed in Velt components like `VeltCommentsSidebar`. It also identifies the location when `id` is omitted.
   - You can add any number of custom fields to the location object.
 
+#### Modeling nested hierarchies
+
+Because Locations are flat, model nested product hierarchies (for example, `Style → Variant → SKU → Price`) using the resources higher in the tree:
+
+- **Folders and subfolders** carry the parent tree. [Folders can contain subfolders](#folders), and access cascades down the folder tree. Use one folder per parent entity (for example, one folder per Style, containing a subfolder per Variant).
+- **Documents** represent the leaf collaborative surface (for example, one Document per SKU or per Sample Request). Each Document has its own activity timeline.
+- **Locations** partition data within a single Document. Represent sibling sections of the same entity (for example, `prices`, `samples`, `variant-summary`) as separate Locations on that Document. Add your own hierarchy fields (`entityType`, `entityId`, `parentEntityType`, `parentEntityId`) as custom fields on the location object so your app can filter comments and activity by them client-side.
+- **Roll-up queries** across the hierarchy work by passing multiple `documentIds` to [`getAllActivities()`](/async-collaboration/activity/setup#3-subscribe-to-activities) (or the [Get Activities REST API](/api-reference/rest-apis/v2/activities/get-activities)). To get every Document under a Folder, resolve the tree with the [Get Folders REST API](/api-reference/rest-apis/v2/folders/get-folders) using `maxDepth`. Collect the descendant `documentIds` and pass that list to your activity subscription.
+- **Custom activity records** created via [`createActivity()`](/api-reference/sdk/api/api-methods#createactivity) accept `entityData` and `entityTargetData` — use these to attach your own hierarchy metadata (parent IDs, entity type, etc.) to non-Velt events so the same rollups work across custom and Velt-generated activity.
+
 ### APIs
 
 ### Frontend APIs