@jskit-ai/connectors-catalog 0.1.1

package/docs/microsoft-teams.md

@@ -0,0 +1,72 @@
+# Microsoft Teams
+
+Provider ID `microsoft-teams`; export `microsoftTeamsProvider` from
+`@jskit-ai/connectors-catalog/server/microsoft-teams`.
+
+Follow all [Microsoft registration steps](microsoft-oauth.md), selecting
+**Multiple Entra ID tenants**. This module uses the `organizations` authority;
+personal Microsoft accounts are unsupported. Under **API permissions → Microsoft
+Graph → Delegated permissions**, add `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `User.Read` and `offline_access`.
+The form requires team/channel/profile reads. Optional channel send and all-user
+profile read start selected; clear them for listing teams only. Channel-message
+read and chat read/write are also available. The operations below use these permissions separately; `teams.list` itself uses only `Team.ReadBasic.All`.
+The user's organization must provide Teams access and permit consent.
+
+`teams.list` verifies access with `GET /v1.0/me/joinedTeams`. Verification input
+is `{}`. This endpoint does not support OData query parameters, so this fragment
+does not offer page size, search or filter controls. It returns the `value`
+array of teams in which the signed-in user has direct membership. Shared-channel
+access does not necessarily imply that the host team appears here. That listing does not itself read/send messages; use the separate operations below. Team creation and membership changes remain unsupported.
+[Joined teams API](https://learn.microsoft.com/en-us/graph/api/user-list-joinedteams?view=graph-rest-1.0).
+
+The common continuation input is accepted only for a same-resource provider
+link if one is returned; do not manufacture a Teams paging URL. The fragment
+does not introduce query parameters on its initial request.
+
+AI provisioning is **API-capable after authorization** using Graph application
+creation and credential endpoints. Apply the audience and delegated permissions
+above. Administrator consent and tenant restrictions remain provider-controlled.
+The application owner supplies its registration and private Env bindings using
+the common guide. Separate registrations do not remove overlapping tenant/service
+limits.
+
+Use the common JSON/file-store pattern from a CLI or backend. Automated tests
+verify the organization endpoint, exact permission, query-free initial request,
+scope denial, cancellation, refresh, isolation and encrypted persistence. Live
+Teams usage and generated applications are excluded.
+
+## Editor credential handoff
+
+The inline guide covers Entra registration/audience, exact Web redirect,
+delegated permissions and administrator consent, secret Value versus Secret ID,
+and rotation. Save `env:MICROSOFT_TEAMS_CLIENT_SECRET` and
+`env:MICROSOFT_TEAMS_CALLBACK_URL`, then use **Set credential in Env** and
+**Open Env** for their values. Shared/assistant **Connect account** uses the
+prepared project runtime. Per-user connections belong to authenticated users
+of that app. No Vibe64 gateway or editor-owned provider registration is used.
+Local disconnect does not revoke provider consent.
+
+## Conversations in CLI and generated apps
+
+`channels.list({teamId})` requires Channel.ReadBasic.All.
+`messages.list({teamId,channelId,pageSize?})` and
+`replies.list({teamId,channelId,messageId})` require ChannelMessage.Read.All.
+`messages.send({teamId,channelId,text})` and
+`replies.send({teamId,channelId,messageId,text})` require ChannelMessage.Send.
+Existing chats use `chats.list({})`, `chatMessages.list({chatId,pageSize?})` and
+`chatMessages.send({chatId,text})` with Chat.ReadWrite. Retain returned resource IDs
+and same-resource nextLink values. Text sends are bounded to 20,000 characters.
+
+App authorization must approve the destination and text; connected permissions
+are not permission to expose an unrestricted send endpoint. Do not blindly retry
+uncertain sends. Sanitize returned HTML before rendering. JSKIT CLI apps call the
+same connection service; other frameworks use Graph and their own Env/grant store.
+
+**LIMITATIONS:** No team/chat creation, membership administration, message edit/delete,
+attachments, meeting bot or editor tool attachment. Example: read a channel and
+post a status update, not a Teams client or automatic team administrator. No live
+provider or generated-app proof.
+
+[Channel messages](https://learn.microsoft.com/en-us/graph/api/channel-list-messages?view=graph-rest-1.0),
+[channel send](https://learn.microsoft.com/en-us/graph/api/channel-post-messages?view=graph-rest-1.0),
+[chat send](https://learn.microsoft.com/en-us/graph/api/chat-post-messages?view=graph-rest-1.0).

package/docs/microsoft-word.md

@@ -0,0 +1,119 @@
+# Microsoft Word
+
+Provider ID `microsoft-word`; export `microsoftWordProvider` from
+`@jskit-ai/connectors-catalog/server/microsoft-word`. This initial adapter browses
+document files and folders in the connected account's default drive, and reads
+file metadata. It does not read or edit document contents, download files,
+execute macros, create files or change sharing. A filename extension identifies
+a candidate file; it is not a check of the file's actual format.
+
+## Registration and configuration
+
+Follow the complete [Microsoft registration steps](microsoft-oauth.md).
+Use **Any Entra ID Tenant + Personal Microsoft accounts** with `common`, or the
+matching organizational, personal-only or single-directory option in that guide.
+For one directory, copy **Directory (tenant) ID** into `settings.tenantId`.
+Under **API permissions → Add a permission → Microsoft Graph → Delegated
+permissions**, select `Files.Read` and `offline_access`. Then configure the
+Web callback, create a client secret and store its Value through the referenced
+Env variable. Use an account with an existing drive; JSKIT does not provision it.
+
+```json
+{
+  "schemaVersion": 1,
+  "integrations": {
+    "files": {
+      "provider": "microsoft-word",
+      "accountMode": "per-user",
+      "scopes": [
+        "Files.Read",
+        "offline_access"
+      ],
+      "settings": {
+        "tenantId": "common"
+      },
+      "authentication": {
+        "method": "oauth2",
+        "registrationRef": "microsoft"
+      }
+    }
+  },
+  "registrations": {
+    "microsoft": {
+      "source": "own",
+      "clientId": "YOUR_APPLICATION_CLIENT_ID",
+      "clientSecretRef": "env:MICROSOFT_CLIENT_SECRET",
+      "callbackUrlRef": "env:MICROSOFT_CALLBACK_URL"
+    }
+  }
+}
+```
+
+The same values are editable in Vibe64: display name, account ownership, tenant,
+Client ID, secret/callback references and the two permission choices. Saving the
+file does not open provider consent. The [OAuth composition pattern](../patterns/oauth-connection/PATTERN.md)
+uses the library for consent, private encrypted text storage and runtime access.
+A per-user slot uses the app's authenticated subject. A shared slot uses the
+host's membership policy and stable shared subject; it is a shared account.
+
+## Runtime operations
+
+- `items.list`: optional `folderId`, `pageSize` (1–100, default 25) and `nextLink`.
+  Without `folderId`, reads `/v1.0/me/drive/root/children`; otherwise reads
+  `/v1.0/me/drive/items/{folderId}/children`. Keeps folders and files whose
+  extensions are doc, docx, docm, dot, dotx, dotm, case-insensitively.
+- `items.get`: required `itemId`, reading `/v1.0/me/drive/items/{itemId}`.
+  Returns a matching file's metadata. Other file types and folders produce
+  `connector_document_type_invalid`.
+
+Both operations require `Files.Read`. IDs must be opaque item IDs, not paths or
+URLs. Selected metadata includes ID, name, size, web URL, file/folder facets,
+parent reference, last modification time and ETag. The adapter does not follow
+returned URLs. [Graph children API](https://learn.microsoft.com/en-us/graph/api/driveitem-list-children?view=graph-rest-1.0),
+[Graph item API](https://learn.microsoft.com/en-us/graph/api/driveitem-get?view=graph-rest-1.0).
+
+`items.list` verifies a new connection with input `{}`. Its page size bounds the
+upstream page before local file filtering. A filtered page can be empty and
+still have `@odata.nextLink`: retain that link and pass it with the same folder
+input to continue. It is not a recursive search or an automatic full-drive scan.
+Next links cannot change Graph origin or the selected resource path.
+
+## Application registration and AI provisioning
+
+AI provisioning is **API-capable after operator authorization** using the
+application and credential endpoints in the common guide. Registration remains
+separate from account consent and tenant administrator policy.
+
+Register the callback served by this application's backend. Store its exact URL
+and client secret in application environment bindings. The same setup works with
+a CLI, installed editor or hosted editor; none supplies a shared registration.
+See the [callback guide](../../connectors-core/docs/oauth-callbacks.md) for domain
+changes and reconnect behavior. Keep the selected Microsoft tenant/audience
+consistent with the provider registration.
+
+## Evidence and limits
+
+Focused fixtures cover consent, cancellation, encrypted restart, refresh,
+reduced permissions, owner isolation, tenant changes, folder paging, empty
+filtered pages, metadata validation and controlled provider failures. Provider
+HTTP is simulated. No live account, provider registration or generated app is
+used. Provider-console administration and live account acceptance remain outside
+this fixture evidence.
+
+## Editor credential handoff
+
+The inline guide supplies Entra registration, account audience, Web callback,
+delegated permissions, secret Value and expiry steps. Save
+`env:MICROSOFT_WORD_CLIENT_SECRET` and `env:MICROSOFT_WORD_CALLBACK_URL`;
+use **Set credential in Env** and **Open Env** to store the values.
+Shared/assistant **Connect account** invokes the prepared application runtime.
+Per-user connections belong to individual users inside that application.
+No Vibe64 gateway or shared registration is used.
+
+## Existing-scope closeout — 13 September 2026
+
+Delegated project-owned OAuth browses default-drive folders and Word candidate filenames and fetches selected file metadata, with bounded paging, tenant/audience configuration and refreshed private grants.
+
+No document content reading, creation/editing, upload/download, conversion, macros, sharing, recursive search, arbitrary drive/site selection or document format validation. Filename extension filtering is not content inspection; filtered empty pages can still have a continuation. No app-only/client-credentials or device-code grant, application login or automatic remote consent revocation. The app owns callback routes, account connection UI, authorization and file-picker/pagination behavior. Exact Lovable shared-form fields/scopes remain unverified because the saved shared-form reference is a loading placeholder. To extend: choose supported native document tooling, implement content/file transfers with conflict and format preservation tests; do not invent Graph document-editing endpoints. No live provider account, provider registration, paid request or generated-application execution was tested. No new editor coding-assistant tool attachment is claimed. Other frameworks use the same project configuration and their own native tools; JSKIT is optional.
+
+7 provider-specific source and 7 installed-package cases passed, plus 2 shared Microsoft tenant checks in each 16-test Word/PowerPoint run on September 13. September 12 rendered guidance/form/lifecycle evidence at 496px is retained; no new phone or browser run.

package/docs/miro.md

@@ -0,0 +1,117 @@
+# Miro assistant MCP
+
+Checked against Miro's public documentation and discovery metadata on 9 September
+2026. This fragment connects an assistant owner's selected Miro team, discovers
+tools and calls explicitly authorized tools. Its fixed HTTP endpoint is
+`https://mcp.miro.com/`, including the trailing slash.
+
+## Registration and consent steps
+
+1. Read [Connecting to Miro MCP](https://developers.miro.com/docs/connecting-to-miro-mcp).
+   A user signs into Miro and selects the team containing the intended boards.
+   This MCP client registration is separate from creating a REST API application
+   in **Your apps**; those credentials are not interchangeable.
+2. Choose the actual callback served by your assistant backend or CLI host.
+   Use HTTPS for a remote host; use a loopback callback only where the provider
+   accepts that client setup.
+3. Invoke `registerMiroClient` once from an authorized setup command. Pass the
+   client name, callback and selected scopes. It uses Miro's advertised dynamic
+   registration endpoint, requests `client_secret_post`, and returns the client
+   ID, secret and any reported secret-expiry timestamp.
+4. Store the secret in the host's secret/environment facilities. Write the client
+   ID, secret reference and callback reference into the portable registration.
+   Never put the secret value in the configuration JSON.
+5. In Vibe64, select **Integrations → Add Miro**. Enter **Client ID**, **Client
+   secret reference** and **Callback URL reference**. Keep **Assistant access**.
+   **Read boards** starts selected; enable other permissions only as needed.
+   The **OAuth client registration** panel supplies the endpoint and raw JSON
+   POST body for the current callback/scopes. Send it once from your HTTP client
+   or use the helper above. Select **Save configuration**, then **Set credential
+   in Env** for `MIRO_CLIENT_SECRET` and **Open Env** for `MIRO_CALLBACK_URL`.
+   **Connect account** invokes the prepared application runtime; saving alone
+   does not register or authorize an account.
+6. The host begins authorization and opens the returned URL. Sign in, review the
+   requested access, and select the appropriate Miro team. Complete the callback
+   under the same authenticated owner. The runtime discovers available tools
+   before storing the connection.
+7. To switch teams, reconnect and choose the new team during provider consent.
+   Discovering tools does not prove access to any particular board. Team and
+   organization administrators can restrict access even when a client is valid.
+
+Miro's connection guide documents the **Connect**, sign-in, team-selection and
+**Continue** flow. A custom host supplies its own equivalent connect action;
+the provider controls its account and team screens.
+
+## Fields and operations
+
+| Field | Meaning |
+|---|---|
+| Client ID | Assigned by MCP dynamic registration |
+| Client secret reference | Reference to the confidential registration's secret |
+| Callback URL reference | Reference to the exact backend redirect URI |
+| `boards:read` | Board read permission; selected initially |
+| `boards:write` | Board writes; initially unselected |
+| `openid` | Identity scope; initially unselected |
+| `email` | Email scope; initially unselected |
+
+These fields follow the
+[authorization metadata](https://mcp.miro.com/.well-known/oauth-authorization-server)
+and [resource metadata](https://mcp.miro.com/.well-known/oauth-protected-resource).
+The issuer/resource is `https://mcp.miro.com/`; its `/authorize`, `/token` and
+`/register` endpoints belong to the same server. The existing OAuth runtime
+binds the resource to code and refresh requests. Identity scopes do not turn
+this connector into the application's login system.
+
+Import `miroProvider` and `registerMiroClient` from
+`@jskit-ai/connectors-catalog/server/miro`, then use the
+[assistant OAuth pattern](../patterns/assistant-mcp-oauth/PATTERN.md):
+
+```js
+const registration = await registerMiroClient({
+  clientName: "My board assistant",
+  callbackUrl: configuredCallback,
+  scopes: ["boards:read"]
+});
+```
+
+The host stores the result privately. `tools.list` returns current tool schemas;
+`tools.call` requires the host's exact name/argument authorization. For example,
+a host can allow the documented `board_search_boards` tool and validate its
+query, then authorize board-specific reads separately. Do not infer write
+approval from granted OAuth scopes or the presence of a tool in discovery.
+Use Miro's current [tool reference](https://developers.miro.com/docs/miro-mcp-tools)
+when composing calls; tool availability evolves, and the library does not pin a
+second copy of the remote tool catalogue. Returned `isError` stays observable.
+
+## Connection ownership and callbacks
+
+Register the real callback implemented by the runtime that owns this connection.
+For an application integration, use the application's assigned hosting URL as
+the initial origin and its implemented callback path. Store the exact callback
+in its Env reference and provider registration. A domain change requires updating
+both values if the callback URL changes; retain the application identity and its
+persistent grants when moving hosts. Public Vibe64, Online and CLI users supply
+their own registrations through this same contract.
+See the [callback guide](../../connectors-core/docs/oauth-callbacks.md).
+
+The application or explicitly authorized assistant host owns the client secret
+and grants. Each user still selects a team and grants access. Separate client
+IDs do not establish separate team capacity, entitlements or billing limits.
+
+## Automation assessment and proof
+
+Miro documents OAuth with dynamic registration in its
+[MCP overview](https://developers.miro.com/docs/miro-mcp). The helper can create
+the registration after a privileged caller authorizes setup; AI can assemble
+configuration, callback handlers and tool policy. Sign-in, consent, team choice
+and any administrator approval remain external actions. The helper never
+retries an ambiguous registration automatically.
+
+Focused tests use simulated provider replies and real encrypted files for
+registration, PKCE, refresh after restart, replay, ownership, discovery,
+tool policy, safe HTTP failures and cancellation. No live registration,
+consent, board read/write or sample application was exercised. Managed
+assignments, automatic assistant attachment and application login remain
+outside this fragment.
+
+**LIMITATIONS (accepted deferral):** Automatic Vibe64 Codex/OpenCode attachment is deferred. Example: a wired CLI/assistant host may discover and authorize a board read or diagram tool, but connecting here does not make the board available in Vibe64 chat. No embedded board editor. Fixture board/diagram names are controlled test inputs, not claims about current remote tool names. Live board access remains unproven.

package/docs/n8n.md

@@ -0,0 +1,169 @@
+# n8n assistant MCP connection
+
+Import `n8nProvider` from `@jskit-ai/connectors-catalog/server/n8n`. Configure
+`accountMode: "assistant"`, `authentication.method: "api-key"`, an environment
+`secretRef`, empty `scopes`, and `settings.serverUrl`. The shared validator
+requires a final HTTPS endpoint ending `/mcp-server/http`; installation paths
+and explicit ports are retained. Display name is the common integration field.
+
+## Manual setup
+
+1. Open **Settings → Instance-level MCP** as an owner/admin and enable access.
+2. Open **Connection details → Connect → API key**. Copy **Server URL** and the
+   personal token into the URL setting and secret environment respectively.
+   Older releases label the token tab **Access Token**.
+3. Review **Workflows exposed** and enable only the intended workflows.
+4. Keep `env:N8N_API_KEY` as the reference, select **Save configuration**,
+   then **Set credential in Env** for the token. Select **Connect account**
+   to verify discovery; the assistant separately authorizes individual tool calls.
+5. To expose a workflow, choose **Workflows exposed → Enable workflows**,
+   select it and **Enable**, or use its **… → Settings → Available in MCP**.
+   Check workflow eligibility and user access. Search may return previews of
+   other workflows visible to that user; exposure is not isolated per client.
+
+Use the [n8n setup guide](https://docs.n8n.io/connect/connect-to-n8n-mcp-server)
+for version-specific screens and token rotation. A REST API key is a different
+credential. Rotating this personal token revokes its predecessor.
+
+## Runtime and ownership
+
+`connectApiKey` performs initialization and `tools/list`, never a workflow call.
+`tools.list` accepts an optional opaque `cursor`; `tools.call` requires `name`
+and an `arguments` object. Results retain MCP content, `isError`, tool schemas
+and pagination. Tool errors are data; protocol/HTTP failures use safe connector
+errors. No automatic tool selection or execution occurs.
+
+The application policy receives the requested tool and arguments before any
+HTTP request. Apply the assistant's delegated authority there, and treat tool
+descriptions/results as untrusted external content. Every call gets a temporary
+MCP session; cleanup attempts DELETE and closes local streams. Operations have
+the core's 15-second bound. Cancellation does not undo a workflow already
+accepted remotely, and connection discovery does not establish every permission.
+
+Private HTTPS instances are intentionally permitted in trusted configuration;
+the runtime host owns outbound-network restrictions. It contacts only the exact
+configured endpoint and never follows redirects, metadata links or returned
+URLs. Changing the URL requires verification again. Tokens and sessions are
+not copied into project source; existing encrypted file storage owns grants.
+
+## Automation and application ownership
+
+AI can compose this configuration and runtime wiring once supplied an authorized
+token. This fragment provides no API for enabling MCP or issuing its initial
+token; provisioning remains manual. OAuth client provisioning is available through `registerN8nClient` below;
+instance access policies and actual provider consent still apply.
+
+This token mode has no OAuth app ID. The application owner supplies a credential
+for its n8n instance through private Env. Separate credentials give attribution
+and revocation; they do not demonstrate independent capacity on the same instance.
+Independent capacity requires separate instances or appropriate usage limits.
+
+## Proof and limits
+
+`test/mcp.test.js` uses the real SDK, JSON/SSE response fixtures and encrypted
+file storage to exercise discovery, tool calls, input policy, restart, rotation,
+changed destinations, isolation, failure handling and cancellation. The editor
+test checks the same URL/reference fields and reload. `test/n8nOAuth.test.js`
+exercises OAuth with controlled discovery, registration and token responses.
+Automatic assistant attachment, stdio, resources/prompts, live n8n and generated
+apps are not tested.
+
+## Remaining authorization parity
+
+n8n also supports OAuth. The captured Lovable flow accepts only the server URL
+and offers Add & authorize. The runtime supports personal tokens and
+OAuth. The editor offers explicit discovery and Register client and connect,
+which registers a client, saves configuration and Env, then invokes the
+application-owned connection flow. Manual registration remains available. The token path
+requires no client registration or callback.
+
+## OAuth discovery helper
+
+`discoverN8nOAuth({ serverUrl }, { fetchImpl, signal })` is exported from the
+same server entry point. It returns `{ resource, oauth, scopes }` after reading
+the MCP protected-resource and authorization-server metadata through the existing
+SDK. It does not register a client, send credentials or open consent.
+
+The exact configured resource must match discovery. A single HTTPS issuer is
+required, but it can use a different hostname and installation path. The helper
+validates n8n's advertised /mcp-oauth endpoints, S256, refresh and confidential
+client_secret_post support. Scopes come from discovery, not a hardcoded universal
+list. Failed discovery requires correcting the instance/URL; it does not guess
+an OAuth authority from the MCP hostname. Trusted callers own outbound-network
+policy, including access to private instances. Requests omit credentials, reject
+redirects and share a 15-second cancellation bound.
+
+The editor exposes Discover OAuth settings for n8n. The provider uses saved discovery
+as described below. Focused discovery tests
+cover split hosts and paths, inconsistent metadata, bad inputs and cancellation.
+
+## OAuth client registration helper
+
+`registerN8nClient({ serverUrl, clientName, callbackUrl, scopes }, options)`
+validates setup inputs, performs discovery and submits one confidential-client
+registration using the existing MCP registration helper. Select a nonempty
+subset of advertised resource scopes. Unsupported scopes fail before POST;
+ambiguous failures are not retried. The privileged host owns authorization to
+register and private storage of the returned secret.
+
+The result includes clientId, clientSecret, optional clientSecretExpiresAt,
+resource, oauth metadata, advertised scopes and the separate requestedScopes.
+Advertised scopes are not consent or the permissions to save automatically.
+Use the selected requestedScopes for the application's intended configuration.
+Never copy the whole result into public JSON: put the secret in Env and retain
+only its reference. Registration does not connect an account. The editor can register and store credentials through its explicit action,
+or display the endpoint and request body for manual registration.
+
+
+## Saved OAuth configuration and runtime
+
+For OAuth, save only `{ resource, oauth, scopes }` from discovery/registration as
+`integrations.<id>.settings.oauthDiscovery`, alongside `settings.serverUrl`.
+Use the same exact resource URL for `serverUrl`. This is public metadata; never
+save the complete registration response here. The shared schema validates the
+endpoints, protocol capabilities and advertised scope names. OAuth becomes an
+available authentication method when discovery settings are present.
+
+Create an ordinary project-owned registration with the returned `clientId`,
+`clientSecretRef: "env:N8N_CLIENT_SECRET"` and
+`callbackUrlRef: "env:N8N_CALLBACK_URL"`. Put the secret and exact registered
+callback in private Env. Choose `authentication.method: "oauth2"`, reference
+that registration, and put only the selected `requestedScopes` into the
+integration's `scopes`. Advertised permissions are choices, not automatic grants.
+
+Use `n8nProvider` with the existing `createConnectionService`, project-owned
+store, reference resolver and authorization policy. `beginAuthorization` uses
+the saved authority, selected scopes, S256 and exact resource. Serve the
+callback in the application's backend and call `completeAuthorization` there.
+The common runtime checks consent, stores encrypted grants and refreshes them
+when necessary. It does not rediscover endpoints during token refresh or follow
+metadata advertised by a tool response. A changed server URL requires fresh
+matching discovery before consent. Revoke provider access in n8n separately
+from removing a local connection.
+
+The focused OAuth fixture proves consent, callback exchange, tool discovery,
+restart/refresh and rejection of changed resources and malformed saved metadata.
+It makes no live provider requests. CLI applications can use this runtime now;
+the editor can discover settings and register a client explicitly.
+A live n8n deployment and real consent remain untested.
+
+
+In the editor, enter Server URL and select **Discover OAuth settings**. Choose
+**OAuth** in **Authentication**, then open **Permissions** and select the needed
+scopes. Open **Set up n8n** for the complete steps. Its **OAuth client
+registration** section provides a copyable endpoint and JSON body with the
+current callback and selected scopes. Alternatively choose Register client and connect with a new registration and
+unused Env keys. This action saves the client and Env, then starts the normal
+application-owned connection flow. For manual registration, send the request
+once, enter its returned client ID, save and configure Env yourself.
+
+Discovery requires the instance to advertise at least one supported permission.
+Versions without that contract can use the personal-token path. Saved metadata
+contains public endpoints and permission names only. Selecting a new slot,
+changing the URL or editing the draft while discovery runs prevents a stale
+response from replacing the new draft. Discovery does not write a file until
+Save configuration, and it neither reads nor writes Env.
+
+## Accepted limitations
+
+LIMITATIONS: Automatic Vibe64 coding-chat attachment is deferred. A separately wired CLI or assistant host can discover and invoke exposed workflows through MCP after approving the exact tool and arguments; connecting alone does not attach chat tools. This connector is not the n8n REST API or a workflow designer. Example: an approved host can start an exposed report workflow and receive its result, but saving this connection alone does not let Vibe64 chat start that report. Workflow tools and schemas come from discovery, not a fixed catalogue. Fixture execution is not proof of a live workflow run.

package/docs/notion.md

@@ -0,0 +1,137 @@
+# Notion
+
+Import `notionProvider` from `@jskit-ai/connectors-catalog/server/notion`.
+This adapter accepts an internal connection token using `api-key`, or a
+project-owned public connection using `oauth2`. It pins
+`Notion-Version: 2026-03-11`. Hosted Notion MCP uses a separate connection mode and client registration.
+Its controlled editor journey is verified; live consent remains untested.
+
+## Set up access
+
+1. Open [Notion's Developer portal](https://www.notion.so/profile/integrations)
+   with permission to create a connection in the intended workspace.
+2. In **Build → Internal connections**, choose **Create a new connection**, enter
+   a name, and select the installation workspace.
+3. In **Configuration**, enable **Read content** and copy the **Installation
+   access token**. Store the connection token outside application source
+   as `NOTION_API_KEY`.
+4. Use **Content access → Edit access**, or on a page open **••• → Connections →
+   + Add connection**. Select the connection and intended content. Parent access
+   includes children. An internal connection is workspace-specific.
+5. In `integrations.json`, select provider `notion`, mode `shared` or `assistant`,
+   empty `scopes`, and authentication method `api-key` with secret reference
+   `env:NOTION_API_KEY`. No client registration or callback is needed for this mode.
+6. Verify using `connectApiKey`; it performs a title search. Follow the
+   [internal connection guide](https://developers.notion.com/guides/get-started/internal-connections)
+   and [content authorization instructions](https://developers.notion.com/guides/get-started/authorization).
+
+## Runtime and AI composition
+
+`content.search` accepts `query`, `page_size` (1–100), and `start_cursor` and
+returns the provider's list envelope, including `has_more` and `next_cursor`.
+This is title search over accessible pages/data sources, not arbitrary full-text
+search. `identity.read` returns the token's user; the response may describe a
+bot or a person. See [Search](https://developers.notion.com/reference/post-search)
+and [Token identity](https://developers.notion.com/reference/get-self).
+
+Apply the [API-key source pattern](../patterns/api-key-connection/PATTERN.md)
+with this provider. The application owns which callers may search the shared
+workspace. It supplies the same JSON file whether configured by a CLI or UI.
+Page content, product screens and any writes remain separate application work.
+
+## Provisioning automation and capacity
+
+An AI can prepare the library wiring and configuration; these ordinary internal
+connection instructions still require a workspace operator to create the token
+and share content. This pass has not verified an administrative API that creates
+equivalent connections across arbitrary workspaces. Do not infer that from
+Notion's content API or use undocumented console endpoints.
+
+Each application supplies its intended Notion connection. Check provider limits
+for that connection/workspace; different names do not prove isolated capacity
+or permit one workspace's data to be shared with another. Unrelated app users require the separate public OAuth mode.
+
+Fixtures cover version headers, JSON search bodies, cursors, file restart,
+credential rotation, owner isolation, and rejected or malformed responses.
+No Notion workspace was connected during testing.
+
+## Public OAuth connection
+
+Use [Notion's public connection guide](https://developers.notion.com/guides/get-started/public-connections)
+and the inline OAuth setup instructions. In the Developer portal choose
+Build → Public connections, create the connection with its installation scope,
+Read content capability and exact application callback, then retrieve the client
+ID and secret from Configuration. Store the secret and callback in Env.
+
+The JSON registration uses source `own`, `tokenEndpointAuthMethod`
+`client_secret_basic`, `clientId`, `clientSecretRef` and `callbackUrlRef`.
+The integration uses method `oauth2`, `registrationRef`, empty `scopes` and the
+intended shared/per-user account mode. The app owns its callback route and uses
+`beginAuthorization`, `completeAuthorization`, `invoke` and `disconnect` from
+the common connection service with its authorized owner and configured storage.
+Laravel implements the same provider protocol in its own framework; JSKIT
+contains no PHP runtime. Vibe64 edits this configuration and the project's Env.
+
+The adapter sends owner=user and the exact callback at authorization. It uses
+confidential Basic authentication and JSON requests at the token endpoint, per
+[Notion's authorization guide](https://developers.notion.com/guides/get-started/authorization).
+PKCE is disabled for this documented confidential flow; common state checks
+and single-use attempts remain active. API requests include the pinned version.
+The runtime retains rotated refresh tokens and refreshes expiring grants using
+the existing lifecycle. No artificial expiry is invented when the provider
+omits it; that case follows the common runtime's non-expiring-token behavior.
+
+The controlled OAuth test covers request encoding/authentication, callback,
+replay rejection, two refresh rotations across storage restart, version headers
+and another app user's denied access. Browser coverage, hosted MCP and live
+Notion consent remain unproven. This is data authorization, not app login.
+
+## Hosted assistant MCP
+
+Set `settings.connectionType` to `mcp` (default `rest`). Select account mode
+`assistant`, OAuth with a separate own registration using `client_secret_post`,
+and scope `default`. `registerNotionMcpClient({clientName, callbackUrl}, options)`
+uses the existing bounded registration helper; the caller owns authorization
+and secret storage. Never reuse REST client credentials.
+
+Notion's [MCP metadata](https://mcp.notion.com/.well-known/oauth-authorization-server)
+provides the separate authority. The runtime uses S256, form token requests and
+https://mcp.notion.com/mcp. Verification initializes MCP and lists tools;
+`tools.call` requires the host's authorization of the exact name and arguments.
+Use the ordinary connection service in assistant execution mode for assistant
+permission enforcement. This mode exposes no REST operations.
+
+The editor's Connection type field switches the credential family and creates
+a new OAuth registration slot. It offers assistant-only ownership and the MCP
+setup instructions, including a manual registration request and Env handoff.
+Controlled tests cover registration, an ambiguous registration failure without
+retry, separate endpoints, PKCE, encoding, refresh after restart and tool
+discovery. Controlled browser verification covers all three modes, their setup links,
+credential separation, failure recovery and reload. Live consent is untested.
+
+## Content operations and native-framework composition
+
+The same project-owned connection service now exposes pages.get, databases.get,
+dataSources.get, blocks.list, dataSources.query, pages.create, pages.update and
+blocks.append. Use database.data_sources to select a source, then read its schema.
+Query with id, page_size/start_cursor and optional provider-shaped filter/sorts.
+Read nested blocks separately while has_children; follow has_more/next_cursor.
+Create pages with parentId, parentType (page_id or data_source_id), properties
+and optional children. Update properties by page id; append children by block/page id.
+Documents are bounded to64KiB; append batches1–100 blocks,256KiB total.
+Read content capability is required; Insert content permits creation/append,
+Update content permits property edits. Grant access to the parent pages as well.
+Connection verification still only searches, never writes. Approval and rendering
+belong to the app; an uncertain write is not automatically repeated.
+
+CLI JSKIT uses service.invoke with these operations and the same file/Env config.
+Other frameworks implement these documented requests using their native Notion
+client and app-owned credential storage; this library contains no PHP code.
+Example: pages.create can add a meeting note, then blocks.append adds an action.
+**LIMITATIONS:** No embedded Notion editor, database/schema administration, file
+uploads or automatic coding-chat attachment. Nested paging/rendering is app-owned.
+Controlled fixtures, not live workspace or generated-app execution.
+
+References: [data sources](https://developers.notion.com/guides/get-started/upgrade-guide-2025-09-03),
+[create page](https://developers.notion.com/reference/post-page),
+[append blocks](https://developers.notion.com/reference/patch-block-children).