velt-js · yoen-velt · May 19, 2026
diff --git a/.claude/logs/agent-2-planning-5.0.2-beta.29.md b/.claude/logs/agent-2-planning-5.0.2-beta.29.md
@@ -0,0 +1,66 @@
+# Release Update Plan for v5.0.2-beta.29
+
+## Overview
+- Release Type: Patch
+- Key Changes: 7 bug fixes across Comments and Documents features
+- Breaking Changes: No
+
+## Per-Item Analysis
+
+### Item 1 — [Comments] Thread-card action buttons disappearing
+- Internal fix in `CommentDialogOptionsDropdownComponent` and `CommentDialogThreadCardSeenDropdownComponent` via `CommentDialogActionService.threadCardDropdownOpen()`.
+- No API change, no new types, no UI surface change.
+- **No docs updates needed.**
+
+### Item 2 — [Comments] Visibility dropdown not editable when composing
+- `isVisibilityDropdownAuthor()` helper added internally in `VisibilityBannerDropdown` components.
+- No API change, no new public method or type.
+- **No docs updates needed.**
+
+### Item 3 — [Comments] Visibility banner not appearing in composer
+- `registerTempContext` merge bug fix; internal only.
+- No API change.
+- **No docs updates needed.**
+
+### Item 4 — [Comments] Page-mode comment visibility not persisted
+- `savePageComment` now forwards `_setAccessFields` via `buildPageCommentContext()`. Internal only.
+- No API change.
+- **No docs updates needed.**
+
+### Item 5 — [Documents] Spurious resetServicesCache() on setDocuments() refresh
+- `DocService.setDocumentsImpl` comparison fix; `getOptionsFromDocumentPaths()` internal mapping fix.
+- No API change.
+- **No docs updates needed.**
+
+### Item 6 — [Documents] Documents with folderId not attached to folder on creation
+- `PermissionQuery.resource` gains optional `parentFolderId?: string` field (additive).
+- `PermissionQuery` IS documented user-facing:
+  - `/api-reference/sdk/models/data-models.mdx` line 5919 — inline type for `resource` field
+  - `/key-concepts/overview.mdx` line 1473 — links to PermissionQuery anchor (no inline type, no update needed)
+- **One doc update required.**
+
+### Item 7 — [Comments] Assign-user overlay mispositioned in wireframe-injected DOM
+- `resolveOverlayOrigin()` internal positioning fix; walks ancestor chain past `display:contents`.
+- No new wireframe component, no new primitive, no API change.
+- **No docs updates needed.**
+
+---
+
+## Areas Requiring Updates
+
+### 1. Data Models — PermissionQuery.resource type
+- File: `/Users/yoenzhang/Downloads/docs/api-reference/sdk/models/data-models.mdx`
+- Line: 5919
+- Change: Add `parentFolderId?: string` to the inline type definition of the `resource` property, and update the Description column to note it is present when the document was created with a `folderId` and is used to attach the document to its folder.
+- Priority: Medium
+
+## Implementation Sequence
+1. Update `PermissionQuery.resource` inline type in `data-models.mdx` to include `parentFolderId?: string` — small, isolated edit.
+
+## Quality Checklist
+- [x] All new types added to data-models.mdx (parentFolderId on PermissionQuery.resource)
+- [x] No new API methods — api-methods.mdx not touched
+- [x] No new UI customization wireframes or primitives
+- [x] No breaking changes — upgrade-guide.mdx not touched
+- [x] Log file written to `.claude/logs/agent-2-planning-5.0.2-beta.29.md`
+- [x] Items 1–5 and 7 explicitly confirmed as no-docs-needed
diff --git a/.claude/logs/agent-7-qa-v5.0.2-beta.29.md b/.claude/logs/agent-7-qa-v5.0.2-beta.29.md
@@ -0,0 +1,36 @@
+## QA Summary for v5.0.2-beta.29
+
+### Issues Found: 0
+
+All checks passed. No defects found.
+
+### Verification Results
+
+1. **parentFolderId in PermissionQuery (data-models.mdx line 5919)**
+   - Appears exactly once in the `PermissionQuery.resource` inline type definition.
+   - The other occurrences of `parentFolderId` in data-models.mdx (lines 4267, 7076, 7914, 7921, 8495, 9421) are in unrelated sections (`FolderMetadata`, REST API payloads, code examples) — no collision or confusion.
+   - Description is accurate: field is marked optional (`?: string`), explains it is set when `setDocuments()` is called with a `folderId` option.
+
+2. **Changelog entry (sdk-changelog.mdx lines 13–31)**
+   - Exactly 7 bug-fix bullets present, matching Agent-1 scope.
+   - Only `### Bug Fixes` section — no `Breaking Changes`, no `New Features`, no `Improvements`.
+   - MDX tag balance: 1 `<Update>` open, 1 `</Update>` close.
+   - No stray tags, no odd-backtick lines, no broken inline code spans.
+   - `PermissionQuery.resource` reference in bullet 6 is correctly prose (not a link — acceptable, the type name is self-explanatory and the full link is in data-models.mdx).
+
+3. **Cross-doc anchor integrity**
+   - `#permissionquery` anchor resolves to `#### PermissionQuery` at line 5910 of data-models.mdx.
+   - Existing reference in key-concepts/overview.mdx line 1473 links to `#permissionquery` — still valid, no slug change.
+   - `setDocuments()` references in changelog (prior beta entries) link to `#setdocuments` which resolves to `#### setDocuments()` at api-methods.mdx line 3363 — unaffected.
+
+4. **Term drift scan (PermissionQuery, parentFolderId, setDocuments, folderId)**
+   - `PermissionQuery` appears in: data-models.mdx (definition), key-concepts/overview.mdx (linked reference), sdk-changelog.mdx (changelog prose). All consistent.
+   - `parentFolderId` appears in: data-models.mdx (FolderMetadata row, PermissionQuery row, REST API docs, Python SDK examples), sdk-changelog.mdx (changelog prose). All uses are accurate and contextually correct.
+   - `setDocuments` casing is consistent across all files (`setDocuments()` in prose, `setDocuments` in anchors).
+   - `folderId` usage in changelog bullet 6 correctly refers to the `SetDocumentsRequestOptions.folderId` option — no rename or casing drift.
+
+### Summary
+- Files corrected: 0
+- Critical issues: 0
+- Terminology alignments needed: 0
+- Pipeline status: Clean — Agent-1 ready for next release note
diff --git a/api-reference/sdk/models/data-models.mdx b/api-reference/sdk/models/data-models.mdx
@@ -5916,7 +5916,7 @@ Request structure for permission queries sent to the Permission Provider.
 | Property   | Type                                                                                                                                                                                  | Required | Description                                                                                                                                                                                                                                                                                                                                                                |
 | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `userId`   | `string`                                                                                                                                                                              | Yes      | ID of the user requesting access to the resource.                                                                                                                                                                                                                                                                                                                          |
-| `resource` | `{ type:` [PermissionResourceType](#permissionresourcetype)`; id: string; source:` [PermissionSource](#permissionsource)`; organizationId: string; context?:` [Context](#context) `}` | Yes      | Resource the user is requesting access to. The `type` uses [`PermissionResourceType`](#permissionresourcetype) enum. The `source` field identifies which SDK method triggered the permission check. The optional `context` field is present only when `isContextEnabled: true` and contains context values set during setDocuments. Includes `organizationId` for context. |
+| `resource` | `{ type:` [PermissionResourceType](#permissionresourcetype)`; id: string; source:` [PermissionSource](#permissionsource)`; organizationId: string; context?:` [Context](#context)`; parentFolderId?: string }` | Yes      | Resource the user is requesting access to. The `type` uses [`PermissionResourceType`](#permissionresourcetype) enum. The `source` field identifies which SDK method triggered the permission check. The optional `context` field is present only when `isContextEnabled: true` and contains context values set during setDocuments. Includes `organizationId` for context. The optional `parentFolderId` field is set when the document was created via `setDocuments()` with a `folderId` option — it forwards the folder context through the permission request so the document is created and attached to its parent folder. |
 
 #### PermissionResult
 

diff --git a/release-notes/version-5/sdk-changelog.mdx b/release-notes/version-5/sdk-changelog.mdx
@@ -10,6 +10,26 @@ description: Release Notes of changes added to the core Velt SDK
 - `@veltdev/sdk`
 - `velt-py`
 
+<Update label="5.0.2-beta.29" description="May 15, 2026">
+
+### Bug Fixes
+
+- [**Comments**]: Thread-card action buttons (like, react, options) no longer disappear when the options dropdown (⋯ menu) or the "seen by" dropdown is open. Both dropdowns now route their open/close state through `CommentDialogActionService.threadCardDropdownOpen()`, keeping the actions visible while either dropdown is active.
+
+- [**Comments**]: The visibility dropdown in the comment composer is now editable when composing a new comment. Previously, the `isAuthor` check required a known `from.userId`, which is only stamped at submit time — so new comments always rendered the dropdown as read-only. The caret trigger icon is also correctly shown for new comments.
+
+- [**Comments**]: The visibility banner now appears in the comment composer when `enableVisibilityOptionDropdown()` has been called. Previously, default `ComponentConfig` values overwrote the live service flags during composer initialization, preventing the banner from rendering.
+
+- [**Comments**]: Page-mode comments now respect the visibility setting chosen in the dropdown at submit time. Previously, the page-mode save path did not forward the `_setAccessFields` tokens, causing all page-mode comments to be saved as public regardless of the selected visibility.
+
+- [**Documents**]: `setDocuments()` no longer triggers `resetServicesCache()` on routine same-org document refreshes. The organization-change comparison now correctly uses `clientOrganizationId` on both sides, so cache resets only occur when the organization genuinely changes.
+
+- [**Documents**]: Documents included in a `setDocuments()` call with a `folderId` option are now created with the correct folder context when they do not yet exist in the database. The `PermissionQuery.resource` interface gains an optional `parentFolderId?: string` field (additive, no breaking change).
+
+- [**Comments**]: The assign-user (@assign) dropdown overlay is now correctly positioned when the comment dialog is inside wireframe-injected DOM. The overlay origin resolver now walks up the ancestor chain to find the first element with a non-zero bounding rect, bypassing consecutive `display: contents` ancestors introduced by wireframes.
+
+</Update>
+
 <Update label="5.0.2-beta.22" description="April 28, 2026">
 
 ### New Features