@fusebase/fusebase-gate-sdk 2.3.34-sdk.9 → 2.5.0

package/release-notes/2.3.34-sdk.10.md

@@ -0,0 +1,1054 @@
+# Release Notes 2.3.34-sdk.10
+
+- Current ref: `HEAD`
+- Previous tag: `v2.2.15`
+- Generated at: 2026-07-27T04:36:05.229Z
+
+## Included Drafts
+
+- `docs/release-notes/2026-05-20-app-magic-link-redirectpath-fix.md` - 2026-05-20-app-magic-link-redirectpath-fix
+- `docs/release-notes/2026-05-27-visitor-api-edge-skills.md` - 2026-05-27 — Visitor access vs open `/api/*` (skill guidance)
+- `docs/release-notes/2026-06-05-isolated-store-secret-guidance.md` - Isolated store secret guidance
+- `docs/release-notes/2026-06-08-get-org-url.md` - Get organization URL
+- `docs/release-notes/2026-06-15-create-portal-folder.md` - createPortalFolder
+- `docs/release-notes/2026-06-15-duplicate-portal-item.md` - duplicatePortalItem
+- `docs/release-notes/2026-06-15-update-portal-access.md` - updatePortalAccess
+- `docs/release-notes/2026-06-16-bulk-invite-to-portal.md` - Bulk invite users to a portal
+- `docs/release-notes/2026-06-16-getme-timezone-time-format.md` - getMe returns user timezone and time-format preferences
+- `docs/release-notes/2026-06-16-token-rls-bypass-permission-validation.md` - Token creation accepts isolated_store RLS break-glass permissions
+- `docs/release-notes/2026-06-19-token-provisioning-pagination.md` - Summary
+- `docs/release-notes/2026-06-20-app-portal-embeds.md` - List an app's portal embeds
+- `docs/release-notes/2026-06-26-publish-portal-draft.md` - publishPortalDraft
+- `docs/release-notes/2026-06-29-app-portal-embeds-iframe-kind.md` - App portal embeds — detect iframe embeds, add `kind`
+- `docs/release-notes/2026-06-30-append-workspace-note-content.md` - Append workspace note content
+- `docs/release-notes/2026-06-30-client-app-invite.md` - Client → client app invite op (NIM-40541 / NIM-41954)
+- `docs/release-notes/2026-06-30-client-portal-invite.md` - Client → client portal invite authz (NIM-40541 / NIM-41950)
+- `docs/release-notes/2026-07-02-markdown-notes-crud.md` - Markdown (v3) notes CRUD
+- `docs/release-notes/2026-07-02-member-removal-client-deletion.md` - Member removal and client deletion scheduling
+- `docs/release-notes/2026-07-03-auto-confirm-email-registration.md` - 2026-07-03-auto-confirm-email-registration
+- `docs/release-notes/2026-07-04-bulk-app-magic-links.md` - Bulk app magic-link invites
+- `docs/release-notes/2026-07-09-workspace-portal-member-read.md` - Workspace and portal member read
+- `docs/release-notes/2026-07-13-getme-no-health-read.md` - getMe no longer requires health.read
+- `docs/release-notes/2026-07-23-add-portal-blank-note-block.md` - Add Portal Blank Note Block
+- `docs/release-notes/2026-07-23-conditional-remove-org-member.md` - Conditional removeOrgMember (optional preconditions)
+- `docs/release-notes/2026-07-24-add-portal-chat-block.md` - Add portal Chat block + channel discovery
+- `docs/release-notes/2026-07-24-add-portal-embed-block.md` - Add Portal Embed Block
+- `docs/release-notes/2026-07-24-create-portal-page-with-note-portal-service.md` - createPortalPageWithNote moves into portal-service
+- `docs/release-notes/2026-07-25-list-portal-chat-users.md` - List portal Chat DM target users
+
+## Summary
+
+### 2026-05-20-app-magic-link-redirectpath-fix
+
+Bug fix for the AI App **Magic Link** ops. The Gate controller coerced an
+omitted `redirectPath` to an explicit `null` before forwarding the request to
+`nimbus-ai`. nimbus-ai accepts an _absent_ `redirectPath` but rejects an
+explicit `null` (`"must be string"`), so every `createAppMagicLink` /
+`requestAppMagicLink` call that did not include a deep-link path failed with
+HTTP 400. That broke the two most common magic-link scenarios — inviting a
+client so they land on the app root, and visitor self-service where the
+visitor only types an email.
+
+### 2026-05-27 — Visitor access vs open `/api/*` (skill guidance)
+
+Clarify in MCP prompts that `--access=visitor` enables guest access to the App host via platform `/_auth/` and `fbsfeaturetoken`, not unauthenticated `/api/*`. Reduces false "broken API" reports from curl and agent smoke tests.
+
+### Isolated store secret guidance
+
+Clarified Gate isolated-store guidance so app agents treat store identity as a Gate-resolved platform resource, not app secret or runtime environment configuration.
+
+### Get organization URL
+
+Gate exposes `GET /:orgId/url` (`getOrgUrl`) to resolve the canonical HTTPS base URL for an organization. The hostname follows org-service rules: custom CNAME domain when configured, otherwise `{sub}.{FUSEBASE_HOST}`.
+
+### createPortalFolder
+
+Adds the `createPortalFolder` Gate operation (NIM-41312): create a new empty
+root folder in a portal from CLI/SDK/MCP agents. The folder is staged in the
+portal's customizer draft (via the NIM-41542 changeEvents/draft mechanism), not
+published immediately — the portal owner reviews and publishes it in the
+customizer.
+
+### duplicatePortalItem
+
+Adds the `duplicatePortalItem` Gate operation (NIM-41316): copy a folder or page
+(and, for a folder, its whole subtree of copyable children) inside the same
+portal from CLI/SDK/MCP agents. The copy is staged in the portal's customizer
+draft (via the NIM-41542 changeEvents/draft mechanism), not published
+immediately — the portal owner reviews and publishes it in the customizer.
+
+### updatePortalAccess
+
+Adds the `updatePortalAccess` Gate operation (NIM-41308): set a portal's access
+mode from CLI/SDK/MCP agents. The change is staged in the portal's customizer
+draft (via the NIM-41542 changeEvents/draft mechanism), not published
+immediately — the portal owner reviews and publishes it in the customizer.
+
+### Bulk invite users to a portal
+
+Gate exposes `POST /:orgId/portals/:portalId/invite/bulk` (`bulkInviteToPortal`) to invite many users to a single portal in one request, replacing N sequential `inviteToPortal` calls. Invites run with bounded concurrency (default 5, max 5); the rest are queued. Portal discovery (`listPortals`/`getPortal`) runs once for the whole batch. An optional `background` mode returns immediately without blocking the caller.
+
+### getMe returns user timezone and time-format preferences
+
+Extend the `GET /me` (`getMe`) response with a `preferences` object so Fusebase Apps can read the user's timezone and clock preference (12h/24h) without a separate call.
+
+### Token creation accepts isolated_store RLS break-glass permissions
+
+Fix token creation rejecting `isolated_store.rls.bypass` and `isolated_store.rls.delegate` with `Invalid permission` even though they are part of the Gate permission catalog.
+
+### List an app's portal embeds
+
+Adds a Gate operation that returns the portal pages where a given app is embedded
+(as an `app-feature` brick), scoped to the org. Backs the app card "Resources"
+popup, the in-app runtime, and the public-api/CLI proxy.
+
+### publishPortalDraft
+
+Adds the `publishPortalDraft` Gate operation (NIM-41873): publish a portal's
+staged customizer draft to the live portal from CLI/SDK/MCP agents — the
+programmatic equivalent of the customizer's Publish button. This lets an agent
+make its previously staged content/settings ops (folders, pages, blocks, access
+mode, custom code) visible to clients without opening the customizer.
+
+### App portal embeds — detect iframe embeds, add `kind`
+
+Extends `listAppPortalEmbeds` to also report portal pages where the app is embedded
+via a regular `embed` (iframe) block whose `contentUrl` points at the app host, in
+addition to the existing `app-feature` brick embeds. Every entry now carries a
+`kind` discriminator. Detection works for all consumers, including the in-app
+runtime app-token path.
+
+### Append workspace note content
+
+Add an append-only workspace note content operation for apps that need to add content to an existing note without replacing the note body.
+
+### Client → client app invite op (NIM-40541 / NIM-41954)
+
+New op `createAppClientInviteMagicLink`
+(`POST /:orgId/apps/:appId/client-invites`): an authenticated **client** that
+already has access to an AI App can invite another client. The caller's
+`orgRole` must be `client` (owners/admins use the separate `createAppMagicLink`
+flow); the op is gated by the `FEATURE_FLAGS=client_invite` env kill-switch
+(fail-closed). The invitee is always provisioned as a `client` and inherits the
+inviter's app scope (a user principal on every feature) — no role/access
+selectors. The owner/admin `createAppMagicLink` (`app_magic_link.write`) flow is
+unchanged.
+
+### Client → client portal invite authz (NIM-40541 / NIM-41950)
+
+`inviteToPortal` / `bulkInviteToPortal` now allow a caller whose `orgRole` is
+`client` to invite other clients, gated by the portal's `allowClientsToInvite`
+setting and the `FEATURE_FLAGS=client_invite` env kill-switch (fail-closed:
+off → client callers are denied `portal_client_invite_disabled`).
+Members/managers/owners are unaffected.
+
+### Markdown (v3) notes CRUD
+
+Add Gate contracts, controllers, and MCP-visible operations for v3 markdown notes: create, read, replace, and append markdown stored as the source of truth in note-service (no editor-service involved). Part of Notes v3 Iteration 1 (NIM-42034, NIM-42042).
+
+### Member removal and client deletion scheduling
+
+Gate now exposes member-removal operations for organization, workspace, and portal membership using app-visible user/workspace ids, plus delayed Client account deletion scheduling.
+
+### Bulk app magic-link invites
+
+Gate exposes `POST /:orgId/apps/:appId/magic-links/bulk` (`bulkCreateAppMagicLinks`) to invite many users to a single app in one request, replacing N sequential `createAppMagicLink` calls. Invites run with bounded concurrency (default 5, max 5); the rest are queued in-process. An optional `background` mode returns immediately without blocking the caller. Mirrors the portal `bulkInviteToPortal` pattern (NIM-41651).
+
+### Workspace and portal member read
+
+Gate now exposes read operations that list the members of a single workspace or portal scoped to an organization, closing the gap where only member writes and the org-wide roster were available.
+
+### getMe no longer requires health.read
+
+`GET /me` (`getMe`) no longer declares a required Gate permission. Any authenticated **user** or **token** subject may call it with a valid session, without `health.read` in the grant.
+
+### Add Portal Blank Note Block
+
+New operation `addPortalBlankNoteBlock`: creates an empty Fusebase note, shares it
+into the portal and stages one `addBlock` event on an existing portal page — the
+programmatic equivalent of the customizer's "Blank Block" action. No page and no
+sidebar menu item is created.
+
+### Conditional removeOrgMember (optional preconditions)
+
+`DELETE /{orgId}/users/{userId}` (`removeOrgMember`) accepts two optional query preconditions. Without them the call stays exactly as unconditional as before.
+
+- `expectedRole` — remove only while the member still holds that org role.
+- `expectedJoinedAfter` — unix seconds; remove only when the membership was created at or after that moment.
+
+Either mismatch returns **409** and removes nothing, with `data.errorCode` = `org_member_role_mismatch` or `org_member_joined_before_expected`.
+
+### Add portal Chat block + channel discovery
+
+Gate exposes two new portal operations that stage a Chat widget on a portal page,
+mirroring the customizer's "Chat" action:
+
+- `GET /:orgId/portals/:portalId/chat/channels` (`listPortalChatChannels`) — the
+  portal's real, listable chat channels (DMs, group DMs and hidden channels
+  excluded; default channel first) for the Chat block picker.
+- `POST /:orgId/portals/:portalId/pages/:pageId/blocks/chat` (`addPortalChatBlock`)
+  — stages one Chat block whose `target` is a discriminated union: a channel
+  (`target: { type: 'channel', channelId }`) or a DM (`target: { type: 'dm', userId }`).
+  One active Chat block per page.
+
+Gate stays thin: all channel/DM revalidation, the chat widget configuration and the
+draft logic live in portal-service.
+
+### Add Portal Embed Block
+
+New operation `addPortalEmbedBlock`: stages one Customizer-compatible Embed block
+("Embeds & Integrations") on an existing portal page — the programmatic equivalent
+of the customizer's Embed action. No page and no sidebar menu item is created, and
+nothing is published automatically.
+
+As part of the same change, the generic `addPortalBlock` **no longer accepts
+`type: "embed"`** — Embed blocks now go exclusively through `addPortalEmbedBlock`.
+
+### createPortalPageWithNote moves into portal-service
+
+`createPortalPageWithNote` now delegates the whole use case to a new portal-service
+endpoint (`POST /portals/:portalId/pages/note`), the same way `addPortalBlankNoteBlock`
+does. Gate keeps the public contract, auth/authz and error mapping; note creation,
+sharing, optional initial content, slug/URL/index calculation, the canonical
+addPage/addMenuItem/addBlock events and the draft append + conflict retry all live in
+portal-service. The public operation, HTTP path, request/response shape, permission
+(`portals.write`) and MCP semantics are unchanged.
+
+### List portal Chat DM target users
+
+Gate exposes a new portal operation that searches a portal org's active members
+and owner as DM targets for the Chat block picker, completing the Chat block flow
+(`listPortalChatChannels` + `addPortalChatBlock` shipped earlier):
+
+- `GET /:orgId/portals/:portalId/chat/users?query=&limit=&cursor=`
+  (`listPortalChatUsers`) — a single bounded page of
+  `{ id, displayName, email, username? }` plus the matching `total` and an opaque
+  `nextCursor`. `query` is optional: omit it to browse the first page when the
+  person is not known. Call it before `addPortalChatBlock` with a
+  `{ type: 'dm', userId }` target; pass the exact `users[].id`.
+
+Gate stays thin: the name match, member scoping and opaque cursor all live in
+org-service (`/orgs/:org/members/search`); portal-service forwards the caller's
+user context and the query/limit/cursor.
+
+
+## API / SDK Changes
+
+### 2026-05-20-app-magic-link-redirectpath-fix
+
+- No contract, schema, OpenAPI, SDK, or permission change. The Gate HTTP
+  surface is identical; `redirectPath` remains optional in both request
+  contracts.
+- `AppMagicLinksController` (`src/controllers/app-magic-links/app-magic-links.ts`)
+  now forwards `redirectPath` to nimbus-ai **only when the caller provided
+  one** (`...(body.redirectPath != null ? { redirectPath } : {})`), for both
+  `createAppMagicLink` and `requestAppMagicLink`. An empty-string
+  `redirectPath` is still forwarded verbatim.
+
+### Isolated store secret guidance
+
+No API or SDK contract changes.
+
+MCP prompts and generated skill references now explicitly say not to register `storeId`, database IDs, physical database names, or provider connection details through `fusebase secret create`.
+
+### Get organization URL
+
+- Added `getOrgUrl` operation and `OrgsApi.getOrgUrl` SDK client method.
+- Response fields: `url`, `host`, `kind` (`cname` | `subdomain`), `sub`, `customDomain`, `domainShorter`.
+- Permission: `org.read` with org-scoped authz.
+
+### createPortalFolder
+
+- New op `createPortalFolder` — `POST /:orgId/portals/:portalId/folders`.
+  - Body: `name` (required), `icon` (optional, default `folder`).
+  - Response: `{ folderId, pageId, url, branchId, seqs, staged: true }`.
+  - Permission: `portals.write`.
+- New contract types `CreatePortalFolderRequest` / `CreatePortalFolderResponse`
+  (regenerated `runtime-schema-defs`).
+- MCP `portals` prompt bumped to 1.8.0 with folder-creation guidance.
+
+### duplicatePortalItem
+
+- New op `duplicatePortalItem` —
+  `POST /:orgId/portals/:portalId/items/:itemId/duplicate`.
+  - Body: `name` (optional, default `<source name> copy`), `parentId` (optional,
+    default: next to the source).
+  - Response: `{ itemId, pageId?, url, itemCount, branchId, seqs, staged: true }`.
+  - Permission: `portals.write`.
+- New contract types `DuplicatePortalItemRequest` / `DuplicatePortalItemResponse`
+  (regenerated `runtime-schema-defs`).
+- MCP `portals` prompt bumped to 1.10.0 with duplication guidance.
+
+### updatePortalAccess
+
+- New op `updatePortalAccess` — `POST /:orgId/portals/:portalId/access`.
+  - Body: `accessMode` ∈ `open` | `invite-only` | `email` | `email-verified`.
+  - Response: `{ accessMode, branchId, seq, staged: true }`.
+  - Permission: `portals.write`.
+- New contract types `UpdatePortalAccessRequest` / `UpdatePortalAccessResponse`
+  (regenerated `runtime-schema-defs`).
+- MCP `portals` prompt bumped to 1.7.0 with access-mode guidance.
+
+### Bulk invite users to a portal
+
+- Added `bulkInviteToPortal` operation and `PortalsApi.bulkInviteToPortal` SDK client method.
+- Request: `invitations[]` (each item matches `inviteToPortal`: `email` required; optional `fullName`, `orgRole`, `workspaceRole`, `isFullAccess`), optional `concurrency` (1..5, default 5), optional `background` (default false).
+- Response: `total`, `status` (`completed` | `processing`). For `completed`: `succeeded`, `failed`, `results[]` (`{ email, status, magicLink?, url?, userId?, error? }`). For `processing`: `accepted`.
+- Per-invitation `orgRole`/`isFullAccess` semantics are identical to `inviteToPortal` (shared `invitePortalUser` helper).
+- Permission: `portals.manage` with org-scoped authz (same as `inviteToPortal`).
+- MCP: `bulkInviteToPortal` is MCP-visible under the `portals` prompt group; the prompt now documents batching, concurrency, background mode, and the client access-clarification rule.
+
+### getMe returns user timezone and time-format preferences
+
+- `MeResponse` gains a nullable `preferences` object (`MePreferences` schema):
+  - `timezone` — IANA timezone name, e.g. `Europe/Moscow` (nullable)
+  - `timezoneOffset` — current UTC offset string, e.g. `+03:00`, recomputed from the timezone at request time so it stays correct across DST (nullable)
+  - `timeFormat` — `12h` or `24h`, derived from the user's `dateTimeLocale`
+  - `dateTimeLocale` — raw display locale, e.g. `en-US` (12h) / `en-GB` (24h) (nullable)
+- `preferences` is `null` when the auth context is not user-bound (e.g. an app token without a user).
+
+### Token creation accepts isolated_store RLS break-glass permissions
+
+- No API contract changes.
+- Token `POST` now accepts all permissions from the Gate catalog, including `isolated_store.rls.bypass` and `isolated_store.rls.delegate`.
+
+### List an app's portal embeds
+
+- New operation `listAppPortalEmbeds`: `GET /:orgId/apps/:appId/portal-embeds`.
+- Auth: `userOrToken('portals.read', PATH)` — internal user or app token.
+- Response `ListAppPortalEmbedsResponse`: `{ portalEmbeds: [{ portal { globalId, name }, page { globalId, title }, url }] }`, one entry per page (deduped).
+- Lives in the new `app-embed-targets` controller/tag (a bucket for app embed-target lookups; `portal-embeds` is the first kind).
+- MCP: not exposed (`mcp.enabled: false`).
+- Downstream: calls portal-service `GET /blocks/search` with the app-embed filter (`org`, `blockType=flexible`, `brickType=app-feature`, `brickMatch=featureId:<appId>`).
+
+### publishPortalDraft
+
+- New op `publishPortalDraft` — `POST /:orgId/portals/:portalId/publish`.
+  - No body.
+  - Response: `{ branchId, newBranchId, appliedEventCount, lastPublishedAt, published: true }`.
+  - Permission: `portals.write`.
+- New contract type `PublishPortalDraftResponse` (regenerated `runtime-schema-defs`).
+- MCP `portals` prompt bumped to 1.15.0 with publish guidance.
+
+### App portal embeds — detect iframe embeds, add `kind`
+
+- `ListAppPortalEmbedsResponse` entries gain `kind: 'app-feature' | 'iframe'`
+  (additive, non-breaking).
+- `listAppPortalEmbeds` now merges two portal-service searches:
+  - existing brick search (`blockType=flexible`, `brickType=app-feature`,
+    `brickMatch=featureId:<appId>`) → `kind: 'app-feature'`.
+  - new iframe search (`blockType=embed`, `attrContains=contentUrl:<host>` per
+    resolved host) → `kind: 'iframe'`.
+- Host(s) resolved via nimbus-ai `apiGetAppByGlobalId` using a secret-only
+  ("visitor") header (no caller user id), so the app-token runtime path works too.
+  Takes the host of `url` and, when set, of `customDomainFqdn` (deduped).
+- Merge is per page with brick precedence: a page matched by both stays
+  `app-feature`.
+- Graceful degrade: if host resolution yields nothing (app not found / unpublished
+  / nimbus-ai unreachable), the iframe search is skipped and brick embeds are
+  returned normally — the op never fails on this.
+
+### Append workspace note content
+
+- Added `appendWorkspaceNoteContent`.
+- The operation accepts a workspace note id plus non-empty `content`, with optional `format: "text" | "html"`.
+- The operation appends to the end of the note and returns the refreshed note metadata plus `note.md`.
+- Regenerated SDK/OpenAPI artifacts include the new Notes API method and request contract.
+
+### Client → client app invite op (NIM-40541 / NIM-41954)
+
+- New op + request schema `CreateAppClientInviteRequest` (`email`,
+  `redirectPath?`); response reuses `CreateAppMagicLinkResponse`. SDK + OpenAPI
+  regenerated.
+- New permission `app_magic_link.client_invite`, granted to clients (and, via
+  the full set, to members/managers/owners). Distinct from
+  `app_magic_link.write` so the owner/admin flow stays owner-only.
+- `403` when the caller is not a client, the feature flag is off, the caller has
+  no app-invite permission, or the inviter has no access to the app
+  (`errorCode: forbidden` for the downstream no-access case).
+
+### Client → client portal invite authz (NIM-40541 / NIM-41950)
+
+Request/response schemas and op-level authz are unchanged; enforcement is
+internal to the controller. New error codes are returned in the existing error
+response body under `apiData.errorCode` and are now documented as `403`
+responses on both ops in the OpenAPI spec:
+
+- `portal_client_invite_disabled` (403) — portal setting off or feature flag off.
+- `forbidden` (403) — caller has no access to the portal.
+- `client_limit_reached` (403) — org client seat limit would be exceeded.
+
+### Markdown (v3) notes CRUD
+
+- Added `createWorkspaceMarkdownNote` (`POST /:orgId/workspaces/:workspaceId/markdown-notes`).
+- Added `getWorkspaceMarkdownNote` (`GET .../markdown-notes/:noteId`) returning the markdown source of truth plus `revision`.
+- Added `updateWorkspaceMarkdownNoteContent` (`PUT .../markdown-notes/:noteId/content`) replacing the full markdown document with a required optimistic `revision` lock.
+- Added `appendWorkspaceMarkdownNoteContent` (`POST .../markdown-notes/:noteId/content/append`) with an optional `revision` lock.
+- Stale-revision writes return HTTP 409 with `data.errorCode = markdown_note_revision_conflict` and `data.currentRevision`.
+- Regenerated SDK/OpenAPI artifacts include the new Notes API methods and contracts.
+
+### Member removal and client deletion scheduling
+
+- Added `removeOrgMember`.
+- Added `removeWorkspaceMember`.
+- Added `removePortalMember`.
+- Added `scheduleClientAccountDeletion`, which schedules delayed deletion only for Client-role org members.
+
+### Bulk app magic-link invites
+
+- Added `bulkCreateAppMagicLinks` operation and `AppMagicLinksApi.bulkCreateAppMagicLinks` SDK client method.
+- Request: `invitations[]` (each item matches `createAppMagicLink`: `email` required; optional `redirectPath`, `addToAccessPrincipals`), optional `concurrency` (1..5, default 5), optional `background` (default false).
+- Response: `total`, `status` (`completed` | `processing`). For `completed`: `succeeded`, `failed`, `results[]` (`{ email, status, id?, magicLinkUrl?, expiresAt?, error? }`, request order). For `processing`: `accepted`.
+- Per-invitation semantics identical to `createAppMagicLink` (shared `createOneAppMagicLink` helper): `redirectPath` is omitted from the nimbus-ai call when absent, `addToAccessPrincipals` defaults to true upstream.
+- Permission: `app_magic_link.write` with org-scoped authz (same as `createAppMagicLink`). No nimbus-ai changes — the gate fans out the existing per-user calls.
+- MCP: `bulkCreateAppMagicLinks` is MCP-visible under the `appMagicLinks` prompt group; the prompt (v1.4.0) now tells agents to use it instead of looping `createAppMagicLink`.
+
+### Workspace and portal member read
+
+- Added `listWorkspaceMembers({ orgId, workspaceId })`.
+- Added `listPortalMembers({ orgId, workspaceId })` (portal membership is represented by its underlying workspace, same semantics as `removePortalMember`).
+- Both return `{ members: OrgWorkspaceMember[] }`, where each member includes the workspaceMember `id` (globalId) required by `removeWorkspaceMember` / `removePortalMember`.
+
+### Add Portal Blank Note Block
+
+- `POST /:orgId/portals/:portalId/pages/:pageId/blocks/blank-note` (`addPortalBlankNoteBlock`,
+  permission `portals.write`, MCP prompt groups `authz`, `sdk`, `portals`).
+- Optional body `{ title }` (default `"New Document"`); returns
+  `{ noteId, blockId, pageId, branchId, seqs, staged: true }`.
+- The whole use case lives in portal-service (`POST /portals/:portalId/pages/:pageId/blocks/blank-note`,
+  portal-service client `2.34.0`): note creation/sharing, canonical block shape, block
+  index from the effective draft state and the draft append. Gate makes exactly one
+  downstream call and adds no customizer business logic.
+- Unlike `addPortalNoteBlock`, `pageId` may also be a page created earlier in the
+  active draft (portal-service resolves published + staged pages).
+
+### Conditional removeOrgMember (optional preconditions)
+
+- `OrgUsersApi.removeOrgMember` gained an optional `query` argument (`expectedRole`, `expectedJoinedAfter`).
+- New exported types `OrgMemberExpectedRoleInQueryOptional`, `OrgMemberExpectedJoinedAfterInQueryOptional`.
+- OpenAPI: two optional query parameters on `removeOrgMember`.
+
+### Add portal Chat block + channel discovery
+
+- Added `listPortalChatChannels` and `addPortalChatBlock` operations + SDK methods.
+- Permission: `portals.write`, org-scoped authz.
+- **BREAKING:** generic `addPortalBlock` no longer accepts `type='chat'`. Consumers
+  must migrate to `listPortalChatChannels` (for a channel target) followed by
+  `addPortalChatBlock`.
+
+### Add Portal Embed Block
+
+- `POST /:orgId/portals/:portalId/pages/:pageId/blocks/embed` (`addPortalEmbedBlock`,
+  permission `portals.write`, MCP prompt groups `authz`, `sdk`, `portals`).
+- Body `{ title, embedType, url?, content?, showEmbedLink?, colspan?, rowspan?, height? }`:
+  - `embedType` — one of the 11 chooser variants (`custom`, `youtube`, `google-drive`,
+    `ms-doc`, `calendly`, `hubspot`, `airtable`, `loom`, `data-studio`, `figma`, `miro`).
+    The legacy `unknown` is rejected.
+  - For `custom`, pass `content` (URL or embed code) and not `url`; for every named
+    variant, pass `url` and not `content`. The service builds the canonical iframe.
+  - Defaults: `showEmbedLink` true, `colspan` 3, `rowspan` 1, `height` null.
+- Returns `{ blockId, pageId, branchId, seqs, staged: true }`.
+- The whole use case lives in portal-service (`POST /portals/:portalId/pages/:pageId/blocks/embed`):
+  semantic-input validation, URL/Custom-Embed normalization, canonical iframe/block
+  shape, index and the draft append. Gate makes exactly one downstream call and adds
+  no customizer business logic. No server-side fetch, DNS resolution or Iframely
+  request is performed.
+- Like `addPortalBlankNoteBlock`, `pageId` may also be a page created earlier in the
+  active draft (portal-service resolves published + staged pages).
+
+### createPortalPageWithNote moves into portal-service
+
+- No public contract change: `POST /:orgId/portals/:portalId/pages/note`
+  (`createPortalPageWithNote`) keeps its operationId, path, request/response fields
+  and MCP prompt (`authz`, `sdk`, `portals`). Response is unchanged
+  (`{ noteId, menuItemId, pageId, url, branchId, seqs, staged: true }`).
+- The contract now declares `403` (portal console / org access denied) and `409`
+  (draft conflict after the internal retry) as documented responses, and enforces
+  `title` `maxLength 100`.
+- Gate makes exactly one downstream call and no longer imports customizer draft/event
+  types; note-service, editor-server, menu/slug/index and draft sequencing are gone
+  from the controller.
+- portal-service response fields (`noteId`, `menuItemId`, `pageId`, `url`, `branchId`,
+  `seqs`; `lastSeq` on 409) are marked required in its OpenAPI, so the generated client
+  exposes them as non-optional.
+
+### List portal Chat DM target users
+
+- Added `listPortalChatUsers` operation + SDK method.
+- Permission: `portals.write`, org-scoped authz. The org member search is
+  user-bound (org-service enforces `canViewMembers` on the acting user).
+- Query params: `query` (optional, 2..100 chars, matched case-insensitively
+  against display name, username and email), `limit` (optional, default 20,
+  max 50), `cursor` (optional, opaque, bound to org+user+query).
+- MCP `portals` prompt v1.23.0: added `listPortalChatUsers` guidance, the
+  DM-target flow for `addPortalChatBlock`, and the one-page-at-a-time browse /
+  "show the next 20?" pagination rule.
+
+
+## Consumer Impact
+
+### 2026-05-20-app-magic-link-redirectpath-fix
+
+- `createAppMagicLink` and `requestAppMagicLink` calls that omit
+  `redirectPath` now succeed (HTTP 200) instead of failing with HTTP 400
+  `"must be string"`. Callers that already send a `redirectPath` are
+  unaffected.
+- No action required by SDK or apps-cli consumers — the wire contract is
+  unchanged; this purely fixes the no-deep-link request path.
+
+### Isolated store secret guidance
+
+App agents should resolve isolated stores at runtime through Gate using app token/source scope and stable aliases, or use platform-provided bindings when available.
+
+Operator/CI migration commands may still use `storeId` in handoff logs, `fusebase.json`, or `--store-id`; that does not make `storeId` app runtime configuration.
+
+### Get organization URL
+
+- Apps and agents can stop hardcoding Fusebase hostnames when building org-scoped links.
+- Portal domains and app magic-link hosts remain separate surfaces; use `listPortals` or app APIs for those.
+
+### createPortalFolder
+
+- Agents can create a portal folder without touching the customizer UI. The op
+  stages two change events exactly as the customizer's section-create flow does:
+  an `addPage` node followed by an `addMenuItem` (`portalSection`) pointing at
+  it, sharing a `batchId` so the folder is a single undo unit. The slug is
+  derived from the name (collision-suffixed against the existing menu) and the
+  item is appended to the end of the root sidebar.
+- The change is staged, not live — consumers must tell the user to publish it.
+
+### duplicatePortalItem
+
+- Agents can duplicate portal content without the customizer UI. The op reads the
+  published menu subtree (and each page's content blocks) and re-emits fresh
+  `addPage` / `addMenuItem` / `addBlock` change events with new ids, remapping
+  parent ids so the copied subtree is self-contained. Copyable types are
+  `portalSection`, `note`, `portalPage`, `notesFolder`, `link`; portal
+  scaffolding (home, system dashboards, tasks/chat/all-pages, processes) is
+  skipped.
+- Fusebase notes are **reused** (the copies reference the same note via
+  `targetId`, the note is not cloned), so later edits to the note affect both the
+  original and the copy.
+- It reads **published** content only; pending draft changes should be published
+  before duplicating items that depend on them.
+- The change is staged, not live — consumers must tell the user to publish it.
+
+### updatePortalAccess
+
+- Agents can set portal access without touching the customizer UI. The op maps
+  the high-level mode to portal-service `access.portal` flags exactly as the
+  customizer's `PortalAccessSelector` does; `access.console` (editor access) is
+  preserved.
+- The change is staged, not live — consumers must tell the user to publish it.
+
+### Bulk invite users to a portal
+
+- App agents inviting several clients can issue one call instead of N blocking sequential requests.
+- Single `inviteToPortal` is unchanged; behavior and response shape are preserved.
+- Failures are isolated per invitee in `completed` mode — a single bad invite does not fail the batch.
+
+### getMe returns user timezone and time-format preferences
+
+- Apps can render dates/times in the user's timezone and clock format directly from `getMe`.
+- Backward compatible: existing fields are unchanged; `preferences` is additive.
+- Data sources: timezone from user-service `GET /users/{id}/timezone`; `timeFormat` derived from the
+  `dateTimeLocale` user var (defaults to `en-US` → `12h` when unset), matching the webnotes client.
+- Preference resolution is non-fatal: if user-service is unreachable, `getMe` still returns identity with `preferences: null`.
+
+### Token creation accepts isolated_store RLS break-glass permissions
+
+- Studio and other token-creation UIs can include RLS break-glass permissions when issuing owner/manager tokens.
+- No migration or config changes required.
+
+### List an app's portal embeds
+
+- public-api can proxy this op for the CLI; the frontend Resources popup and in-app runtime can fetch an app's portal embeds via the regenerated SDK.
+- Org-scoped by design (per spec): returns all embeds in the org; workspace-level access enforcement remains portal-service's responsibility (same as `listPortals`).
+- App-token callers must have `portals.read` in their scoped permissions, otherwise the token path returns 403.
+- Requires `npm run build:sdk` to publish the new op in the SDK/OpenAPI.
+
+### publishPortalDraft
+
+- Agents can publish staged portal changes without the customizer UI. The op
+  delegates to portal-service `POST /portals/:id/draft/publish`, which applies the
+  whole active draft branch through the same content pipeline the customizer's
+  Publish button uses (every reducer/cache/share side effect preserved).
+- It publishes the ENTIRE staged draft (including any changes the owner staged
+  manually in the customizer), so it should only be called when the user
+  explicitly wants the staged changes to go live.
+- Returns 400 if the draft is empty (nothing staged) and 409 if the portal was
+  published elsewhere since the draft was based (the draft is stale and must be
+  re-staged before publishing again).
+
+### App portal embeds — detect iframe embeds, add `kind`
+
+- public-api / CLI / frontend receive the new `kind` field; downstream consumers
+  pass it through without behavioral or visual differentiation for now.
+- Requires `npm run build:sdk` to publish the additive `kind` field and the updated
+  op description.
+
+### Append workspace note content
+
+Apps can now update existing notes by appending text or HTML instead of creating a new note. For Markdown sources, apps should render Markdown to HTML before calling the operation when formatting fidelity matters; otherwise send the content as text.
+
+### Client → client app invite op (NIM-40541 / NIM-41954)
+
+- The gate forwards the inviter's id to nimbus-ai, which performs the actual
+  "inviter has app access" check (strict principal match — never the permissive
+  managed-app User fallback) and creates the invite.
+
+### Client → client portal invite authz (NIM-40541 / NIM-41950)
+
+- Portal-client UI (NIM-41952) maps the above error codes to user messages.
+- A client invitee is always forced to `orgRole='client'` and inherits the
+  inviter's binary access level (full-private vs shared-only); the request body's
+  `orgRole`/`isFullAccess` are ignored for client callers.
+
+### Markdown (v3) notes CRUD
+
+AI/MCP callers can manage markdown-native (v3) notes end-to-end without HTML conversion. Classic (v2) notes are untouched and keep using the existing notes operations. The operations depend on the note-service markdown API (NIM-42040/NIM-42041); until note-service ships it, calls fail upstream.
+
+### Member removal and client deletion scheduling
+
+Consumers can remove org members by numeric `userId`, remove workspace/portal members by `workspaceId` plus numeric `userId`, and schedule Client account deletion by numeric user id in the org context. Gate resolves internal membership ids before calling org-service.
+
+### Bulk app magic-link invites
+
+- App agents inviting several clients issue one call instead of N blocking sequential requests.
+- Single `createAppMagicLink` is unchanged; behavior and response shape are preserved.
+- Failures are isolated per invitee in `completed` mode — one bad invite does not fail the batch.
+
+### Workspace and portal member read
+
+Apps can list members of a specific facility workspace/portal instead of the whole-org roster, avoiding cross-facility leakage, and can obtain the membership `id` needed to remove a workspace/portal member. Both ops require `org.members.read` and org access. A workspace outside the org returns `404`.
+
+### Add Portal Blank Note Block
+
+- Additive: no existing operation changes. `addPortalNoteBlock` stays the way to
+  embed an already-created, already-shared note.
+- Requires portal-service `>= 2.34.0` deployed; on an older portal-service the
+  operation returns 404 from the downstream route.
+
+### Conditional removeOrgMember (optional preconditions)
+
+- Existing callers are unaffected — omitting both params keeps today's behavior.
+- Invite-cancel flows should capture a timestamp before inviting and pass it as `expectedJoinedAfter` (plus the invited `expectedRole`), so undoing an invite can never drop a pre-existing or since-promoted member.
+- `expectedJoinedAfter` is in **seconds**, matching org-service `member.createdAt`. Passing milliseconds fails closed (409, nothing removed).
+
+### Add portal Chat block + channel discovery
+
+- Agents can add a Chat block by exact channel id or a DM user id without touching
+  chat-backend directly.
+- Any caller passing `type='chat'` to `addPortalBlock` now gets a 400 and must use
+  `addPortalChatBlock`.
+
+### Add Portal Embed Block
+
+- Requires portal-service with the `/blocks/embed` route deployed; on an older
+  portal-service the operation returns 404 from the downstream route.
+- Other `addPortalBlock` types are unchanged.
+
+### createPortalPageWithNote moves into portal-service
+
+- Backward compatible: existing callers/agents see the same operation and response.
+- Requires the portal-service release that adds `POST /portals/:portalId/pages/note`
+  deployed first; on an older portal-service the operation returns 404 from the
+  downstream route. Deploy portal-service before this Gate change.
+
+### List portal Chat DM target users
+
+- Agents can resolve a DM target by name, username or email — or browse the
+  members when the person is not known — without guessing a user id and without
+  loading the full organization user list.
+- `email` is returned so an agent can distinguish two users sharing a display name.
+
+
+## Verification
+
+### 2026-05-20-app-magic-link-redirectpath-fix
+
+- `npm run build` — clean.
+- `npm run lint` — 0 errors (5 pre-existing `dist/` warnings).
+- `npm test` — 216 pass / 1 skipped. `tests/unit/app-magic-links-controller.test.ts`
+  updated: the two tests that previously asserted `redirectPath: null` on the
+  wire now assert the key is **absent** when omitted, plus a new case that an
+  empty-string `redirectPath` is forwarded verbatim (19 cases in the suite).
+
+### 2026-05-27 — Visitor access vs open `/api/*` (skill guidance)
+
+- `npm test -- --runInBand tests/unit/mcp-prompts.test.ts`
+- `npm run mcp:skills:generate`
+- `npm run mcp:skills:validate`
+- `npm run mcp:skills:copy-to-apps-cli:local` (optional)
+
+### Isolated store secret guidance
+
+- Ran `npm run mcp:skills:generate`.
+- `npm run mcp:skills:validate` is blocked in this environment because the `skills-ref` Python module is missing.
+
+### Get organization URL
+
+- `npm test -- tests/unit/org-url-service.test.ts tests/unit/orgs-controller.test.ts`
+- `npm run build:sdk`
+- `npm run mcp:skills:generate`
+- `npm run mcp:skills:validate`
+
+### createPortalFolder
+
+- `npm run build` (regenerates runtime schema defs, tsc).
+- `npm test` — unit tests pass, incl. new `createPortalFolder` coverage
+  (batch order, slug collision, icon, 409 retry, empty-name 400, 404).
+- `npm run lint` — clean.
+
+### duplicatePortalItem
+
+- `npm run build:sdk` / `npm run build` (regenerates schema defs + SDK, tsc).
+- `npm test` — unit tests pass, incl. new `duplicatePortalItem` coverage
+  (subtree copy with fresh ids + reused note + detached block, name override,
+  item-not-found 400, non-copyable-type 400, graceful block-read failure, 404).
+- `npm run lint` — clean (only pre-existing `no-console` warnings).
+
+### updatePortalAccess
+
+- `npm run build` (regenerates runtime schema defs, tsc).
+- `npm test` — 265 unit tests pass, incl. new `updatePortalAccess` coverage
+  (mode→flags mapping, console preservation, 409 retry, 404).
+- `npm run lint` — clean.
+
+### Bulk invite users to a portal
+
+- `npm test -- tests/unit/portals-bulk-invite-controller.test.ts tests/unit/concurrency.test.ts tests/unit/portals-controller.test.ts`
+- `npm run build`
+- `npm run build:sdk`
+- `npm run mcp:skills:generate` (validate blocked locally: `skills-ref` Python module unavailable in this environment)
+
+### getMe returns user timezone and time-format preferences
+
+- `npm run build`
+- `npm test -- tests/unit/me-controller.test.ts`
+
+### Token creation accepts isolated_store RLS break-glass permissions
+
+- `npm test -- tests/unit/permissions.test.ts`
+- Create a token via `POST /tokens` with `isolated_store.rls.bypass` in `permissions`.
+
+### List an app's portal embeds
+
+- `eslint` and `tsc --noEmit` clean on the changed files.
+- Runtime (user): `GET /:orgId/apps/:appId/portal-embeds` with an internal user and with an app token — returns the deduped per-page list; a user lacking `portals.read` is denied.
+
+### publishPortalDraft
+
+- `npm run build` (regenerates runtime schema defs, tsc).
+- `npm run build:sdk` (regenerates SDK + OpenAPI, with isolated-store feature flags).
+- `npm test` — unit tests pass, incl. new `publishPortalDraft` coverage
+  (success, empty-draft 400, stale 409, portal-not-found 404).
+- `npm run lint` — clean.
+
+### App portal embeds — detect iframe embeds, add `kind`
+
+- `eslint` and `tsc --noEmit` clean on the changed files (whole-project tsc: 0
+  errors).
+- Runtime (user): embed an app via a regular `embed` block (managed or custom host,
+  with path/query) → page appears with `kind: 'iframe'`; brick + iframe on the same
+  page → one `app-feature` row; nimbus-ai down / app unpublished → brick results
+  returned normally. Works for internal-user and app-token auth.
+
+### Append workspace note content
+
+- `npm run build:sdk`
+- `npm run mcp:skills:generate`
+- `npm run mcp:skills:validate`
+- `npm run mcp:skills:copy-to-apps-cli:local`
+
+### Client → client app invite op (NIM-40541 / NIM-41954)
+
+- `npm run build`, `npm run build:sdk` (generated SDK tsc green).
+- Unit test: gate controller forwards the inviter id and maps the no-context
+  case to 403.
+
+### Client → client portal invite authz (NIM-40541 / NIM-41950)
+
+- `npm test` (controller authz matrix + inheritance, 16 cases in
+  `tests/unit/portals-bulk-invite-controller.test.ts`).
+- `npm run build`, `npm run lint` (no new warnings).
+
+### Markdown (v3) notes CRUD
+
+- `npm run build`
+- `npm run build:sdk`
+- `npm run mcp:skills:generate`
+- `npm run mcp:skills:validate`
+- `npm test` (unit suites for the new controller, client, and contracts)
+
+### Member removal and client deletion scheduling
+
+- `npm test -- --runTestsByPath tests/unit/org-users-controller.test.ts`
+- `npm run build:sdk`
+- `npm run build`
+- `npm run mcp:skills:generate`
+- `npm run mcp:skills:validate`
+
+### Bulk app magic-link invites
+
+- `npm run build`
+- `npm run build:sdk`
+- `npm run mcp:skills:generate` + `npm run mcp:skills:validate`
+- `npm test`, `npm run lint`
+- Unit tests for the bulk controller follow in NIM-42093.
+
+### Workspace and portal member read
+
+- `npm test -- --runTestsByPath tests/unit/org-users-controller.test.ts`
+- `npm run build:sdk`
+- `npm run build`
+- `npm run mcp:skills:generate`
+- `npm run mcp:skills:validate`
+
+### getMe no longer requires health.read
+
+- `npm run test:unit -- tests/unit/authz-op-registry-bridge.test.ts`
+- `npm run build`
+
+### Add Portal Blank Note Block
+
+- `npx tsc --noEmit`, `npm run lint`, `npx jest tests/unit/portals-controller.test.ts` (84 passed).
+- `npm run mcp:skills:generate` + `npm run mcp:skills:validate`.
+- portal-service: `npx jest lib/controllers/contents/addBlankNoteBlock.spec.ts` (13 passed).
+
+### Conditional removeOrgMember (optional preconditions)
+
+- `npm test`
+- `npm run build`
+- `npm run mcp:skills:generate && npm run mcp:skills:validate`
+
+### Add portal Chat block + channel discovery
+
+- `npm test -- tests/unit/portals-contracts.test.ts tests/unit/portals-controller.test.ts`
+- `npm run build`
+
+### Add Portal Embed Block
+
+- portal-service: `npx jest lib/controllers/contents/embedNormalization.spec.ts
+  lib/controllers/contents/addPortalEmbedBlock.spec.ts` (green); `npm run build` green.
+- gate: `npx tsc --noEmit`, `npm run lint`, `npx jest tests/unit/portals-controller.test.ts
+  tests/unit/portals-contracts.test.ts tests/unit/portals-embed-block-seam.test.ts`.
+- `npm run mcp:skills:generate` + `npm run mcp:skills:validate`.
+
+### createPortalPageWithNote moves into portal-service
+
+- portal-service: `npx jest lib/controllers/contents/createPortalPageWithNote.spec.ts`.
+- gate: `npm run build`, `npm run lint`,
+  `npm test -- tests/unit/portals-controller.test.ts tests/unit/portals-contracts.test.ts tests/unit/portals-page-with-note-seam.test.ts`.
+- `npm run mcp:skills:generate` + `npm run mcp:skills:validate`.
+
+### List portal Chat DM target users
+
+- `npm test -- tests/unit/portals-contracts.test.ts tests/unit/portals-chat-block-seam.test.ts`
+- `npm run build`
+
+
+## Follow-ups
+
+### 2026-05-20-app-magic-link-redirectpath-fix
+
+- None. End-to-end QA re-runs the no-`redirectPath` invite and self-service
+  cases against the dev Gate after redeploy.
+
+### Isolated store secret guidance
+
+- Restore/install the local `skills_ref` validator dependency so MCP skill validation can run end to end.
+
+### Get organization URL
+
+- None.
+
+### createPortalFolder
+
+- No new portal-service endpoint was needed: reuses the existing draft endpoints
+  - `addPage`/`addMenuItem` reducer. Sibling content ops in NIM-40621
+    (createPortalPageWithNote, addPortalNoteBlock, duplicatePortalItem) follow the
+    same draft-staging pattern.
+
+### duplicatePortalItem
+
+- No new portal-service endpoint was needed: reuses the existing draft endpoints
+  - `addPage`/`addMenuItem`/`addBlock` reducer and the `GET /blocks` reader.
+- A future iteration could deep-clone notes and replicate sync/permission/process
+  fidelity (closer to `apiPostMenusCopy`).
+
+### updatePortalAccess
+
+- No new portal-service endpoint was needed: reuses the existing draft endpoints
+  - `updateAccessSettings` reducer. Sibling content ops in NIM-40621 follow the
+    same draft-staging pattern.
+
+### Bulk invite users to a portal
+
+- Background mode is fire-and-forget within the request pod; if durable retry/observability is later required, move bulk processing to a worker/queue.
+
+### getMe returns user timezone and time-format preferences
+
+- SDK artifact regeneration (`npm run build:sdk`) is currently blocked by a pre-existing
+  IsolatedStores SDK drift (`generated/sdk-client/src/extras/sqlMigrationBundle.ts` imports
+  `IsolatedStoreSqlMigrationBundleContract`, which the regenerator no longer emits). The published
+  SDK should be rebuilt by the SDK publish pipeline once that drift is resolved.
+
+### Token creation accepts isolated_store RLS break-glass permissions
+
+- None.
+
+### List an app's portal embeds
+
+- Regenerate the SDK (`npm run build:sdk`) before downstream (public-api / frontend) consume the op.
+- M3 (public-api proxy) and M4 (frontend Resources row) are separate milestones.
+
+### publishPortalDraft
+
+- No new portal-service endpoint was needed: reuses the existing
+  `POST /portals/:id/draft/publish` (NIM-41548). Sibling content ops in NIM-40621
+  stage into the same draft this op publishes.
+
+### App portal embeds — detect iframe embeds, add `kind`
+
+- Regenerate + publish the SDK (`npm run build:sdk` / `build:sdk:push`); note the
+  version for the M3A (public-api) and M4A (nx-frontend) pin bumps.
+- M3A/M4A/M5A pass `kind` through unchanged.
+
+### Append workspace note content
+
+- Full note replacement/editing remains a separate product/API decision because it needs a canonical Markdown-to-editor-content conversion path.
+
+### Client → client portal invite authz (NIM-40541 / NIM-41950)
+
+- Enable `FEATURE_FLAGS=client_invite` per environment (dev for QA, prod on
+  rollout) — the feature is fail-closed until then.
+- App client→client invite op is tracked separately (NIM-41954, ST-5).
+
+### Markdown (v3) notes CRUD
+
+- Switch the plain-HTTP note-service markdown client to the generated `@internal/note-service` SDK once note-service publishes the markdown endpoints.
+- Add e2e-sdk/mcp-e2e coverage once the note-service contract is live (fake-note-service markdown routes should mirror the real service).
+
+### Member removal and client deletion scheduling
+
+- None.
+
+### Bulk app magic-link invites
+
+- Background mode is fire-and-forget within the request pod; if durable retry/observability is later required, move bulk processing to a worker/queue.
+
+### Workspace and portal member read
+
+- App-side Ovation Benchmarking integration is a separate task once Gate ships.
+
+### Add Portal Blank Note Block
+
+- No automatic unshare/remove compensation: a failed share or a terminal draft
+  append can leave an empty orphan note (logged as a structured warning with
+  phase/portalId/pageId/workspaceId/noteId/blockId). Cleanup is tracked separately.
+- SDK/OpenAPI artifacts are regenerated by the release `build(sdk)` commit, not here.
+
+### Conditional removeOrgMember (optional preconditions)
+
+- Query-parameter schemas are referenced but not emitted into `components/schemas` by the OpenAPI generator (pre-existing — same for `EmailInQueryOptional`).
+
+### Add portal Chat block + channel discovery
+
+- `listPortalChatUsers` (DM user search) + the dedicated org-service search endpoint
+  are tracked separately: org-service member rows carry no name fields, so a proper
+  name search needs a new org-service endpoint joining user profiles + an SDK
+  regenerate/publish. The DM target already works end-to-end via `addPortalChatBlock`
+  when the caller has the userId.
+
+### Add Portal Embed Block
+
+- Private/loopback rejection is a literal-IP/well-known-name check (no DNS
+  resolution, per spec); a hostname that resolves to a private address is not caught.
+- SDK/OpenAPI artifacts are regenerated by the release `build(sdk)` commit, not here.
+
+### createPortalPageWithNote moves into portal-service
+
+- No automatic unshare/remove compensation: a failed share, initial-content paste or
+  terminal draft append can leave an orphan note (logged as a structured warning with
+  phase/portalId/parentId/workspaceId/noteId/menuItemId/pageId/blockId). Cleanup is
+  tracked separately.
+- SDK/OpenAPI artifacts are regenerated by the release `build(sdk)` commit, not here.
+
+
+## Breaking
+
+### Add Portal Embed Block
+
+- `addPortalBlock` **rejects `type: "embed"`**. Direct callers that previously staged
+  an embed via the generic op must migrate:
+
+  ```
+  // before
+  addPortalBlock({ pageId, type: "embed", title,
+    properties: { embedType, content, contentUrl, showEmbedLink } });
+
+  // after — named variant
+  addPortalEmbedBlock({ orgId, portalId, pageId, title, embedType, url });
+  // after — custom embed
+  addPortalEmbedBlock({ orgId, portalId, pageId, title, embedType: "custom", content });
+  ```
+
+  `contentUrl` and the iframe are no longer supplied by the caller — the service
+  generates them from `url` (named) or stores `content` verbatim (custom).
+
+
+## Changes
+
+### 2026-05-27 — Visitor access vs open `/api/*` (skill guidance)
+
+- `src/mcp/prompts/fusebase-auth.ts` — `1.1.0` → `1.2.0`: section **Visitor Access Vs Open API (Platform Edge)**.
+- `src/mcp/prompts/app-magic-links.ts` — `1.2.0` → `1.3.0`: section **Platform Edge: Visitor Token And `/api/*`**; tighten `visitor` principal wording.
+- Regenerated `generated/claude_skills/fusebase-gate/references/{fusebase-auth,app-magic-links}.md`.
+
+
+## Consumer impact
+
+### 2026-05-27 — Visitor access vs open `/api/*` (skill guidance)
+
+Documentation / agent guidance only — no API or permission changes.
+
+### getMe no longer requires health.read
+
+- **Apps without `health.read` in the published grant** can call `getMe` again (service tokens, visitor browser tokens).
+- **Apps that already include `health.read`** are unchanged.
+- Do **not** remove `health.read` from grants solely because of this change — other ops may still require it.
+- Continue using `FBS_ORG_ID` / `getMyOrgAccess` for org resolution; do not rely on `getMe().auth.scopes` for visitor sessions.
+
+
+## Dependency
+
+### Client → client app invite op (NIM-40541 / NIM-41954)
+
+- Requires the nimbus-ai endpoint `apiCreateAppClientInviteMagicLink`
+  (`POST /orgs/:org/apps/:appId/client-invites`, secret/superuser-trusted),
+  shipped on the nimbus-ai `NIM-40541` branch. Until it deploys, this op returns
+  the upstream error.
+
+
+## Limitations (iteration 1)
+
+### duplicatePortalItem
+
+- Same-portal only; cross-portal copy is out of scope.
+- Notes are referenced, not deep-cloned.
+- Sync-origin linkage, external-resource copies, process status, and per-page
+  permission copies (handled by portal-service's heavyweight `apiPostMenusCopy`)
+  are not replicated — copies use allow-all permissions and are detached from
+  any sync origin. The owner reviews before publishing.
+- A copy that would exceed the portal-service draft cap (200 change events) is
+  rejected with a clear 400.
+
+
+## Why
+
+### getMe no longer requires health.read
+
+- `getMe` is the primary identity introspection op for Fusebase Apps.
+- Requiring `health.read` caused production lockouts when app grants omitted it after `fusebase analyze gate` / `--sync-gate-permissions` (see issue `041-benchmarking-app`, escalation `2026-07-13-platform-gate-2.3.29-auth-breaking-changes.md`).
+- `resolveOperationPermissions` now reports `required_permission: null` for `getMe`, aligned with `getHealth`.