v5.0.3 (#230)

* v5.0.3

* save

---------

Co-authored-by: Rakesh <rakesh@snippyly.com>

Author: yoen-velt

.claude/logs/agent-2-planning-5.0.3.md

@@ -0,0 +1,79 @@
+# Release Update Plan for v5.0.3
+
+## Overview
+- Release Type: Minor (fully additive; no breaking changes)
+- Key Changes: Multi-org "Selected Teams" comment visibility — `organizationIds?: string[]` on `CommentVisibilityConfig`; `PrivateModeConfig` Omit widened; new `contactElement.updateOrgList()` API (+ `OrgContact`, `UpdateOrgListConfig` types); new `OrgPicker` primitive + matching wireframe component.
+- Breaking Changes: No. No `upgrade-guide.mdx` edit. Omit change is additive (a previously-omitted field is now accepted).
+- docs.json: No change. OrgPicker/updateOrgList land on existing pages already in nav (docs.json L399–401). Confirmed.
+- Bug fixes (7): Behavioral visibility-correctness fixes. Covered by the changelog; no separate doc-API edits. Confirmed.
+
+## Areas Requiring Updates
+
+### 1. Data Models — Agent-3 — Priority: High
+File: `api-reference/sdk/models/data-models.mdx`
+- `#### CommentVisibilityConfig` table (L271–276): add row `organizationIds` | `string[]` | No | "Target multiple organizations when `type` is `'organizationPrivate'`. Merged and de-duplicated with `organizationId`." Keep `organizationId` row.
+- `#### PrivateModeConfig` (L282–294): change Omit to `Omit<CommentVisibilityConfig, 'annotationId'>` (drop `| 'organizationId'`); update the prose at L282 (it currently says "excludes `annotationId` and `organizationId`"); add `organizationId` and `organizationIds` rows to the props table.
+- New types: add `OrgContact` (`id: string`; `name?: string`) and `UpdateOrgListConfig` (`orgList: OrgContact[]`). Place near contact/visibility models; mirror existing table format (Property | Type | Required | Description).
+
+### 2. API Methods — Agent-3 — Priority: High
+File: `api-reference/sdk/api/api-methods.mdx`
+- New `#### updateOrgList()` immediately after `updateContactList()` (ends L676) / before `updateContactListScopeForOrganizationUsers()` (L678). Mirror the `updateContactList()` block format:
+  - Params: [`config: UpdateOrgListConfig`](/api-reference/sdk/models/data-models#updateorglistconfig)
+  - Returns: `void`; React Hook: `useContactUtils()`
+  - Note full-replace semantics (every call replaces the list; `{ orgList: [] }` clears); exposed on `contactElement` only.
+- `updateVisibility()` (L138–143) and `enablePrivateMode()` (L145–150): add a one-line `organizationIds: string[]` note (multi-org target; merged + de-duped with `organizationId`).
+- `addCommentAnnotation()` (L9): note `visibility` accepts `organizationIds`.
+File: `async-collaboration/comments/customize-behavior.mdx`
+- `updateVisibility` full section (L2884–2964): add `organizationIds` to the `CommentVisibilityConfig` param bullets (after L2892) and add an `organizationPrivate` example using `organizationIds: ['org-1','org-2']` in BOTH tabs (React L2898+, Other Frameworks L2932+).
+- `enablePrivateMode` full section: add the same `organizationIds` mention/example.
+- Optional: add a brief `updateOrgList` mention near the `updateContactList` full section (L2115) if Agent-3 deems the picker needs a behavior anchor; otherwise the api-methods entry suffices.
+
+### 4a. UI Customization — Wireframe — Agent-4 — Priority: Medium
+The wireframe `OrgPicker` is the team analogue of `UserPicker`. Mirror UserPicker's structure (container + Search/Header/Item sub-tree) ONLY IF the SDK ships those sub-parts; the release spec describes the picker as a single component analogue, so default to the container component plus the same sub-children pattern as UserPicker and confirm against the SDK. At minimum add the container entry.
+- File: `ui-customization/features/async/comments/comment-dialog-structure.mdx`
+  - React tree: in `##### VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content` (L270–272), add `- VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.OrgPicker` directly after the `...Content.UserPicker` line (L272). Add its own `#####` subsection after the UserPicker subsection (after L294) if sub-children are documented, mirroring L278–294.
+  - HTML tree: after the user-picker wireframe block (L578, L584–600), add `velt-comment-dialog-visibility-banner-dropdown-content-org-picker-wireframe` entry mirroring the user-picker entry exactly.
+- File: `ui-customization/features/async/comments/comment-dialog/wireframes.mdx`
+  - In `#### Content (Visibility Banner Dropdown)` (L4264–4293): add `<VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.OrgPicker />` (React, after L4275) and `<velt-comment-dialog-visibility-banner-dropdown-content-org-picker-wireframe>` (HTML, after L4288).
+  - Add a new `##### **OrgPicker (Visibility Banner Dropdown Content)**` subsection immediately after the UserPicker subsection (UserPicker starts L4360; its block ends ~L4591). Mirror the UserPicker subsection format exactly: bold h5 title, React/Other Frameworks `<Tabs>`, `<VeltWireframe>` wrapper. If documenting sub-children, mirror UserPicker's `**Search/Header/Item ...**` bold sub-entries with `(Visibility Banner Dropdown Content OrgPicker)` parenthetical suffixes.
+- File: `ui-customization/features/async/comments/comment-dialog/wireframe-variables.mdx`
+  - Grep for the user-picker wireframe element here; add the analogous `OrgPicker` wireframe-variable entry only if UserPicker has one (mirror it). If UserPicker is absent from this file, no edit.
+
+### 4b. UI Customization — Primitive — Agent-5 — Priority: Medium
+- File: `ui-customization/features/async/comments/comment-dialog/primitives.mdx`
+- New entry `### VeltCommentDialogVisibilityBannerDropdownContentOrgPicker` placed immediately after the UserPicker container entry `### VeltCommentDialogVisibilityBannerDropdownContentUserPicker` (L3545–3564) — i.e. insert after L3564 / before the `...UserPickerSearch` entry (L3568).
+- Mirror the UserPicker container entry exactly (L3545–3564):
+  - One-line description (team analogue): "Team picker for selecting specific organizations/teams when visibility is set to `selected-teams`."
+  - React tab: `<VeltCommentDialogVisibilityBannerDropdownContentOrgPicker annotationId="abc123" />`
+  - Other Frameworks tab: `<velt-comment-dialog-visibility-banner-dropdown-content-org-picker annotation-id="abc123"></velt-comment-dialog-visibility-banner-dropdown-content-org-picker>`
+  - Props/Attributes: "Common inputs only (see [Common Inputs](#common-inputs) section)." — the primitive's three props (`annotationId`, `defaultCondition`, `inlineCommentSectionMode`) are already the documented Common Inputs (L62–70). Do NOT add a separate props table; match the sibling.
+- Primitives belong ONLY here, NEVER in a wireframes/components page.
+
+## Name-Mirror Spec (QA will diff exact strings)
+| Surface | React / dotted name | HTML element |
+| --- | --- | --- |
+| Primitive | `VeltCommentDialogVisibilityBannerDropdownContentOrgPicker` | `velt-comment-dialog-visibility-banner-dropdown-content-org-picker` |
+| Wireframe | `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.OrgPicker` | `velt-comment-dialog-visibility-banner-dropdown-content-org-picker-wireframe` |
+
+Mirror rule: wireframe path = primitive name segment-by-segment. Primitive `...VisibilityBannerDropdownContentOrgPicker` ↔ wireframe `VisibilityBanner.Dropdown.Content.OrgPicker`; HTML wireframe = primitive HTML + `-wireframe` suffix. UserPicker is the exact sibling template for every entry. UI-customization headings use the full parent-path component name; wireframes.mdx h5 titles are bold.
+
+## Implementation Sequence
+1. Agent-3: data-models.mdx (`organizationIds`, `PrivateModeConfig` Omit, `OrgContact`, `UpdateOrgListConfig`) then api-methods.mdx (`updateOrgList()` + notes) then customize-behavior.mdx examples.
+2. Agent-4: wireframe OrgPicker in comment-dialog-structure.mdx + wireframes.mdx (+ wireframe-variables.mdx if UserPicker present). Mirror UserPicker.
+3. Agent-5: OrgPicker primitive in comment-dialog/primitives.mdx, after UserPicker container entry. Mirror UserPicker, "Common inputs only".
+4. Agent-6: align terminology ("Selected Teams", OrgPicker, updateOrgList, organizationIds) repo-wide.
+5. Agent-7: QA — diff primitive vs wireframe name strings; confirm no breaking-change content leaked into the changelog.
+
+## Quality Checklist
+- [ ] `organizationIds` added to `CommentVisibilityConfig` (data-models.mdx); `organizationId` retained.
+- [ ] `PrivateModeConfig` Omit widened to `Omit<CommentVisibilityConfig, 'annotationId'>`; prose + table updated.
+- [ ] `OrgContact` + `UpdateOrgListConfig` added to data-models.mdx.
+- [ ] `updateOrgList()` documented in api-methods.mdx after `updateContactList()`; full-replace + `contactElement`-only noted.
+- [ ] `organizationIds` notes added to `updateVisibility`/`enablePrivateMode`/`addCommentAnnotation` (api-methods + customize-behavior).
+- [ ] OrgPicker wireframe added to comment-dialog-structure.mdx (React + HTML trees) and wireframes.mdx, mirroring UserPicker; h5 titles bold.
+- [ ] OrgPicker primitive added to comment-dialog/primitives.mdx after UserPicker container; "Common inputs only".
+- [ ] Primitive/wireframe name strings mirror segment-by-segment (per Name-Mirror Spec).
+- [ ] All code examples include React / Next.js and Other Frameworks tabs.
+- [ ] No breaking-change content in the changelog; no upgrade-guide edit.
+- [ ] No docs.json change (verified pages already in nav).
+- [ ] Log written to `.claude/logs/agent-2-planning-5.0.3.md`.

.claude/logs/agent-7-qa-5.0.3.md

@@ -0,0 +1,40 @@
+# Agent-7 QA — core Velt SDK v5.0.3 (multi-org "Selected Teams" comment visibility)
+
+Branch: `main` · Scope confirmed: exactly the 7 expected files modified. Backend changelogs (velt-node/velt-py) and `docs.json` untouched. `.claude/logs/agent-2-planning-5.0.3.md` is an untracked planning log, not a doc change.
+
+## Issues Found: 1 (fixed)
+
+1. **primitives.mdx** (`comment-dialog/primitives.mdx`, OrgPicker entry) — The new OrgPicker primitive prose claimed the picker appears "when visibility is set to `selected-teams`", mirroring the UserPicker sibling's `selected-people`. But `selected-teams` is NOT a real value: the `Content.Item` `type` enum (structure.mdx + wireframes.mdx) only lists `'public' | 'org-users' | 'personal' | 'selected-people'`, and the feature targets teams via `organizationPrivate` + `organizationIds` surfaced by `updateOrgList()` — not a new Item type (the brief confirms v5.0.3 adds the component, not an Item type). `selected-teams` appeared in NO other shipped doc.
+   - Fix: Reworded to "scoping an `organizationPrivate` comment to specific teams (the 'Selected Teams' picker)… appears automatically once a team list is provided via `contactElement.updateOrgList()`." Now matches the changelog, customize-behavior, and the wireframe subsection. No invented enum value.
+
+## Verification Coverage (per file)
+
+- **sdk-changelog.mdx** — `<Update label="5.0.3" description="June 18, 2026">` sits above `5.0.2-beta.38`; `### New Features` (3) + `### Bug Fixes` (7), each a distinct `[**Comments**]` bullet (no merging); no code/wireframe blocks; all 4 learn-more anchors resolve; `<Update>` tags balanced (62/62 repo-wide); fences balanced.
+- **data-models.mdx** — `CommentVisibilityConfig` has `organizationIds` row; `PrivateModeConfig = Omit<CommentVisibilityConfig, "annotationId">` (no longer omits `organizationId`) with `organizationId`/`organizationIds` rows; `OrgContact` + `UpdateOrgListConfig` sections well-formed; all `ts`/`typescript` fences balanced.
+- **api-methods.mdx** — `updateOrgList()` present, mirrors `updateContactList()` format (no code examples — page convention; correct); `organizationIds` notes added to updateVisibility/enablePrivateMode/addCommentAnnotation.
+- **customize-behavior.mdx** — `#### updateOrgList` section + React/Other Frameworks examples (React uses `client`, Other Frameworks uses `Velt` — correct); `organizationIds` examples added to updateVisibility/enablePrivateMode; fences balanced.
+- **comment-dialog-structure.mdx** — `Content.OrgPicker` (React tree) + `…content-org-picker-wireframe` (HTML tree) added under VisibilityBanner.Dropdown.Content; consistent with existing tree.
+- **wireframes.mdx** — OrgPicker added to both wireframe trees; new `##### **OrgPicker (Visibility Banner Dropdown Content)**` subsection (bold h5, mirrors UserPicker); `<velt-wireframe style="display:none;">` present; HTML uses separate open/close tags; fences balanced.
+- **primitives.mdx** — OrgPicker entry mirrors UserPicker sibling (h3, "Common inputs only", no fabricated props table); primitive HTML has NO `-wireframe`; `#common-inputs` anchor resolves; fences balanced.
+
+### Name mirror (exact strings, verified)
+- Primitive: `VeltCommentDialogVisibilityBannerDropdownContentOrgPicker` / `velt-comment-dialog-visibility-banner-dropdown-content-org-picker` — no `-wireframe`.
+- Wireframe: `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.OrgPicker` / `velt-comment-dialog-visibility-banner-dropdown-content-org-picker-wireframe` — has `-wireframe`.
+- Segment-by-segment match, no casing drift. UserPicker siblings unchanged.
+
+### Link integrity
+All resolve: changelog → `#commentvisibilityconfig`, `#updateorglist`, `.../comment-dialog/primitives`; cross-doc → `#updateorglistconfig`, `#orgcontact`, `#privatemodeconfig`; customize-behavior anchor `#updateorglist`. Targets confirmed present in data-models.mdx (265/279/296/316), api-methods.mdx (681), customize-behavior.mdx (2159).
+
+## Pre-existing flags (NOT fixed — out of scope)
+
+- **Agent-6's reported `Content.Item` `type` enum drift could NOT be reproduced.** Agent-6 flagged a `selected-people` vs `selected-teams` split in structure.mdx's HTML tree. On inspection, structure.mdx uses `selected-people` consistently in BOTH the React tree (line 271) and the HTML tree (line 578); wireframes.mdx likewise uses `selected-people` throughout (lines 4274/4288/4299). The only `selected-teams` occurrence in shipped docs was the new OrgPicker primitive prose — which was a v5.0.3-introduced inaccuracy, now fixed above (Issue 1), not a pre-existing drift. No `selected-teams` Item type exists anywhere; flag is informational for the team in case the SDK ever introduces such a type.
+- **Minor (note only, acceptable):** `CommentVisibilityConfig` prose lacks an explicit v5.0.3 sentence (`PrivateModeConfig` got one), but the `organizationIds` row is present and the anchor resolves. Optional, not fixed.
+
+## Summary
+
+- Files corrected: 1 (primitives.mdx)
+- Genuine issues: 1 (fixed) — invented `selected-teams` enum value in OrgPicker prose
+- Pre-existing flags: 1 reported by Agent-6 could not be reproduced (clarified above)
+- Scope: 7/7 expected files; backend changelogs + docs.json untouched
+- Name mirror, fences, MDX/JSX tags, anchors, headings: all pass
+- **Overall: PASS.** Agent-1 ready for next release note.

api-reference/sdk/api/api-methods.mdx

@@ -11,6 +11,7 @@ Add a new comment annotation.
 - Params: [AddCommentAnnotationRequest](/api-reference/sdk/models/data-models#addcommentannotationrequest)
 - Returns: [AddCommentAnnotationEvent](/api-reference/sdk/models/data-models#addcommentannotationevent)
 - React Hook: `useAddCommentAnnotation()`
+- Note: For `organizationPrivate` visibility, the visibility config accepts `organizationIds?: string[]` (multi-org) alongside `organizationId`; they are merged + de-duplicated. With neither provided, the comment defaults to the logged-in user's own org.
 - [Full Documentation →](/async-collaboration/comments/customize-behavior#addcommentannotation)
 
 #### addCommentOnSelectedText()
@@ -140,13 +141,15 @@ Programmatically set comment visibility to `public`, `organizationPrivate`, or `
 - Params: `annotationId: string`, [`config: CommentVisibilityConfig`](/api-reference/sdk/models/data-models#commentvisibilityconfig)
 - Returns: `void`
 - React Hook: `n/a`
+- Note: For `organizationPrivate`, `config` accepts `organizationIds?: string[]` (multi-org) alongside `organizationId`; they are merged + de-duplicated. With neither provided, the comment defaults to the logged-in user's own org.
 - [Full Documentation →](/async-collaboration/comments/customize-behavior#updatevisibility)
 
 #### enablePrivateMode()
 Enable private mode so new comments are created with restricted visibility by default.
 - Params: [`PrivateModeConfig`](/api-reference/sdk/models/data-models#privatemodeconfig)
 - Returns: `void`
 - React Hook: `n/a`
+- Note: `PrivateModeConfig` now accepts `organizationId` / `organizationIds?: string[]` for `organizationPrivate` mode; `organizationIds` is merged + de-duplicated with `organizationId`. With neither provided, comments default to the logged-in user's own org.
 - [Full Documentation →](/async-collaboration/comments/customize-behavior#enableprivatemode)
 
 #### disablePrivateMode()
@@ -834,6 +837,13 @@ Update the contact list for the current user session.
 - React Hook: `useContactUtils()`
 - [Full Documentation →](/async-collaboration/comments/customize-behavior#updatecontactlist)
 
+#### updateOrgList()
+Supplies the list of teams shown in the comment dialog's "Selected Teams" visibility picker. Unlike `updateContactList()`, this is a full replace on every call (it does not merge); pass `{ orgList: [] }` to clear the picker. Exposed on `contactElement` only.
+- Params: [`config: UpdateOrgListConfig`](/api-reference/sdk/models/data-models#updateorglistconfig) (`orgList` is an array of [`OrgContact`](/api-reference/sdk/models/data-models#orgcontact))
+- Returns: `void`
+- React Hook: `useContactUtils()`
+- [Full Documentation →](/async-collaboration/comments/customize-behavior#updateorglist)
+
 #### updateContactListScopeForOrganizationUsers()
 Restrict which contacts are shown in the dropdown for organization users.
 - Params: `scopes: Array<'all' | 'organization' | 'organizationUserGroup' | 'document'>`