@fusebase/fusebase-gate-sdk 2.13.1-sdk.0 → 2.13.1

package/dist/apis/FilesApi.d.ts

@@ -45,7 +45,7 @@ export declare class FilesApi {
     }): Promise<CreateTempStoredFileUploadResponseContract>;
     /**
      * Delete file
-     * Deletes a file-service stored file by stored-file UUID. Gate never handles the file bytes.
+     * Deletes a file-service stored file by stored-file UUID. Gate never handles the file bytes. Not available to organization clients: they remove the files they uploaded with `removeBucketAttachment`.
      */
     deleteFile(params: {
         path: {
@@ -56,7 +56,7 @@ export declare class FilesApi {
     }): Promise<DeleteFileResponseContract>;
     /**
      * List bucket attachments
-     * Lists the organization's files from every source in one list: files uploaded into an app (`app`), note attachments (`note`) and portal files (`portalPage`, `portalGlobal`, `portalFiles`, `portalBlock`). Each item carries its source `target`, its file `kind` (`image`, `video`, `audio`, `doc`, `archive` or `file`, detected from the mime type), the uploader `userId` (resolve the email and role with the org-users operations), the `size` in bytes, the custom `attributes` and the `accessPrincipals`. Filter by source with `targets`, keep only some apps or other sources with `targetIds` (matched against the item `targetId`; a bare app id needs `targets` set to `app`), drop small files with `sizeFrom`, keep only the files one user uploaded with `uploaderId`, keep only some file types with `kinds`, and match custom metadata with `attributes`, a JSON object of strings sent as a string, such as `{"source":"file-manager"}`, where every given pair must match exactly (`total` follows the same filter). Clients only receive files their access principals or the bucket permissions allow.
+     * Lists the organization's files from every source in one list: files uploaded into an app (`app`), note attachments (`note`) and portal files (`portalPage`, `portalGlobal`, `portalFiles`, `portalBlock`). Each item carries its source `target`, its file `kind` (`image`, `video`, `audio`, `doc`, `archive` or `file`, detected from the mime type), the uploader `userId` (resolve the email and role with the org-users operations), the `size` in bytes, the custom `attributes` and the `accessPrincipals`. Filter by source with `targets`, keep only some apps or other sources with `targetIds` (matched against the item `targetId`; a bare app id needs `targets` set to `app`), drop small files with `sizeFrom`, keep only the files added in a date range with `createdFrom` and `createdTo` (unix seconds like `createdAt`, both inclusive, either alone), keep only the files one user uploaded with `uploaderId`, keep only some file types with `kinds`, and match custom metadata with `attributes`, a JSON object of strings sent as a string, such as `{"source":"file-manager"}`, where every given pair must match exactly (`total` follows the same filter). Clients only receive files their access principals or the bucket permissions allow.
      */
     listBucketAttachments(params: {
         path: {
@@ -66,6 +66,8 @@ export declare class FilesApi {
             targets?: unknown[];
             targetIds?: unknown[];
             sizeFrom?: number;
+            createdFrom?: number;
+            createdTo?: number;
             uploaderId?: number;
             kinds?: unknown[];
             attributes?: string;
@@ -78,7 +80,7 @@ export declare class FilesApi {
     }): Promise<ListBucketAttachmentsResponseContract>;
     /**
      * Remove bucket attachment
-     * Removes a file of the organization from the organization file listing, whatever its source (app, note or portal). Only the uploader or an organization manager or owner may remove it.
+     * Removes a file of the organization from the organization file listing, whatever its source (app, note or portal). Only the uploader or an organization manager or owner may remove it, so an organization client removes only the files it uploaded.
      */
     removeBucketAttachment(params: {
         path: {
@@ -100,7 +102,7 @@ export declare class FilesApi {
     }): Promise<StartMultipartFileUploadResponseContract>;
     /**
      * Update bucket attachment
-     * Renames a bucket attachment or replaces its attributes and accessPrincipals. Works on any file of the organization; `accessPrincipals` only on app files. Only the uploader or an organization manager or owner may change `attributes` or `accessPrincipals`. Send `accessPrincipals: null` to drop every restriction and show the file to everyone who can see the organization bucket.
+     * Renames a bucket attachment or replaces its attributes and accessPrincipals. Works on any file of the organization; `accessPrincipals` only on app files. Only the uploader or an organization manager or owner may change `attributes` or `accessPrincipals`; an organization client may change only the files it uploaded, the name included. Send `accessPrincipals: null` to drop every restriction and show the file to everyone who can see the organization bucket.
      */
     updateBucketAttachment(params: {
         path: {

package/dist/apis/FilesApi.js

@@ -58,7 +58,7 @@ class FilesApi {
     }
     /**
      * Delete file
-     * Deletes a file-service stored file by stored-file UUID. Gate never handles the file bytes.
+     * Deletes a file-service stored file by stored-file UUID. Gate never handles the file bytes. Not available to organization clients: they remove the files they uploaded with `removeBucketAttachment`.
      */
     async deleteFile(params) {
         return this.client.request({
@@ -73,7 +73,7 @@ class FilesApi {
     }
     /**
      * List bucket attachments
-     * Lists the organization's files from every source in one list: files uploaded into an app (`app`), note attachments (`note`) and portal files (`portalPage`, `portalGlobal`, `portalFiles`, `portalBlock`). Each item carries its source `target`, its file `kind` (`image`, `video`, `audio`, `doc`, `archive` or `file`, detected from the mime type), the uploader `userId` (resolve the email and role with the org-users operations), the `size` in bytes, the custom `attributes` and the `accessPrincipals`. Filter by source with `targets`, keep only some apps or other sources with `targetIds` (matched against the item `targetId`; a bare app id needs `targets` set to `app`), drop small files with `sizeFrom`, keep only the files one user uploaded with `uploaderId`, keep only some file types with `kinds`, and match custom metadata with `attributes`, a JSON object of strings sent as a string, such as `{"source":"file-manager"}`, where every given pair must match exactly (`total` follows the same filter). Clients only receive files their access principals or the bucket permissions allow.
+     * Lists the organization's files from every source in one list: files uploaded into an app (`app`), note attachments (`note`) and portal files (`portalPage`, `portalGlobal`, `portalFiles`, `portalBlock`). Each item carries its source `target`, its file `kind` (`image`, `video`, `audio`, `doc`, `archive` or `file`, detected from the mime type), the uploader `userId` (resolve the email and role with the org-users operations), the `size` in bytes, the custom `attributes` and the `accessPrincipals`. Filter by source with `targets`, keep only some apps or other sources with `targetIds` (matched against the item `targetId`; a bare app id needs `targets` set to `app`), drop small files with `sizeFrom`, keep only the files added in a date range with `createdFrom` and `createdTo` (unix seconds like `createdAt`, both inclusive, either alone), keep only the files one user uploaded with `uploaderId`, keep only some file types with `kinds`, and match custom metadata with `attributes`, a JSON object of strings sent as a string, such as `{"source":"file-manager"}`, where every given pair must match exactly (`total` follows the same filter). Clients only receive files their access principals or the bucket permissions allow.
      */
     async listBucketAttachments(params) {
         return this.client.request({
@@ -88,7 +88,7 @@ class FilesApi {
     }
     /**
      * Remove bucket attachment
-     * Removes a file of the organization from the organization file listing, whatever its source (app, note or portal). Only the uploader or an organization manager or owner may remove it.
+     * Removes a file of the organization from the organization file listing, whatever its source (app, note or portal). Only the uploader or an organization manager or owner may remove it, so an organization client removes only the files it uploaded.
      */
     async removeBucketAttachment(params) {
         return this.client.request({
@@ -117,7 +117,7 @@ class FilesApi {
     }
     /**
      * Update bucket attachment
-     * Renames a bucket attachment or replaces its attributes and accessPrincipals. Works on any file of the organization; `accessPrincipals` only on app files. Only the uploader or an organization manager or owner may change `attributes` or `accessPrincipals`. Send `accessPrincipals: null` to drop every restriction and show the file to everyone who can see the organization bucket.
+     * Renames a bucket attachment or replaces its attributes and accessPrincipals. Works on any file of the organization; `accessPrincipals` only on app files. Only the uploader or an organization manager or owner may change `attributes` or `accessPrincipals`; an organization client may change only the files it uploaded, the name included. Send `accessPrincipals: null` to drop every restriction and show the file to everyone who can see the organization bucket.
      */
     async updateBucketAttachment(params) {
         return this.client.request({

package/dist/apis/NotesApi.d.ts

@@ -5,7 +5,7 @@
  * Domain: notes
  */
 import type { Client } from "../runtime/transport";
-import type { AddWorkspaceMarkdownNoteAttachmentRequestContract, AddWorkspaceMarkdownNoteAttachmentResponseContract, AddWorkspaceNoteAttachmentRequestContract, AddWorkspaceNoteAttachmentResponseContract, AppendWorkspaceMarkdownNoteContentRequestContract, AppendWorkspaceNoteContentRequestContract, CreateWorkspaceMarkdownNoteRequestContract, CreateWorkspaceNoteFolderRequestContract, CreateWorkspaceNoteFolderResponseContract, CreateWorkspaceNoteRequestContract, CreateWorkspaceNoteResponseContract, orgIdInPathRequired, ShareWorkspaceMarkdownNoteRequestContract, ShareWorkspaceMarkdownNoteResponseContract, UnshareWorkspaceMarkdownNoteResponseContract, UpdateWorkspaceMarkdownNoteContentRequestContract, WorkspaceIdInPathRequired, WorkspaceMarkdownNoteResponseContract, WorkspaceNoteContentResponseContract, WorkspaceNoteFolderListResponseContract, WorkspaceNoteIdInPathRequired, WorkspaceNoteListResponseContract, WorkspaceNoteParentIdInQueryOptional } from "../types";
+import type { AddWorkspaceMarkdownNoteAttachmentRequestContract, AddWorkspaceMarkdownNoteAttachmentResponseContract, AddWorkspaceNoteAttachmentRequestContract, AddWorkspaceNoteAttachmentResponseContract, AppendWorkspaceMarkdownNoteContentRequestContract, AppendWorkspaceNoteContentRequestContract, CreateWorkspaceMarkdownNoteRequestContract, CreateWorkspaceNoteFolderRequestContract, CreateWorkspaceNoteFolderResponseContract, CreateWorkspaceNoteRequestContract, CreateWorkspaceNoteResponseContract, orgIdInPathRequired, ShareWorkspaceMarkdownNoteRequestContract, ShareWorkspaceMarkdownNoteResponseContract, UnshareWorkspaceMarkdownNoteResponseContract, UpdateWorkspaceMarkdownNoteContentRequestContract, WorkspaceIdInPathRequired, WorkspaceMarkdownNoteResponseContract, WorkspaceNoteContentResponseContract, WorkspaceNoteFolderListResponseContract, WorkspaceNoteIdInPathRequired, WorkspaceNoteListResponseContract, WorkspaceNoteParentIdInQueryOptional, WorkspaceNoteSearchResponseContract } from "../types";
 export declare class NotesApi {
     private client;
     constructor(client: Client);
@@ -146,6 +146,22 @@ export declare class NotesApi {
         };
         headers?: Record<string, string>;
     }): Promise<WorkspaceNoteListResponseContract>;
+    /**
+     * Search workspace notes by text
+     * Full-text search over note titles and text in one workspace, covering both classic (v2) and markdown (v3) notes. Each hit carries `contentVersion` (`v2` or `markdown_v3`) so the caller knows whether to read it with getWorkspaceNote or getWorkspaceMarkdownNote, plus a `snippet` around the matched words. Pass `parentId` to search only inside that folder and its subfolders. Folders, trashed, encrypted and portal-shared notes are never returned; v3 hits are returned only when the caller also holds `notes.markdown.read`. Ranking is keyword full-text, not semantic. Prefer a real workspace id; when the path workspaceId is `default`, gate resolves it to the organization's default workspace.
+     */
+    searchWorkspaceNotes(params: {
+        path: {
+            orgId: orgIdInPathRequired;
+            workspaceId: WorkspaceIdInPathRequired;
+        };
+        query?: {
+            query?: string;
+            parentId?: WorkspaceNoteParentIdInQueryOptional;
+            limit?: number;
+        };
+        headers?: Record<string, string>;
+    }): Promise<WorkspaceNoteSearchResponseContract>;
     /**
      * Share markdown (v3) note
      * Publishes a v3 markdown note through the existing note-service share flow and returns the share links for the three read-only modes: `ui` (full share page), `rendered` (markdown only) and `raw` (the markdown source as `text/markdown`). note-service creates the security key and enforces the caller's own note access, password and access-control rules — gate mints nothing. Calling it again on an already shared note updates that same share instead of creating a second one. v2 notes are not accepted here; they keep their existing sharing flow.

package/dist/apis/NotesApi.js

@@ -173,6 +173,21 @@ class NotesApi {
             expectedContentType: "application/json",
         });
     }
+    /**
+     * Search workspace notes by text
+     * Full-text search over note titles and text in one workspace, covering both classic (v2) and markdown (v3) notes. Each hit carries `contentVersion` (`v2` or `markdown_v3`) so the caller knows whether to read it with getWorkspaceNote or getWorkspaceMarkdownNote, plus a `snippet` around the matched words. Pass `parentId` to search only inside that folder and its subfolders. Folders, trashed, encrypted and portal-shared notes are never returned; v3 hits are returned only when the caller also holds `notes.markdown.read`. Ranking is keyword full-text, not semantic. Prefer a real workspace id; when the path workspaceId is `default`, gate resolves it to the organization's default workspace.
+     */
+    async searchWorkspaceNotes(params) {
+        return this.client.request({
+            method: "GET",
+            path: "/:orgId/workspaces/:workspaceId/notes/search",
+            pathParams: params.path,
+            query: params.query,
+            headers: params.headers,
+            opId: "searchWorkspaceNotes",
+            expectedContentType: "application/json",
+        });
+    }
     /**
      * Share markdown (v3) note
      * Publishes a v3 markdown note through the existing note-service share flow and returns the share links for the three read-only modes: `ui` (full share page), `rendered` (markdown only) and `raw` (the markdown source as `text/markdown`). note-service creates the security key and enforces the caller's own note access, password and access-control rules — gate mints nothing. Calling it again on an already shared note updates that same share instead of creating a second one. v2 notes are not accepted here; they keep their existing sharing flow.

package/dist/types/note/note.d.ts

@@ -25,6 +25,24 @@ export interface WorkspaceNoteListQueryContract {
      */
     parentId?: WorkspaceNoteParentIdInQueryOptional;
 }
+export interface WorkspaceNoteSearchHitContract {
+    globalId: string;
+    title?: string | null;
+    parentId?: string | null;
+    workspaceId: string;
+    /**
+     * `markdown_v3` for v3 markdown notes (read them with getWorkspaceMarkdownNote),
+     * `v2` for classic notes (read them with getWorkspaceNote).
+     */
+    contentVersion: "v2" | "markdown_v3";
+    /**
+     * Text around the matched words, when the search index returned one.
+     */
+    snippet?: string | null;
+}
+export interface WorkspaceNoteSearchResponseContract {
+    notes: WorkspaceNoteSearchHitContract[];
+}
 export interface CreateWorkspaceNoteFolderRequestContract {
     title: string;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusebase/fusebase-gate-sdk",
-  "version": "2.13.1-sdk.0",
+  "version": "2.13.1",
   "description": "TypeScript SDK for Fusebase Gate APIs - Generated from contract introspection",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/release-notes/2.13.1-sdk.0.md

@@ -1,9 +1,88 @@
 # Release Notes 2.13.1-sdk.0
 
 - Current ref: `HEAD`
-- Previous tag: `v2.13.1-sdk.0`
-- Generated at: 2026-09-29T14:32:50.746Z
+- Previous tag: `v2.13.0`
+- Generated at: 2026-09-29T14:28:28.394Z
 
 ## Included Drafts
 
-- None
+- `docs/release-notes/2026-09-25-dashboard-custom-columns.md` - Custom columns on client, member, workspace, and portal lists (NIM-44852)
+- `docs/release-notes/2026-09-29-dashboard-metadata-values.md` - Custom column values on client, member, workspace, and portal lists (NIM-44852)
+
+## Summary
+
+### Custom columns on client, member, workspace, and portal lists (NIM-44852)
+
+`listOrgUsers`, `listWorkspaces`, and `listPortals` now include user-added
+custom columns from the matching existing dashboards. System and template
+columns are omitted. A missing dashboard yields an empty column list and does
+not fail the list.
+
+Clients and members are both users, so `listOrgUsers` carries both dashboards:
+`metadata.clients` and `metadata.members`. Workspaces and portals carry
+`metadata.columns` from aliases `workspaces` and `portals`.
+
+### Custom column values on client, member, workspace, and portal lists (NIM-44852)
+
+`listOrgUsers`, `listWorkspaces`, and `listPortals` now include the cell
+values of user-added dashboard columns. Column descriptions stay in
+`metadata`. Values sit on each entity as `metadataValues`, keyed by column
+`key`. A missing cell is `null`.
+
+Clients read the clients dashboard. Every other role on `listOrgUsers` reads
+the members dashboard.
+
+
+## API / SDK Changes
+
+### Custom columns on client, member, workspace, and portal lists (NIM-44852)
+
+- `OrgUserListResponse.metadata.clients.columns` and `.members.columns`.
+- `OrgWorkspaceListResponse.metadata.columns`.
+- `OrgPortalListResponse.metadata.columns`.
+- Column shape: `{ key, alias, name, customType, hidden, readonly, required }`.
+- No new operation. Existing list fields are unchanged.
+
+### Custom column values on client, member, workspace, and portal lists (NIM-44852)
+
+- `OrgUserListItem.metadataValues`, `OrgWorkspaceListItem.metadataValues`,
+  `OrgPortalListItem.metadataValues`.
+- Create-workspace and nested org-member payloads are unchanged.
+- No new operation.
+
+
+## Consumer Impact
+
+### Custom columns on client, member, workspace, and portal lists (NIM-44852)
+
+Callers that ignore unknown fields are unaffected. Callers that need extra
+dashboard fields read `metadata` on the list they already call.
+
+### Custom column values on client, member, workspace, and portal lists (NIM-44852)
+
+Callers that ignore unknown fields are unaffected. Callers that compare list
+items field-for-field now see `metadataValues`.
+
+
+## Verification
+
+### Custom columns on client, member, workspace, and portal lists (NIM-44852)
+
+- Unit tests cover custom-only filtering and a missing dashboard.
+
+### Custom column values on client, member, workspace, and portal lists (NIM-44852)
+
+- Unit test maps a wrapped dashboard cell onto `metadataValues` and fills a
+  missing cell with `null`.
+- Live dev check of a filled client cell is still pending a deploy.
+
+
+## Follow-ups
+
+### Custom columns on client, member, workspace, and portal lists (NIM-44852)
+
+- Cell values shipped later as `metadataValues` on each listed entity.
+
+### Custom column values on client, member, workspace, and portal lists (NIM-44852)
+
+- None.

package/release-notes/2.13.1.md

@@ -0,0 +1,90 @@
+# Release Notes 2.13.1
+
+- Current ref: `HEAD`
+- Previous tag: `v2.13.1-sdk.0`
+- Generated at: 2026-09-29T21:24:25.497Z
+
+## Included Drafts
+
+- `docs/release-notes/2026-09-29-client-files-write.md` - Portal clients can upload files
+- `docs/release-notes/2026-09-29-notes-search.md` - Search notes by their text
+
+## Summary
+
+### Portal clients can upload files
+
+A portal client could not upload through a FuseBase app: the first upload call answered 403
+"Missing required permission: files.write". The client role now holds `files.write`. A client
+may upload and create bucket attachments, and may rename, change or remove only the files it
+uploaded. `deleteFile` is not available to clients.
+
+### Search notes by their text
+
+MCP clients and AI agents could read and edit notes but had no way to find one by its content.
+`searchWorkspaceNotes` searches note titles and text in one workspace, for classic (v2) and
+markdown (v3) notes, using the full-text search note-service already has.
+
+
+## API / SDK Changes
+
+### Portal clients can upload files
+
+- Client role permissions: `files.write` added. Visitor stays read-only.
+- `deleteFile` answers 403 when the caller's organization role is client. A stored-file UUID has
+  no organization and no uploader to check a client against.
+- `updateBucketAttachment` and `removeBucketAttachment`: no change in Gate. bucket-service
+  decides whether the client uploaded the file and its 403 reaches the caller as 403.
+- Op descriptions, MCP `files` prompt (1.15.0), SDK and the Gate files skill reference updated.
+
+### Search notes by their text
+
+- New op `searchWorkspaceNotes`, `GET /:orgId/workspaces/:workspaceId/notes/search` (`notes.read`).
+  Query: `query` (required), `parentId` (search that folder and its subfolders), `limit`
+  (1 to 100, default 20; other values answer 400). `workspaceId` accepts `default`.
+- Each hit: `globalId`, `title`, `parentId`, `workspaceId`, `contentVersion` (`v2` or
+  `markdown_v3`) and `snippet` around the matched words.
+- Never returned: folders, trashed notes (also notes inside a trashed folder), portal-shared and
+  encrypted notes, notes the user cannot read. `markdown_v3` hits need `notes.markdown.read` too.
+- Ranking is keyword full-text, not semantic. No new index.
+- MCP `notes` prompt, SDK `NotesApi`, manifest, OpenAPI and the Gate notes skill reference
+  cover the new op.
+
+
+## Consumer Impact
+
+### Portal clients can upload files
+
+- Same permission name, so deployed apps need no redeploy; an app that lists `files.write` gets
+  it for its client users too.
+- Nothing is tightened for owner, manager, member, guest or app service tokens. Clients never
+  held `files.write`, so the `deleteFile` refusal takes nothing away from a working app.
+- Client uploads work end to end only with the bucket-service release that lets a client create
+  app files (NIM-45207). Before it, a client passes Gate and gets bucket-service's 403, as today.
+
+### Search notes by their text
+
+- New op; nothing changes for existing callers.
+
+
+## Verification
+
+### Portal clients can upload files
+
+- Unit: `tests/unit/permissions.test.ts` (client has `files.write`, visitor does not),
+  `tests/unit/files-controller.test.ts` (client refused on `deleteFile`, member allowed).
+
+### Search notes by their text
+
+- Unit: `tests/unit/notes-controller.test.ts` (trash and portal filtering, `root` search scope,
+  v3 permission rule, limit applied after filtering, invalid limit). Full unit suite green.
+
+
+## Follow-ups
+
+### Portal clients can upload files
+
+- NIM-45213: `deleteFile` has no organization or owner check for any caller.
+
+### Search notes by their text
+
+- Semantic or hybrid ranking, if agents need it, is a separate task.

package/release-notes/latest.md

@@ -1,9 +1,90 @@
-# Release Notes 2.13.1-sdk.0
+# Release Notes 2.13.1
 
 - Current ref: `HEAD`
 - Previous tag: `v2.13.1-sdk.0`
-- Generated at: 2026-09-29T14:32:50.746Z
+- Generated at: 2026-09-29T21:24:25.497Z
 
 ## Included Drafts
 
-- None
+- `docs/release-notes/2026-09-29-client-files-write.md` - Portal clients can upload files
+- `docs/release-notes/2026-09-29-notes-search.md` - Search notes by their text
+
+## Summary
+
+### Portal clients can upload files
+
+A portal client could not upload through a FuseBase app: the first upload call answered 403
+"Missing required permission: files.write". The client role now holds `files.write`. A client
+may upload and create bucket attachments, and may rename, change or remove only the files it
+uploaded. `deleteFile` is not available to clients.
+
+### Search notes by their text
+
+MCP clients and AI agents could read and edit notes but had no way to find one by its content.
+`searchWorkspaceNotes` searches note titles and text in one workspace, for classic (v2) and
+markdown (v3) notes, using the full-text search note-service already has.
+
+
+## API / SDK Changes
+
+### Portal clients can upload files
+
+- Client role permissions: `files.write` added. Visitor stays read-only.
+- `deleteFile` answers 403 when the caller's organization role is client. A stored-file UUID has
+  no organization and no uploader to check a client against.
+- `updateBucketAttachment` and `removeBucketAttachment`: no change in Gate. bucket-service
+  decides whether the client uploaded the file and its 403 reaches the caller as 403.
+- Op descriptions, MCP `files` prompt (1.15.0), SDK and the Gate files skill reference updated.
+
+### Search notes by their text
+
+- New op `searchWorkspaceNotes`, `GET /:orgId/workspaces/:workspaceId/notes/search` (`notes.read`).
+  Query: `query` (required), `parentId` (search that folder and its subfolders), `limit`
+  (1 to 100, default 20; other values answer 400). `workspaceId` accepts `default`.
+- Each hit: `globalId`, `title`, `parentId`, `workspaceId`, `contentVersion` (`v2` or
+  `markdown_v3`) and `snippet` around the matched words.
+- Never returned: folders, trashed notes (also notes inside a trashed folder), portal-shared and
+  encrypted notes, notes the user cannot read. `markdown_v3` hits need `notes.markdown.read` too.
+- Ranking is keyword full-text, not semantic. No new index.
+- MCP `notes` prompt, SDK `NotesApi`, manifest, OpenAPI and the Gate notes skill reference
+  cover the new op.
+
+
+## Consumer Impact
+
+### Portal clients can upload files
+
+- Same permission name, so deployed apps need no redeploy; an app that lists `files.write` gets
+  it for its client users too.
+- Nothing is tightened for owner, manager, member, guest or app service tokens. Clients never
+  held `files.write`, so the `deleteFile` refusal takes nothing away from a working app.
+- Client uploads work end to end only with the bucket-service release that lets a client create
+  app files (NIM-45207). Before it, a client passes Gate and gets bucket-service's 403, as today.
+
+### Search notes by their text
+
+- New op; nothing changes for existing callers.
+
+
+## Verification
+
+### Portal clients can upload files
+
+- Unit: `tests/unit/permissions.test.ts` (client has `files.write`, visitor does not),
+  `tests/unit/files-controller.test.ts` (client refused on `deleteFile`, member allowed).
+
+### Search notes by their text
+
+- Unit: `tests/unit/notes-controller.test.ts` (trash and portal filtering, `root` search scope,
+  v3 permission rule, limit applied after filtering, invalid limit). Full unit suite green.
+
+
+## Follow-ups
+
+### Portal clients can upload files
+
+- NIM-45213: `deleteFile` has no organization or owner check for any caller.
+
+### Search notes by their text
+
+- Semantic or hybrid ranking, if agents need it, is a separate task.