@fusebase/fusebase-gate-sdk 2.5.4 → 2.6.1

package/release-notes/2.5.4.md

@@ -2,8 +2,946 @@
 
 - Current ref: `HEAD`
 - Previous tag: `v2.5.4`
-- Generated at: 2026-08-05T12:30:28.686Z
+- Generated at: 2026-08-11T05:32:13.369Z
 
 ## Included Drafts
 
-- None
+- `docs/release-notes/2026-07-09-portal-homepage.md` - Portal homepage settings (NIM-42205)
+- `docs/release-notes/2026-08-03-isolated-sql-read-only-transaction.md` - Read-only isolated SQL is enforced by Postgres
+- `docs/release-notes/2026-08-05-add-portal-chats-dashboard-menu-item.md` - addPortalChatsDashboardMenuItem — add a Chat dashboard navigation item (NIM-43021)
+- `docs/release-notes/2026-08-05-add-portal-files-dashboard-menu-item.md` - addPortalFilesDashboardMenuItem — add a Files dashboard navigation item (NIM-43020)
+- `docs/release-notes/2026-08-05-add-portal-tasks-dashboard-menu-item.md` - addPortalTasksDashboardMenuItem — add a Tasks dashboard navigation item (NIM-43022)
+- `docs/release-notes/2026-08-05-remove-add-portal-block.md` - addPortalBlock removed from Fusebase Gate (NIM-43018)
+- `docs/release-notes/2026-08-06-chats-dashboard-menu-item-duplicates.md` - addPortalChatsDashboardMenuItem — duplicate items allowed (NIM-43021)
+- `docs/release-notes/2026-08-06-portal-block-discovery-move-delete.md` - Portal block discovery, move and delete (NIM-43062)
+- `docs/release-notes/2026-08-06-portal-block-read-and-note-update.md` - Read a portal block, and edit a note-backed one (NIM-43065)
+- `docs/release-notes/2026-08-06-portal-content-permissions.md` - Portal page and folder permissions (NIM-43064)
+- `docs/release-notes/2026-08-06-portal-text-media-block-update.md` - Edit portal Heading, Simple text and Image blocks (NIM-43065)
+- `docs/release-notes/2026-08-10-portal-ai-agent-block-update.md` - Summary
+- `docs/release-notes/2026-08-10-portal-app-block-update.md` - Summary
+- `docs/release-notes/2026-08-10-portal-bpmn-diagram-block-update.md` - Summary
+- `docs/release-notes/2026-08-10-portal-card-group-block-update.md` - Card group block update
+- `docs/release-notes/2026-08-10-portal-carousel-block-update.md` - Edit portal Carousel blocks (NIM-43065)
+- `docs/release-notes/2026-08-10-portal-chat-block-update.md` - Summary
+- `docs/release-notes/2026-08-10-portal-countdown-block-update.md` - Summary
+- `docs/release-notes/2026-08-10-portal-custom-widget-block-update.md` - Custom widget block update
+- `docs/release-notes/2026-08-10-portal-dynamic-table-block-update.md` - Dynamic Table block update
+- `docs/release-notes/2026-08-10-portal-file-uploader-block-update.md` - Summary
+- `docs/release-notes/2026-08-10-portal-form-block-update.md` - Form block update
+- `docs/release-notes/2026-08-10-portal-html-css-block-update.md` - Summary
+- `docs/release-notes/2026-08-10-portal-info-block-update.md` - Info block update
+- `docs/release-notes/2026-08-10-portal-linked-block-update.md` - Linked block update
+- `docs/release-notes/2026-08-10-portal-recent-files-block-update.md` - Recent files block update
+- `docs/release-notes/2026-08-10-portal-timeline-block-update.md` - Summary
+- `docs/release-notes/2026-08-11-portal-style.md` - Portal branding (NIM-42204)
+
+## Summary
+
+### Portal homepage settings (NIM-42205)
+
+Gate now exposes `updatePortalHomepage`, letting CLI/SDK/MCP agents configure a portal's Homepage settings — the same panel the customizer shows. The change is staged in the portal's customizer draft (not published immediately), so the owner reviews it under Homepage settings before publishing.
+
+### Read-only isolated SQL is enforced by Postgres
+
+`queryIsolatedStoreSql` decided "read-only" from the SQL text: the leading command plus a keyword scan for data-modifying CTEs. A `SELECT` over a volatile function that writes passed that check, and the scanner's lexer disagreed with Postgres about where an escape-string literal ends, which let a real data-modifying CTE through. The read path now opens its transaction with `BEGIN READ ONLY`, so the server rejects every write, including one made inside a function body. The keyword scan stays as an early, friendlier error.
+
+### addPortalChatsDashboardMenuItem — add a Chat dashboard navigation item (NIM-43021)
+
+New public operation `addPortalChatsDashboardMenuItem`
+(`POST /:orgId/portals/:portalId/chats-dashboard`, `portals.write`) adds a root
+navigation item pointing at the portal's system Chat dashboard — the
+programmatic equivalent of the Customizer's root **Dashboards > Chat dashboard**
+action.
+
+The dashboard page at `/chats-dashboard` and its canonical `chats-dashboard`
+block are created with the portal (and backfilled on older portals by
+`chatsDashboardMigration`), so this operation **never creates a page or a
+block**. A portal without that page is inconsistent, not a portal that needs a
+second dashboard: the request returns 409 and stages nothing.
+
+`addPortalChatBlock` still owns the chat WIDGET (a channel or DM block on an
+existing page). The dashboard selects no chat entity, so no channel or user
+discovery is involved.
+
+Gate is a thin semantic passthrough: exactly one portal-service call, and it
+builds no menu item, id, index or change event. The page lookup, the per-bar
+duplicate check, the canonical item shape, the atomic append and its optimistic
+concurrency retry all live in portal-service.
+
+### addPortalFilesDashboardMenuItem — add a Files dashboard navigation item (NIM-43020)
+
+New public operation `addPortalFilesDashboardMenuItem`
+(`POST /:orgId/portals/:portalId/files-dashboard`, `portals.write`) adds a root
+navigation item for the portal's system Files dashboard, staged in the
+Customizer draft. If the portal has no `/files-dashboard` page yet, the page and
+its canonical `files-dashboard` block are created in the same draft batch; if it
+already has one, only the item is added, so several bars can link to the same
+dashboard. The dashboard renders the portal's full File Manager, so it is a
+system page — not a block an agent can place on a page of its choice.
+`addPortalRecentFilesBlock` and `addPortalFileUploaderBlock` still own the
+latest-files list and the upload area on existing pages.
+
+This replaces the unreleased `createPortalFileDashboard` operation, which
+answered `409 alreadyExists` for a portal that already had the page and created
+no navigation item. Every portal gets its `/files-dashboard` page at setup, so
+that op was unusable for its actual purpose: putting a Files entry in a bar.
+
+Gate is a thin semantic passthrough: exactly one portal-service call, no draft
+read, no page/block/id/change-event construction. The dashboard lookup, the
+canonical page, item and block, the atomic batch and its optimistic-concurrency
+retry all live in portal-service.
+
+### addPortalTasksDashboardMenuItem — add a Tasks dashboard navigation item (NIM-43022)
+
+New public operation `addPortalTasksDashboardMenuItem`
+(`POST /:orgId/portals/:portalId/tasks-dashboard`, `portals.write`) adds a root
+navigation item for the portal's system Tasks dashboard, staged in the
+Customizer draft. If the portal has no `/tasks-dashboard` page yet, the page and
+its canonical `tasks-dashboard` block are created in the same draft batch; if it
+already has one, only the item is added, so several bars can link to the same
+dashboard. The dashboard shows each viewer the portal tasks they are allowed to
+access, so it is a system page — not a block an agent can place on a page of its
+choice. `addPortalTaskListBlock` and `addPortalKanbanBlock` still own the task
+list and board blocks on existing pages.
+
+Gate is a thin semantic passthrough: exactly one portal-service call, no draft
+read, no page/block/id/change-event construction. The dashboard lookup, the
+canonical page, item and block, the atomic batch and its optimistic-concurrency
+retry all live in portal-service.
+
+### addPortalBlock removed from Fusebase Gate (NIM-43018)
+
+The generic operation `addPortalBlock`
+(`POST /:orgId/portals/:portalId/blocks`, `portals.write`) is **removed**: the
+contract, the controller, its `portals` MCP prompt section, the generated
+OpenAPI/SDK artifacts and its tests.
+
+It was the universal escape hatch behind the customizer's "Add new block"
+palette. Supported semantic workflows now use dedicated operations that own
+their canonical blocks: `addPortalNoteBlock`, `addPortalBlankNoteBlock`,
+`addPortalTaskListBlock`, `addPortalKanbanBlock`, `addPortalEmbedBlock`,
+`addPortalChatBlock`, `addPortalAiAgentBlock`, `addPortalDatabaseBlock`,
+`addPortalDynamicTableBlock`, `addPortalBpmnDiagramBlock`,
+`addPortalHeadingBlock`, `addPortalTextBlock`, `addPortalImageBlock`,
+`addPortalCardBlock`, `addPortalCardGroupBlock`, `addPortalInfoBlock`,
+`addPortalCarouselBlock`, `addPortalCountdownBlock`, `addPortalFormBlock`,
+`addPortalCustomWidgetBlock`, `addPortalHtmlCssBlock`, `addPortalLinkedBlock`,
+`addPortalTimelineBlock`, `addPortalFileUploaderBlock` and
+`addPortalRecentFilesBlock`. The generic path already answered 400 naming **20**
+of those operations by hand, so its guard chain was most of what remained of it.
+
+Gate no longer builds any portal block shape by hand. `buildBlockChangeEvent`,
+`SUPPORTED_BLOCK_TYPES` and the `properties` type validator existed only for the
+generic path and went with it; the note-block builder used by
+`addPortalNoteBlock` is untouched.
+
+### addPortalChatsDashboardMenuItem — duplicate items allowed (NIM-43021)
+
+The Customizer lets a menu bar carry any number of Chat dashboard items, so
+`addPortalChatsDashboardMenuItem` no longer refuses one. The per-bar duplicate
+check and its 409 `alreadyExists` reason are removed in portal-service and gate;
+every item still points at the portal's system `/chats-dashboard` page.
+
+### Portal block discovery, move and delete (NIM-43062)
+
+Gate can now find, reorder and remove an existing block on a portal page. Until
+now it could only add blocks; changing one meant sending an internal block DTO
+or raw draft change events, which the public API does not accept.
+
+Three new operations, all staged in the active Customizer draft and never
+published automatically:
+
+- `listPortalPageBlocks` — every block of one page in display order, over the
+  published portal plus its active draft. The discovery step before a move or a
+  delete, and the order a move anchor refers to.
+- `movePortalBlock` — reorders a block within its own page via a semantic
+  position: `first`, `last`, `beforeBlockId` or `afterBlockId`.
+- `deletePortalBlock` — removes one removable block, keeping every backing
+  resource.
+
+### Read a portal block, and edit a note-backed one (NIM-43065)
+
+NIM-43062 gave Gate block discovery, move and delete. This adds the read half
+and the first typed edit, so an agent can go list → read → patch without ever
+touching an internal block DTO:
+
+- `getPortalBlock` — one block's semantic `kind` and current public settings,
+  over the published portal plus its active Customizer draft. The inverse of
+  the add operations and the step that lets an agent show the user what is set
+  today before changing it.
+- `updatePortalNoteBlock` — a partial update of a note-backed block: the kind
+  behind `addPortalNoteBlock`, `addPortalBlankNoteBlock`, `addPortalKanbanBlock`
+  and `addPortalTaskListBlock`, which all persist as the same block kind.
+
+`listPortalPageBlocks` now fills in `editOperation` for a block whose typed
+update operation exists — today that is the note kind; it stays `null` for the
+other kinds until their operations land.
+
+The change is staged in the active Customizer draft and never published
+automatically.
+
+### Portal page and folder permissions (NIM-43064)
+
+Gate can now set who may open one published portal page or folder, by path and
+email, in a single call. Until now an agent had to find the internal
+`menuItemId`, resolve numeric `userId`s and post a raw permissions payload — a
+multi-phase flow the public API does not expose.
+
+`updatePortalContentPermissions` takes the item's exact full path and a list of
+emails:
+
+- `mode: "replace"` — the previous item ACL is dropped and access is left to the
+  supplied emails ("make this page only for X").
+- `mode: "add"` — everyone who already has access keeps it and the supplied
+  emails are added ("also give X access").
+
+Emails that are not portal members yet receive a targeted client/editor portal
+invitation. Unlike `inviteToPortal`, the new members are **not** added to the
+portal's private resources, so they reach only the item they were named for.
+
+The target is resolved before any invitation is created, so a wrong path, an
+unsupported item or a caller without portal console access fails without a side
+effect. A `client`-role caller goes through the same client-invite policy
+`inviteToPortal` applies (NIM-40541: the feature kill-switch, the portal's
+`allowClientsToInvite` setting, and the caller's own portal access) — holding
+`portals.manage` is not enough to invite.
+
+The change is applied to the live portal, not staged in the Customizer draft:
+it must **not** be followed by `publishPortalDraft`.
+
+### Edit portal Heading, Simple text and Image blocks (NIM-43065)
+
+The second block family of the portal edit operations, on the seam
+`getPortalBlock` / `updatePortalNoteBlock` established. Three typed updates for
+the Customizer's Text & Media tiles, plus their `getPortalBlock` settings:
+
+- `updatePortalHeadingBlock` and `updatePortalTextBlock` — partial updates of
+  `content` (text, colour, size, styles, alignment), `appearance` and `layout`.
+- `updatePortalImageBlock` — `layout` only. The picture stays the Customizer's
+  built-in image.
+
+`getPortalBlock` now reports these kinds' current `content` and `appearance`, so
+an agent can show what is set today and preserve the fields the user did not ask
+to change. `listPortalPageBlocks` fills in `editOperation` for them.
+
+The change is staged in the active Customizer draft and never published
+automatically.
+
+### Card group block update
+
+Added support for updating an existing portal Card group block.
+
+### Edit portal Carousel blocks (NIM-43065)
+
+Agents can now read and update an existing Carousel block. Changes are staged
+in the active Customizer draft and are not published automatically.
+
+### Custom widget block update
+
+Added support for updating an existing portal Custom widget block.
+
+### Dynamic Table block update
+
+Added support for updating an existing portal Dynamic Table block.
+
+### Form block update
+
+Added support for updating an existing portal Form block.
+
+### Info block update
+
+Added support for updating an existing portal Info block.
+
+### Linked block update
+
+Added support for changing the exact source of an existing Linked block.
+
+### Recent files block update
+
+Added support for updating an existing portal Recent files block.
+
+### Portal branding (NIM-42204)
+
+Gate now exposes `updatePortalStyle`, letting CLI/SDK/MCP agents set a portal's branding — the color theme, the header logo and the favicon. These are the same three fields the customizer's Portal style panel writes. The change is staged in the portal's customizer draft (not published immediately), so the owner reviews it before publishing. `getPortal` gained the matching read side.
+
+
+## API / SDK Changes
+
+### Portal homepage settings (NIM-42205)
+
+- Added `updatePortalHomepage({ orgId, portalId }, body)` — `POST /:orgId/portals/:portalId/homepage`.
+- Body fields (all optional, patch semantics; at least one is required):
+  - `title` — homepage title. Renames the Home menu item and, with it, the linked homepage.
+  - `showSidebarOnOtherPages`, `showSidebarOnHomePage`, `expandSidebarByDefault` — sidebar toggles.
+- Omitted fields keep their current value. One call stages up to two change events — `updateThemeSettings` and `updateMenuItem` — in a single draft write, so a mixed update is all-or-nothing. Returns `{ branchId, seqs, staged: true }`. Requires `portals.write` access.
+
+### Read-only isolated SQL is enforced by Postgres
+
+No signature changes. `queryIsolatedStoreSql`, and a `query` operation in a batch where **every** operation is a read (`query`, `count`, `select`), run inside a Postgres `READ ONLY` transaction.
+
+A batch that also carries a write operation cannot be read-only — a transaction's access mode cannot be relaxed once set — so there a `query` operation is a raw write channel and now requires `isolated_store.execute` instead of `isolated_store.read`. This closes an escalation: the `client` role holds `isolated_store.data.write` but not `isolated_store.execute`, so an app token could previously run arbitrary DML/DDL through a `query` op smuggled into a write batch.
+
+### addPortalChatsDashboardMenuItem — add a Chat dashboard navigation item (NIM-43021)
+
+- New op `addPortalChatsDashboardMenuItem`, MCP-enabled, prompt groups `authz`,
+  `sdk`, `portals`. Portals MCP prompt bumped to 1.66.0.
+- New schemas `AddPortalChatsDashboardMenuItemRequest` and
+  `AddPortalChatsDashboardMenuItemResponse`.
+- The body is optional. `title` (1..100 plain-text characters, default
+  `Chat Dashboard`) names the navigation item only — the page title, icon, slug
+  and route are fixed by the service. `positionType` (`sidebar` default, `top`,
+  `footer`) picks the root menu bar.
+- There is no `pageId` and no `parentId`: the Customizer offers dashboards on
+  root only, never inside a folder or process.
+- Response is `menuItemId`, `pageId` (the system page the item points at), `url`
+  (`/chats-dashboard`), `positionType`, `branchId`, `seqs` and `staged: true`.
+  Nothing is published.
+- Duplicates are allowed, matching the Customizer: any bar may carry several
+  items, and every one of them points at the same dashboard. A portal with no
+  system dashboard page returns the terminal 409 `dashboardPageMissing`, unlike
+  the retryable `draftConflict`, so an agent is told whether a retry can help.
+
+### addPortalFilesDashboardMenuItem — add a Files dashboard navigation item (NIM-43020)
+
+- New op `addPortalFilesDashboardMenuItem`, MCP-enabled, prompt groups `authz`,
+  `sdk`, `portals`.
+- The earlier `createPortalFileDashboard` proposal is dropped rather than kept
+  alongside; it never reached `main`, so no consumer can be calling it.
+- New schemas `AddPortalFilesDashboardMenuItemRequest` and
+  `AddPortalFilesDashboardMenuItemResponse`.
+- The request body may be empty (`requestBody.required: false`). Optional
+  `title` (trimmed plain text, 1..100) names the navigation item and, when the
+  page is created, the dashboard block; optional `positionType` (`sidebar`
+  default, `top`, `footer`) chooses the bar. The page title `Files`, the
+  `/files-dashboard` path and the Files icon are fixed by the service. No
+  `pageId`, `parentId`, file/bucket ids, appearance, layout or raw persisted
+  fields are accepted.
+- Response is `menuItemId`, `pageId`, `blockId` (only when this call created the
+  page), `url`, `pageCreated`, `branchId`, `seqs` and `staged: true` — nothing is
+  published automatically.
+- `409` means only "the draft moved concurrently" and is worth a retry. An
+  existing dashboard is not a conflict.
+- Portals MCP prompt bumped to 1.65.0.
+
+### addPortalTasksDashboardMenuItem — add a Tasks dashboard navigation item (NIM-43022)
+
+- New op `addPortalTasksDashboardMenuItem`, MCP-enabled, prompt groups `authz`,
+  `sdk`, `portals`.
+- New schemas `AddPortalTasksDashboardMenuItemRequest` and
+  `AddPortalTasksDashboardMenuItemResponse`.
+- The request body may be empty. Optional `title` (trimmed plain text, 1..100)
+  names the navigation item and, when the page is created, the dashboard block;
+  optional `positionType` (`sidebar` default, `top`, `footer`) chooses the bar.
+  The page title `Task Dashboard`, the `/tasks-dashboard` path and the Tasks
+  icon are fixed by the service. No `pageId`, `parentId`, task/task-list ids,
+  appearance, layout or raw persisted fields are accepted.
+- Response is `menuItemId`, `pageId`, `blockId` (only when this call created the
+  page), `url`, `pageCreated`, `branchId`, `seqs` and `staged: true` — nothing is
+  published automatically.
+- `409` means only "the draft moved concurrently" and is worth a retry. An
+  existing dashboard is not a conflict.
+- Portals MCP prompt bumped to 1.67.0.
+
+### addPortalBlock removed from Fusebase Gate (NIM-43018)
+
+- Op `addPortalBlock` removed. The route answers 404 from this release.
+- Schemas `AddPortalBlockRequest`, `AddPortalBlockResponse` and the
+  `PortalBlockType` enum removed from the runtime schema defs, the OpenAPI
+  document and the SDK types.
+- `PortalsApi.addPortalBlock()` removed from the generated SDK client, and
+  `addPortalBlock` from the manifest's operation list.
+- The `portals` MCP prompt (bumped to 1.63.0) loses the op's menu entry and its
+  68-line detail section. The 17 "do not use generic `addPortalBlock` for X"
+  sentences in the dedicated ops' guidance are gone too: with no generic op there
+  is no detour left to warn about.
+
+### addPortalChatsDashboardMenuItem — duplicate items allowed (NIM-43021)
+
+- 409 now carries only `dashboardPageMissing` (terminal) or `draftConflict`
+  (retryable). `alreadyExists` is gone — no caller can receive it any more.
+- The documented default item title is `Chat Dashboard`, the name portal-service
+  actually gives the item (it was documented as `Chat dashboard`).
+- Portals MCP prompt bumped to 1.68.0.
+
+### Portal block discovery, move and delete (NIM-43062)
+
+- `GET /:orgId/portals/:portalId/pages/:pageId/blocks` → `{ blocks }` of
+  `blockId`, `type`, `templateType`, `title`, `editOperation`, `place`,
+  `draftOnly`. The order is the page area (`place`) first, then the position
+  inside it — a block's index is only unique within its own area.
+- `PATCH /:orgId/portals/:portalId/pages/:pageId/blocks/:blockId/position` →
+  the shared staged result `{ blockId, pageId, branchId, seqs, staged: true }`.
+- `DELETE /:orgId/portals/:portalId/pages/:pageId/blocks/:blockId` → the same
+  staged result. No request body.
+- All three require `portals.write` with the org taken from the path.
+- No raw block index is accepted anywhere. The internal append sentinel `999`
+  stays internal: the target index is resolved server-side against the effective
+  state, so a concurrent draft change cannot land the block in the wrong slot.
+- `editOperation` is `null` for every block today. It names the typed
+  `updatePortal*Block` operation for that block once those land; a `null` does
+  not mean the block cannot be moved or deleted.
+- A move anchor must carry the same `place` as the block being moved; anything
+  else is a 400 whose message names the reason.
+- Portals MCP prompt bumped to 1.70.0.
+
+### Read a portal block, and edit a note-backed one (NIM-43065)
+
+- `GET /:orgId/portals/:portalId/pages/:pageId/blocks/:blockId` →
+  `blockId`, `kind`, `type`, `templateType`, `title`, `place`, `draftOnly`,
+  `editOperation`, `layout` (`colspan`, `rowspan`, `height`) and the
+  kind-specific `settings`. `kind` is the vocabulary the typed updates use;
+  neither `type` nor `templateType` identifies a block on its own, because every
+  `flexible` block shares one type and is told apart by its template.
+  `settings` is `null` for a kind with no typed update operation yet.
+- `PATCH /:orgId/portals/:portalId/pages/:pageId/blocks/:blockId/note` →
+  the shared staged result `{ blockId, pageId, branchId, seqs, staged: true }`.
+  Body: `title`, `layout.colspan` (3–6) and `layout.height` (≥ 50, or `null` for
+  the automatic height). Every field is optional; an omitted one keeps its
+  current value and the add operation's defaults are not applied.
+- Both require `portals.write` with the org taken from the path.
+- An empty patch, and one the block already satisfies, are 400s — staging
+  nothing would answer 200 and read as "applied".
+- The block's content is not editable here: the note's text, the Kanban board
+  and the task list belong to their own operations, and `noteId` / `workspaceId`
+  are the block's identity.
+- Portals MCP prompt bumped to 1.71.0.
+
+### Portal page and folder permissions (NIM-43064)
+
+- `POST /:orgId/portals/:portalId/content/permissions` →
+  `{ item, mode, permissions, users, affectedItemIds, published: true }`.
+  Requires `portals.manage` with the org taken from the path — the same scope as
+  `inviteToPortal`, because the operation can create a portal invitation.
+- Request is `{ path, emails, mode }` only. `menuItemId`, `pageId`, `userId` and
+  raw permissions are not accepted: they are implementation details that would
+  make the call two-phase for no benefit.
+- `listPortalContent` items now carry `path` — the full portal path
+  (`/docs/start`), which is the selector the new operation takes. `slug` is
+  unchanged for backwards compatibility. `path` is absent for menu items that
+  have no path of their own (external links).
+- For a folder the ACL cascades to every descendant folder and page, matching
+  the Customizer. `affectedItemIds` lists the root plus everything the cascade
+  touched.
+- `add` against an item that is already open to everyone is a successful no-op:
+  the users already have access, and silently turning a public page private is
+  not what "add a user" asks for.
+- A path that exists only in the Customizer draft answers `409` naming
+  `publishPortalDraft`, instead of a bare "not found".
+- A path matching more than one published item answers `409` rather than picking
+  one.
+- Portals MCP prompt bumped to 1.74.0.
+
+### Edit portal Heading, Simple text and Image blocks (NIM-43065)
+
+- `PATCH /:orgId/portals/:portalId/pages/:pageId/blocks/:blockId/heading`
+- `PATCH /:orgId/portals/:portalId/pages/:pageId/blocks/:blockId/text`
+- `PATCH /:orgId/portals/:portalId/pages/:pageId/blocks/:blockId/image`
+
+  All three return the shared staged result
+  `{ blockId, pageId, branchId, seqs, staged: true }` and require
+  `portals.write` with the org taken from the path.
+
+- Body — `heading` and `text`: `content`, `appearance`, `layout`; `image`:
+  `layout` only. Every field is optional; an omitted one keeps its current
+  value and the add operation's defaults are not applied.
+- `layout.colspan` is 2–6 (wider than the note family's 3–6) and
+  `layout.height` is ≥ 50, or `null` for the automatic height.
+- `getPortalBlock`'s `settings` gains three members:
+  `{ kind: "heading" | "text", content, appearance }` and `{ kind: "image" }`.
+
+### Card group block update
+
+- Added `updatePortalCardGroupBlock` to the HTTP API, SDK and MCP surface.
+- `content.items` replaces the complete visual card list while preserving omitted stored image, destination and per-card theme values by position.
+
+### Edit portal Carousel blocks (NIM-43065)
+
+- Added `updatePortalCarouselBlock`.
+- `getPortalBlock` now returns Carousel `settings.content.items` and
+  `editOperation: updatePortalCarouselBlock`.
+- `content.items` is a full replacement list of 1–6 slides; `layout` remains a
+  field-level patch.
+- Regenerated OpenAPI, SDK and MCP skill artifacts include the new operation.
+
+### Custom widget block update
+
+- Added `updatePortalCustomWidgetBlock` to the HTTP API, SDK and MCP surface.
+- `content.bricks` is the full desired semantic brick list; raw ids, indexes, classes and image sources remain internal.
+
+### Dynamic Table block update
+
+- Added `updatePortalDynamicTableBlock` to the HTTP API, generated SDK and MCP surface.
+- The operation updates title, appearance and layout only.
+- Integration provider, OAuth connection, data source, columns and rows remain unchanged.
+
+### Form block update
+
+- Added `updatePortalFormBlock` to the HTTP API, SDK and MCP surface.
+- Existing fields preserve exact `fieldId` values; new fields omit them.
+
+### Info block update
+
+- Added `updatePortalInfoBlock` to the HTTP API, SDK and MCP surface.
+- Images and destinations use semantic variants; persisted image and link encodings remain internal.
+
+### Linked block update
+
+- Added `updatePortalLinkedBlock` to the HTTP API, generated SDK and MCP surface.
+- The operation accepts only an exact source returned by Linked block discovery.
+
+### Recent files block update
+
+- Added `updatePortalRecentFilesBlock` to the HTTP API, generated SDK and MCP surface.
+- The operation updates title, same-portal source and layout only.
+- Sort order, item limit, offset, file type, other query data and appearance remain unchanged.
+
+### Portal branding (NIM-42204)
+
+- Added `updatePortalStyle({ orgId, portalId }, body)` — `POST /:orgId/portals/:portalId/style`.
+- Body fields (all optional, patch semantics; at least one is required):
+  - `theme` — color theme key, the same 13 named themes `createPortal` accepts.
+  - `logo` — `{ storedFileUUID }` of an uploaded image, shown in the portal header.
+  - `favicon` — `{ storedFileUUID }` of an uploaded image, the browser tab icon.
+- Omitted fields keep their current value. One call stages one `updateThemeSettings` event. Returns `{ branchId, seq, staged: true }`. Requires `portals.write` access.
+- `getPortal` now returns `style` — `{ theme, logoUrl, faviconUrl }` — read from the published theme.
+
+
+## Consumer Impact
+
+### Portal homepage settings (NIM-42205)
+
+Agents can name a portal's homepage and control sidebar visibility as part of portal generation. The op covers exactly the two field groups both "Homepage settings" customizer screens show (`settings-homepage-screen.tsx` and `page-main-screen.tsx` for the Home item) — nothing else.
+
+Three field groups from the original ticket body are deliberately **not** exposed:
+
+- `heading`, `showGreeting`, `showSearch` — no customizer control produces `UPDATE_HERO_SETTING`, and the published portal stops rendering these entirely once the owner turns on the block-based Hero header (`theme.hero.show`). A field that silently loses its effect is worse than an absent one. Same reasoning as the header-blocks toggle below.
+- `headerBlocksEnabled` — stored by portal-service, but no portal component renders it.
+- `hero.subheading`, `hero.backgroundImage` — no such field exists anywhere in the customizer.
+
+Page content is out of scope: to add blocks to the homepage, resolve its `pageId` from `listPortalContent` (menu item `type: "home"`, already returned today) and call the normal semantic block operations, exactly as for any other page.
+
+Sidebar toggles live in the portal theme, which portal-service replaces wholesale on every `updateThemeSettings`. The op therefore reads the effective theme — published settings plus any theme change already staged in the draft — and writes it back with only the requested keys changed.
+
+**Depends on portal-service:** the sidebar `minimized` field. portal-service !217 is merged and deployed.
+
+### Read-only isolated SQL is enforced by Postgres
+
+SQL that used to pass the read endpoint and now fails with `cannot execute … in a read-only transaction`:
+
+- `SELECT nextval('seq')` / `setval(...)` — pre-allocate ids with `insertIsolatedStoreSqlRow ... returning` or generate them in app code
+- `SELECT … FOR UPDATE` / `FOR SHARE` — the read path commits immediately, so these locks were already released before the response
+- `SELECT … INTO new_table` and `EXPLAIN ANALYZE <INSERT|UPDATE|DELETE>` — these write; use `executeIsolatedStoreSql` or a migration bundle
+- any `SELECT` over a function that writes — the point of the change
+
+Write paths are unaffected: `executeIsolatedStoreSql`, the structured row APIs, migrations and mixed batches all still run read-write.
+
+### addPortalChatsDashboardMenuItem — add a Chat dashboard navigation item (NIM-43021)
+
+None.
+
+### addPortalFilesDashboardMenuItem — add a Files dashboard navigation item (NIM-43020)
+
+None for existing callers.
+
+### addPortalTasksDashboardMenuItem — add a Tasks dashboard navigation item (NIM-43022)
+
+None for existing callers.
+
+### addPortalBlock removed from Fusebase Gate (NIM-43018)
+
+A vendored-SDK consumer that calls `addPortalBlock` fails to compile after
+updating the SDK (the method is gone) and gets a 404 if it calls the route
+directly with an older client. Use a dedicated operation where one is available;
+each dedicated op takes semantic fields instead of a hand-written `properties`
+bag. Legacy link cards, raw `flexible` payloads and `hero-*` templates have no
+replacement.
+
+### Card group block update
+
+Consumers can update Card group title, description, cards, appearance and layout without raw bricks or links.
+
+### Edit portal Carousel blocks (NIM-43065)
+
+Call `getPortalBlock` before editing, then send the complete desired slide list.
+Built-in images and internal Carousel fields are preserved by the service and
+must not be sent by consumers.
+
+### Custom widget block update
+
+Consumers can update Custom widget title, bricks, appearance and layout.
+
+### Dynamic Table block update
+
+Consumers can update Dynamic Table presentation without replacing its integration configuration.
+
+### Form block update
+
+Consumers can update Form content and presentation without raw bricks or response data.
+
+### Info block update
+
+Consumers can update Info title, image, destination, new-tab behavior and layout.
+
+### Linked block update
+
+Consumers can repoint a Linked block while its presentation remains mirrored from the source.
+
+### Recent files block update
+
+Consumers can edit Recent files presentation and switch between the entire portal and one exact portal page.
+
+### Portal branding (NIM-42204)
+
+Agents can re-brand a portal as part of portal generation without opening the customizer: pick a theme, attach a logo, attach a favicon.
+
+Two field groups from the original ticket body are deliberately **not** exposed, because the portal theme model has nowhere to store them:
+
+- **Semantic hex colors** (`colors.primary`, `background`, `surface`, `text`, `accent`, mapped onto daisyUI `--p`/`--b1`/`--bc`/`--a`). Portals are not daisyUI-themed. Theme color slots hold arrays of **Tailwind palette tokens** (`'neutral-900'`) and render as Tailwind classes (`bg-neutral-900`), safelisted by palette name in `apps/portals/tailwind.config.js`. A raw `#2563eb` would render as the class `bg-#2563eb` and style nothing. This is the same conclusion NIM-42208 published: overriding daisyUI variables re-brands nothing, because only ~7 cosmetic widgets read them.
+- **`font: { family, source }`.** There is no font field anywhere in `PortalServiceThemeDto`, no customizer control that writes one, and no renderer that reads one.
+
+For anything beyond the named themes, `updatePortalCustomCode` is the supported path: it targets the `data-portal` structural hooks published by NIM-42208 (see reference `portal-theme-variables`), where hex colors and `@font-face` do work. That is CNAME-domain portals only.
+
+Removing a logo or favicon is also not exposed — the customizer's remove button is the way back. Add a nullable form if agents turn out to need it.
+
+Images are stored as `/box/file/{storedFileUUID}`, the same relative URL the customizer writes (`STATIC_ASSET_PREFIX` is `/box/file/` on both dev and prod), so it resolves on whatever domain serves the portal.
+
+The theme is replaced wholesale by portal-service on every `updateThemeSettings`, so the op reads the effective theme — published settings plus any theme change already staged in the draft — and writes it back with only `key` / `logo` / `icon` changed, on both the light and dark schemas. Both schemas are written together, exactly as the customizer does, so branding does not shift when dark mode is re-enabled.
+
+`getPortal` reads branding with a second portal-service call; if that call fails or the portal has no settings entry, `style` is simply omitted rather than failing the read.
+
+**No portal-service change:** the op writes through the existing draft-append endpoint and reads through the existing `/portals/settings`.
+
+
+## Verification
+
+### Portal homepage settings (NIM-42205)
+
+- `npm test -- --runTestsByPath tests/unit/portals-controller.test.ts`
+- `npm run build`
+- `FEATURE_FLAGS=isolated_sql_stores,isolated_nosql_stores npm run build:sdk`
+
+### Read-only isolated SQL is enforced by Postgres
+
+- Unit tests: `BEGIN READ ONLY` on the read path and plain `BEGIN` on the write path, all-read vs. mixed batch, and the mixed-batch `query` permission
+- Against a real Postgres 16: a `SELECT` calling a writing volatile function, the escape-string CTE bypass, and an all-read batch calling the same function are all rejected, while plain reads, the write path and mixed batches keep working. Each of the three was accepted (and did write) on the pre-change code.
+- `npm test`, `npm run lint`, `npm run build`
+
+### addPortalChatsDashboardMenuItem — add a Chat dashboard navigation item (NIM-43021)
+
+- `npm run test:unit` — including the reworked `portals-chat-dashboard-contract`
+  and `portals-chat-dashboard-seam` suites and the `mcp-prompts` pins for the new
+  guidance.
+- `npm run build`, `npm run build:sdk`, `npm run mcp:skills:validate` — clean.
+- portal-service: `addPortalChatsDashboardMenuItem.spec.ts` covering duplicate
+  items in the same and other bars, the tombstoned-page exception, the
+  missing-page path, the three bars, the root index, the retry and a reducer
+  round-trip of the staged event.
+
+### addPortalFilesDashboardMenuItem — add a Files dashboard navigation item (NIM-43020)
+
+- `npm test` — unit tests including the new
+  `portals-files-dashboard-contract` and `portals-files-dashboard-seam` suites
+  and the `mcp-prompts` pins.
+- `npm run build`, `npm run build:sdk`, `npm run mcp:skills:generate` and
+  `npm run mcp:skills:validate`.
+- portal-service: `addPortalFilesDashboardMenuItem` use-case, reducer round-trip
+  and swagger-contract specs.
+
+### addPortalTasksDashboardMenuItem — add a Tasks dashboard navigation item (NIM-43022)
+
+- `npm test` — unit tests including the new
+  `portals-tasks-dashboard-contract` and `portals-tasks-dashboard-seam` suites
+  and the `mcp-prompts` pins.
+- `npm run build`, `npm run build:sdk`, `npm run mcp:skills:generate` and
+  `npm run mcp:skills:validate`.
+- portal-service: `addPortalTasksDashboardMenuItem` use-case, reducer round-trip
+  and swagger-contract specs.
+
+### addPortalBlock removed from Fusebase Gate (NIM-43018)
+
+- `npm test` — 1018 unit tests green. The `PortalsController.addPortalBlock`
+  suite and the 21 sibling "generic op rejects X" suites go with the op (28 test
+  files touched, 22 describe blocks removed); the pins the removed prompt lines
+  carried are dropped from `mcp-prompts` and the sibling contract specs.
+- `npm run build`, `npm run lint`, `npm run mcp:skills:validate`.
+- `npm run build:sdk` — OpenAPI operation, SDK method, manifest entry and types
+  dropped.
+
+### addPortalChatsDashboardMenuItem — duplicate items allowed (NIM-43021)
+
+- `npm run test:unit`, `npm run build`, `npm run build:sdk`,
+  `npm run mcp:skills:validate` — clean.
+- portal-service: `addPortalChatsDashboardMenuItem.spec.ts` covers a second item
+  in the same bar, an item in another bar and a concurrent duplicate during the
+  retry.
+
+### Portal block discovery, move and delete (NIM-43062)
+
+- `npm run test:unit` (1090 passing), `npm run build`, `npm run lint`,
+  `npm run build:sdk`, `npm run mcp:skills:generate`,
+  `npm run mcp:skills:validate` — clean.
+- portal-service `portalBlockOperation.spec.ts`: 24 cases covering every move
+  position, self/foreign/other-area anchors, a draft-only block, the
+  not-removable guard, a block already staged for deletion, and the single
+  draft-conflict retry re-deriving the index from fresh state.
+
+### Read a portal block, and edit a note-backed one (NIM-43065)
+
+- `npm run test:unit` (1138 passing), `npm run build`, `npm run lint` (0
+  errors), `npm run build:sdk`, `npm run mcp:skills:validate` — clean.
+- portal-service `portalBlockUpdate.spec.ts`: 15 cases covering the kind map,
+  the note settings, `editOperation`, both draft events, the explicit-null
+  height, the wrong-kind guard, every validation bound and the draft-conflict
+  retry.
+- Both guards were probed rather than trusted: reverting the full-DTO merge to a
+  changed-fields-only payload reds exactly the "stages the full current block"
+  case, and cutting the update-semantics line out of the prompt reds exactly the
+  new prompt pin.
+
+### Portal page and folder permissions (NIM-43064)
+
+- portal-service `updatePortalContentPermissions.spec.ts`: 22 cases covering
+  nested-path resolution, trailing-slash and absolute-URL handling, the page and
+  its backing node, the folder cascade running once per item, `replace` dropping
+  the old lists, `add` preserving them and lifting the user out of `rejectUserIds`,
+  the public-item no-op, a system item, a foreign org, a missing path, an
+  ambiguous path, the permissions-service sync payload, a permissions-service
+  failure not being reported as success, the `mode` and empty-`userIds` guards,
+  `affectedItemIds` skipping items that were already identical, and `dryRun`
+  validating without writing.
+- fusebase-gate `portal-content-permissions.spec.ts`: 25 cases covering email
+  normalization, deduplication and the 50 limit, an existing workspace member not
+  being re-invited, a new email getting a client/editor invite without full portal
+  access, every email resolved before the ACL write, the downstream 403/404/409
+  mapping, the dry run running before the first invitation, a `client` caller
+  refused by the invite policy, and one member-list fetch per batch.
+
+### Card group block update
+
+- Portal-service typecheck, source lint and focused tests passed: 3 suites, 26 tests.
+- Gate build, lint and focused tests passed: 3 suites, 135 tests.
+- SDK and MCP artifacts were generated; MCP fallback validation passed.
+
+### Edit portal Carousel blocks (NIM-43065)
+
+- Portal-service TypeScript and 36 focused block/update/schema/route tests pass.
+  The broader serial suite exceeded the 4 GB Node heap after its earlier tests
+  passed; its one stale Carousel expectation was updated and re-run successfully.
+- Gate build, lint, SDK generation, MCP skill validation and 113 focused unit
+  tests pass. The full suite reached 1182 passing tests; only the existing
+  framework-link check failed because installed platform packages are 1.7.1
+  while package.json pins 1.7.3.
+
+### Custom widget block update
+
+- Portal-service typecheck, source lint and focused tests passed: 3 suites, 25 tests.
+- Gate build, lint and focused tests passed: 3 suites, 143 tests.
+- SDK and MCP artifacts were generated; MCP fallback validation passed.
+
+### Dynamic Table block update
+
+- Portal-service typecheck and focused tests passed: 5 suites, 41 tests.
+- Gate build and focused tests passed: 3 suites, 122 tests.
+- Gate lint passed with 12 existing warnings.
+- SDK and MCP artifacts were generated; MCP fallback validation passed.
+- Full Gate validation remains blocked by the existing platform version mismatch (installed 1.7.1, package requires 1.7.3).
+
+### Form block update
+
+- Portal-service typecheck and focused tests passed: 3 suites, 25 tests.
+- Gate build and focused tests passed: 3 suites, 131 tests.
+- SDK and MCP artifacts were generated; MCP fallback validation passed.
+- Full Gate validation remains blocked by the existing platform version mismatch (installed 1.7.1, package requires 1.7.3).
+
+### Info block update
+
+- Portal-service typecheck, source lint and focused tests passed: 3 suites, 26 tests.
+- Gate build, lint and focused tests passed: 3 suites, 139 tests.
+- SDK and MCP artifacts were generated; MCP fallback validation passed.
+
+### Linked block update
+
+- Portal-service typecheck and focused tests passed: 4 suites, 48 tests.
+- Gate build and focused tests passed: 3 suites, 128 tests.
+- Gate lint passed with 12 existing warnings.
+- SDK and MCP artifacts were generated; MCP fallback validation passed.
+- Full Gate validation remains blocked by the existing platform version mismatch (installed 1.7.1, package requires 1.7.3).
+
+### Recent files block update
+
+- Portal-service typecheck and focused tests passed: 3 suites, 26 tests.
+- Gate build and focused tests passed: 3 suites, 125 tests.
+- Gate lint passed with 12 existing warnings.
+- SDK and MCP artifacts were generated; MCP fallback validation passed.
+- Full Gate validation remains blocked by the existing platform version mismatch (installed 1.7.1, package requires 1.7.3).
+
+### Portal branding (NIM-42204)
+
+- `npm test -- --runTestsByPath tests/unit/portals-controller.test.ts tests/unit/mcp-prompts.test.ts`
+- `npm run build`
+- `FEATURE_FLAGS=isolated_sql_stores,isolated_nosql_stores npm run build:sdk`
+
+
+## Follow-ups
+
+### addPortalFilesDashboardMenuItem — add a Files dashboard navigation item (NIM-43020)
+
+Older portals created by `filesDashboardMigration` keep the migration-era block
+defaults; unifying them is a separate migration.
+
+### addPortalTasksDashboardMenuItem — add a Tasks dashboard navigation item (NIM-43022)
+
+Older portals created by `tasksDashboardMigration` keep the migration-era block
+defaults (`rowspan: 1`, `isOrigin`); unifying them is a separate migration.
+
+### addPortalBlock removed from Fusebase Gate (NIM-43018)
+
+None within NIM-43018. The legacy link cards and raw `flexible` support are
+intentionally gone. Replacement operations for `content` and the three system
+dashboards are tracked by their own tasks (see Breaking).
+
+### Card group block update
+
+None.
+
+### Edit portal Carousel blocks (NIM-43065)
+
+Implement the remaining 15 typed portal block update families one at a time.
+
+### Custom widget block update
+
+None.
+
+### Dynamic Table block update
+
+None.
+
+### Form block update
+
+None.
+
+### Info block update
+
+None.
+
+### Linked block update
+
+None.
+
+### Recent files block update
+
+None.
+
+
+## Breaking
+
+### addPortalChatsDashboardMenuItem — add a Chat dashboard navigation item (NIM-43021)
+
+None. `createPortalChatDashboardPage` never reached gate's contracts, SDK or
+OpenAPI — only portal-service's internal `POST /portals/:id/pages/chat-dashboard`
+route existed, and the paired MR removes it. It staged a second dashboard page on
+the singular `/chat-dashboard` route, while the system page every portal actually
+has is the plural `/chats-dashboard`.
+
+### addPortalFilesDashboardMenuItem — add a Files dashboard navigation item (NIM-43020)
+
+None. `createPortalFileDashboard` never reached `main`.
+
+### addPortalTasksDashboardMenuItem — add a Tasks dashboard navigation item (NIM-43022)
+
+None. The operation is additive.
+
+### addPortalBlock removed from Fusebase Gate (NIM-43018)
+
+Any caller of `addPortalBlock` must stop using it and, where available, move to
+the dedicated operation for the tile it wants. There is no deprecation window
+and no server-side redirect.
+
+The following generic paths are **dropped without replacement**, on purpose:
+
+- the legacy link cards `docs`, `help`, `request`, `meetings`, `links`;
+- raw `flexible` payloads and the `hero-*` templates.
+
+Apps remain supported through `addPortalAppPage` for a new sidebar page and
+`addPortalAppBlock` for an existing page; callers must not construct the
+underlying `app-feature` template themselves.
+
+The remaining blocks are **handled separately**:
+
+- `content` — NIM-43019;
+- `files-dashboard` — NIM-43020;
+- `tasks-dashboard` — NIM-43022;
+- `chats-dashboard` — NIM-43021.
+
+This change does not implement those replacements; their availability depends
+on the separate tasks shipping.
+
+### addPortalChatsDashboardMenuItem — duplicate items allowed (NIM-43021)
+
+None for callers that treat 409 by `reason`: the removed reason was a rejection,
+and those requests now succeed with a 201.
+
+### Portal block discovery, move and delete (NIM-43062)
+
+None — three additive operations.
+
+### Read a portal block, and edit a note-backed one (NIM-43065)
+
+None — two additive operations. `editOperation` was already in the
+`listPortalPageBlocks` response; it now carries a value for note-backed blocks
+instead of always `null`.
+
+### Portal page and folder permissions (NIM-43064)
+
+None — one additive operation plus an additive `path` field on
+`listPortalContent`.
+
+
+## Note for the next regeneration
+
+### Portal block discovery, move and delete (NIM-43062)
+
+`npm run build:sdk` must run with
+`FEATURE_FLAGS=isolated_sql_stores,isolated_nosql_stores`. Without it the
+isolated-store ops are not registered, the generator silently drops that whole
+SDK domain and the run then dies in `tsc` before writing the OpenAPI spec. This
+is pre-existing on `main`, not introduced here.
+
+### Read a portal block, and edit a note-backed one (NIM-43065)
+
+`npm run build:sdk` must run with
+`FEATURE_FLAGS=isolated_sql_stores,isolated_nosql_stores`, as recorded on the
+NIM-43062 note.
+
+### Portal page and folder permissions (NIM-43064)
+
+`npm run build:sdk` must run with
+`FEATURE_FLAGS=isolated_sql_stores,isolated_nosql_stores` (see
+`2026-08-06-portal-block-discovery-move-delete.md`).
+
+
+## Notes
+
+### Edit portal Heading, Simple text and Image blocks (NIM-43065)
+
+**`content` is a field-level patch; `appearance` is not.** A size, style or
+alignment left out of `content` keeps what the block has today. `appearance` is
+a discriminated variant and has to be sent complete — read the current one from
+`getPortalBlock` first, or the fields left out revert to the variant's defaults.
+
+**A `custom` backdrop keeps its background when the patch omits one.** A block
+the Customizer left on the portal theme's surface colour has no background to
+report, so `getPortalBlock` omits it and sending that appearance back is legal.
+
+**An empty patch, and one the block already satisfies, are 400s** — staging
+nothing would answer 200 and read as "applied".
+
+
+## Still to come
+
+### Read a portal block, and edit a note-backed one (NIM-43065)
+
+The other 22 typed `updatePortal…Block` operations from the
+`NIM-40621-edit-blocks.md` spec, and their `getPortalBlock` settings members.
+The engine seam they plug into (`updatePortalBlock` in portal-service) ships
+here.