@zackbart/connecta 0.34.0 → 0.34.1

package/documentation/code-mode.md

@@ -283,7 +283,7 @@ signature is byte-identical to the one `search_tools` returns.
 integration is ambiguous. `safety: "readOnly"` selects stored read verdicts;
 `"approvalRequired"` selects stored write verdicts; omitted or `"all"` selects
 both. Search and describe rows carry `classification`. These filters grant no
-authority and change no call admission decision. On a read-only endpoint,
+authority and change no call admission decision. On a read-only endpoint or connector,
 search and describe omit write tools (`W12`): a write is absent from every
 filter, and describing one is `unknown_tool`. `connecta.skill` guides are not
 filtered and may name such a write; calling it is still refused.
@@ -569,7 +569,7 @@ direct calls; and `input_required_invalid`, `input_required_limit`,
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
 | `unknown_address`            | no visible connector owns the tool address or grants the resource reader                                                                                                                              | false         |
 | `unknown_tool`               | the connector has no such tool                                                                                                                                                                        | false         |
-| `read_only_endpoint`         | a program on a read-only endpoint attempted a write (`E4`)                                                                                                                                            | false         |
+| `read_only_endpoint`         | a program on a read-only endpoint or connector attempted a write (`E4`)                                                                                                                               | false         |
 | `auth_required`              | the credential is missing, expired, or rejected                                                                                                                                                       | false         |
 | `invalid_args`               | arguments or discovery bounds were rejected                                                                                                                                                           | false         |
 | `not_found`                  | the downstream answered and the resource is not there — the one code that says skip this id rather than stop, raised only where the provider tells absence from a permission gap                      | false         |
@@ -594,7 +594,7 @@ direct calls; and `input_required_invalid`, `input_required_limit`,
 sentence. A program cannot recover credentials — only an operator can — so stop
 and let the failure reach the model.
 
-**E4.** A tool classified as a write never runs on a read-only endpoint
+**E4.** A tool classified as a write never runs on a read-only endpoint or connector
 (`W12`). A program's call is refused with `read_only_endpoint` before
 validation and before anything is sent. The refusal carries no `nextAction` and
 echoes no arguments: no route on that endpoint writes, so the program reports
@@ -702,7 +702,7 @@ errors retain their contributing connectors as well.
 Search counts, ranking, and term analysis retain every searched connector,
 including matches outside the returned page or beyond the requested offset.
 Each page rechecks current auth,
-grants, pool membership, and the endpoint's `readOnly`. Reading a stash inside a program carries
+grants, pool membership, and endpoint OR connector `readOnly`. Reading a stash inside a program carries
 its dependencies forward to any new return stash. The page cap is the smallest
 of the deployment cap and contributing connectors' effective `maxResultBytes`.
 Read-only endpoints cannot page write results. A UUID is a handle, never a grant.
@@ -1026,7 +1026,9 @@ sent and records nothing: it was never an attempt (`W9`).
 Whether an endpoint writes belongs to deployment code. Every deployment sets
 `readOnly` for `/mcp` explicitly; construction fails without it. Each named pool inherits
 the deployment's `readOnly` unless it sets its own, in either direction. The
-client owns approval; Connecta answers one question per endpoint: can it write.
+client owns approval. Every connector also accepts optional `readOnly?: boolean`
+(default `false`), enforced on every endpoint. Effective read-only is endpoint OR
+connector; setting connector `false` cannot reopen a read-only endpoint.
 
 ```ts
 createConnecta({

package/documentation/integrating.md

@@ -3,6 +3,21 @@
 Use this guide to change connectors in deployment configuration.
 [All agent routes](./README.md) are in the index.
 
+## Make one connection read-only
+
+Every connector accepts optional `readOnly?: boolean`, defaulting to `false`:
+`remoteMcp("notes", { url: "https://notes.example.com/mcp", auth: { type: "headers", headers: {} }, readOnly: true })`,
+`api("tickets", { readOnly: true, tools: [] })`, and maintained providers such as
+`stripe("billing", { purpose: "Revenue reports", auth: { type: "oauth" }, readOnly: true })`.
+A custom `Connector` sets `readOnly: true` on its connector object.
+
+Only tools classified read appear in search and describe, and every write or
+unclassified tool call is refused before dispatch on every endpoint, including
+maintainers' plain `/mcp`, programs, `call_tool`, and `call_destructive_tool`.
+Effective read-only is endpoint `readOnly` OR connector `readOnly`; connector
+`false` never widens an endpoint. Existing pool/deployment inheritance is unchanged.
+Guides may still name unavailable tools. The operator UI shows a Read-only badge.
+
 ## Add or remove a connector
 
 Connectors are code-owned. Edit the deployment's `src/connecta.config.ts`;
@@ -92,7 +107,7 @@ const tracker = linear("tracker", {
 ```
 
 Linear defaults to OAuth; its read-only endpoint requests only the downstream
-read scope. That is separate from a Connecta `readOnly` endpoint. Read the installed `dist/providers/linear/index.d.ts` for API-key framing,
+read scope. That is separate from Connecta endpoint or connector `readOnly`. Read the installed `dist/providers/linear/index.d.ts` for API-key framing,
 workspace instructions, and admission choices.
 
 The [human README](../README.md#what-you-can-connect) lists available
@@ -107,6 +122,34 @@ pool's `owner` instead ([auth guide](auth.md#pool-owners-for-google-workspace)).
 A request must not choose its own account. Gmail never sends mail, and Drive never permanently
 deletes files.
 
+Intercom uses `intercom()` from `@zackbart/connecta/providers/intercom`:
+
+```ts
+import { intercom } from "@zackbart/connecta/providers/intercom";
+
+const support = intercom("support", {
+  purpose: "Customer support triage",
+  region: "eu",
+});
+// Add support to the deployment's connectors array.
+```
+
+Set `region` explicitly to `"us"` or `"eu"` to match the workspace; AU is
+unsupported. OAuth defaults to personal ownership because it acts as the
+authorizing teammate. Non-loopback OAuth callbacks require an Intercom Customer
+Support allowlist entry for the deployment's redirect URI before authorization
+can complete. Alternatively, set `auth: { type: "credential" }` and connect an
+API token through the [shared credential procedure](./auth.md#connect-a-shared-credential);
+token auth defaults to shared ownership. Fin Operator tools require OAuth,
+workspace availability and teammate permission. Their expected absence adds no
+missing-tool drift; missing core tools still do. Schema coverage reports all
+present reviewed tools as unpinned. Article operations, internal
+notes and Operator actions can write; a note can reopen a snoozed conversation.
+Use a read-only endpoint when writes are unwanted. Catalog review is based on
+[Intercom's docs](https://developers.intercom.com/docs/guides/mcp), with unpinned
+schemas; inspect live tools and the runtime guide before acting on sensitive
+customer data.
+
 Wispr Flow uses OAuth only through `wisprFlow()` from
 `@zackbart/connecta/providers/wispr-flow`. It reaches the authorized account's
 Notetaker content, with personal and work accounts holding separate data.
@@ -116,6 +159,8 @@ reviewed classification includes task writes listed in Claude's directory even
 though Wispr's public help describes read-only access; discover the account's
 actual tools before assuming those writes exist.
 
+For minimal Stripe OAuth/API-key examples with and without connector `readOnly`, see [Stripe setup](./provider-auth-migration.md#stripe). With an API key, prefer a restricted `rk_` key with only read permissions for read-only access; Stripe enforces it too.
+
 Stripe requires `auth`: `{ type: "oauth" }` reaches Stripe's hosted MCP
 server, and `{ type: "apiKey" }` with `mode` reaches Connecta's REST connector
 with an operator-managed key. Notion requires `auth` the same way:
@@ -221,6 +266,15 @@ for precedence, schema digests, and `unlisted: "hide"`. Review the behavior
 before declaring a read, and do not use classification to bypass provider target
 scopes or caller grants.
 
+A reviewed name is required by default for drift comparison. Mark a tool
+`optional: true` only when the downstream can omit it because of plan,
+feature, or permission gating. For example, a remote `crm` connector can use
+`classify: { tools: { list_accounts: "read", list_customers: { verdict: "read",
+optional: true } } }`. Absence of `list_customers` then adds no unserved count;
+when present, its verdict, annotations, and any pinned schema are still checked.
+A missing schema pin means that tool's schema has not been verified against a
+review. Zero schema changes alone does not establish a matching schema.
+
 ## A hand-written HTTP capability
 
 Define only the operations the deployment needs. Every `api()` tool needs a

package/documentation/meta-tools.md

@@ -35,7 +35,7 @@ is annotated `readOnlyHint: true, destructiveHint: false` on a read-only
 endpoint, and `readOnlyHint: false, destructiveHint: true` on a writable one.
 Approval belongs to the client. A read-only endpoint keeps all six tools, omits
 write tools from `search_tools` results and describe, and refuses every write
-call; `readOnly` never changes connector visibility or read grants. Guides
+call. Connector `readOnly` applies the same restriction on every endpoint; effective read-only is endpoint OR connector. Neither setting changes connector visibility or read grants. Guides
 (`queryAnalysis.guideSummary`, `skills`, `connecta.skill`, skill
 `resources/read`) are documentation and may name tools the endpoint refuses. The four tools with structured-only success results
 advertise `outputSchema`. The two direct-call tools omit it because their default
@@ -533,7 +533,7 @@ cap and a 32 KiB program bridge ceiling, with UTF-8 alignment and forward progre
 returning pages unchanged can hit the program result cap. The admitted subject
 and principal, endpoint/pool, request origin, connector, and tool bindings must
 match. The host rechecks current access and whether the endpoint is read-only
-before returning each page; a read-only endpoint cannot read a write stash.
+before returning each page; a read-only endpoint or connector cannot read a write stash.
 Caller arguments select no partition. A read-only endpoint never runs a write,
 so every write result it could page came from a writable endpoint.
 

package/documentation/operating.md

@@ -24,7 +24,7 @@ descriptions. On a writable endpoint, programs and `call_destructive_tool` may
 write within the caller's grants, and `execute_code` is annotated as a write;
 the client controls approval. On a read-only endpoint, search and describe omit
 write tools and every write call is refused with `read_only_endpoint`, even one
-a connector guide names; tell the user rather than looking for another route. Never change pool, identity, or `readOnly` to work
+a connector guide names; tell the user rather than looking for another route. A connector marked Read-only serves only read-classified tools even on a writable endpoint; writes and unclassified tools are omitted from search/describe and refused on every call path. Endpoint and connector restrictions compose by OR. Never change pool, identity, or `readOnly` to work
 around a refusal.
 [Routing between the call surfaces](./meta-tools.md#routing-between-the-call-surfaces)
 owns the full decision rules.

package/documentation/operator-tests.md

@@ -61,7 +61,7 @@ pool member, who gets the member page, with no tabs, on every path.
 | Activity             | No calls                             | Activity              | Member page, no activity request    |
 | Settings             | Snapshot without connectors or pools | Config                | Member page, no configuration facts |
 
-Populated Overview has a failing connector, drift, auth and credential problems
+Populated Overview has a failing connector, auth and credential problems
 and a tokenless agent in its attention list. Populated Endpoints shows who can use each endpoint; populated Tokens has one
 agent per slot state, with pools and last seen.
 
@@ -102,7 +102,13 @@ empty catalog counts zero.
 `test/browser/operator-overview.spec.ts` covers the Overview on the frozen v2
 fixtures: the status pill, stat labels and numbers, map columns, dashed read-only grants and dotted
 tokenless access; attention rows with their fix links, a copied fix prompt equal
-to the catalogue's text and a failing connector sorted first; the hover
+to the catalogue's text, config order through a staggered full refresh, prototype-named
+connector IDs during loading and failure, and stable single-card height when
+its catalog empties. A single long-id, long-title card at 320, 390, 1024 and
+1440px covers all eight status labels, both auth scopes, with and without the
+Read-only badge, tools and an action. Text rows stay single-line, full text
+remains accessible, links stay focusable, and the detail header and Overview
+attention rows retain their height; the hover
 sentence replacing the legend, and dimming; keyboard focus in column order with each node's sentence
 as its accessible name, Enter opening an endpoint's row and a connector; the
 narrow list, whose caller chips link where their map nodes do; an empty deployment; and a member at `/` getting the member page

package/documentation/operator-ui.md

@@ -68,15 +68,16 @@ parameters such as signed handoffs. A pool member sees the
   marks; a tokenless agent's mark is hollow). A dot legend counts each segment
   kind; the first two tiles link to their pages. At 760px and below the tiles
   sit two up, with People · Agents as one row across both.
-- **Needs attention.** One row per connector whose health is not ok, failing
-  first, then one per agent in a pool whose token is missing or revoked. A
+- **Needs attention.** One row per connector whose health is not ok, in
+  configuration order, then one per agent in a pool whose token is missing or revoked. A
   row names the problem ("crm needs authorization"), the endpoints it
   affects ("Affects /mcp and /mcp/team") or the agent URL it can't connect at,
-  and links to the existing fix: Connect, Replace key, Inspect or Review on
+  and links to the existing fix: Connect, Replace key or Inspect on
   the connector's Connection tab, or Issue token on Tokens. A row with a
-  problem code or drift also has Copy fix prompt. A problem keeps its row and
+  problem code also has Copy fix prompt. A problem keeps its row and
   prompt when the connector's detail read failed, prefixed "Details didn't
-  load". With no rows it reads "All clear".
+  load". Surviving connector rows retain their order as individual reads settle,
+  even when their severity changes. With no rows it reads "All clear".
 - **Who reaches what.** The [connection map](#connection-map).
 
 ### Connection map
@@ -134,15 +135,37 @@ cells for the root), guarded grants' live verdicts, and read-only mode.
 ### Connectors
 
 One card per connector: title and id, one status pill, a Shared or Per person
-badge, its tool count over a read and write bar, and when it was last called.
+badge, a Read-only badge when connector `readOnly` is enabled, its tool count over a read and write bar, and when it was last called.
 All, Needs attention and Healthy filter the cards, with counts, beside a
 search field. A connector that is not fine adds one action (Connect, Replace
-key, Inspect, or Review for drift) that opens its Connection tab.
+key or Inspect) that opens its Connection tab.
 
 Every view shares one verdict per connector: the server's problem code first
 (a failed catalog reads "Catalog failed", never "Connected"), then a failed
-detail read ("Couldn't load", with no fix prompt), then a non-ok status, then
-catalog drift.
+detail read ("Couldn't load", with no fix prompt), then a non-ok status.
+Catalog drift is informational: it stays in the connector's Connection panel
+with its fix prompt and in Activity, and never affects health or attention.
+
+Health does not bounce while details load. A connector whose detail read is
+in flight (its `/ui/data` row is `loading`, during sign-in, Retry or a
+connector's Refresh) keeps the verdict the page last showed for it on every
+view (cards, filter counts, the Overview headline, bar, attention list and map,
+Endpoints and the connector page) until that read settles, never "Loading
+details" or an in-between verdict. A connector with no earlier verdict shows
+its contract status. Each connector changes only when its own read settles,
+so one slow read never holds back the others and no row moves for an
+in-between verdict. A new signed-in identity starts fresh. Cards reserve the action footer
+even when no action is needed and the tool bar row even when the catalog is
+empty. Each card header keeps its title, status and id/scope badges on single
+lines; long text truncates with ellipsis and retains its full value on hover
+and for screen readers. The connector detail header and Overview attention
+text follow the same rule, and truncated links remain keyboard focusable.
+Wider status labels never change the card height.
+
+The top bar uses an icon-only Search button (⌘K or Ctrl+K opens the palette).
+Deployment names stay on one line with ellipsis and their full name on hover;
+a name matching the product label is omitted. Tabs scroll horizontally when
+needed, moving to a second row on narrow screens.
 
 A List / Matrix toggle (`?view=matrix`) switches to a table of connectors by
 endpoint, `/mcp` first. A row header is the connector's monogram and name, plus
@@ -181,6 +204,30 @@ tabs:
 - **Activity.** The [Activity](#activity) page for that connector, without
   connector chips or monograms.
 
+#### Read catalog drift
+
+The connector's drift panel reports the last catalog comparison in this
+runtime and identity partition. It never lists tool names or schemas. A
+personal OAuth refresh belongs to that user; another user or endpoint subject
+does not inherit it. A runtime restart or bounded observation eviction resets
+the report until another listing is served.
+
+“No catalog refresh yet” means this partition has no observation. “No reviewed
+baseline” means a listing was observed without a reviewed classification.
+“Matches the reviewed manifest” requires a baseline, successful verification,
+no differences, and schema pins for every live reviewed tool. “Schemas not
+pinned” and “Partial schema coverage” describe missing review evidence; they
+are not clean schema comparisons. “Schema verification unavailable” replaces
+an earlier successful report if hashing fails. Known differences remain visible
+alongside coverage or verification limits. Each operator refresh returns the
+comparison from the catalog it just loaded, including hashing failures and
+schema changes, without another downstream status probe.
+
+The unserved count excludes reviewed names explicitly marked optional for
+plan, feature, or permission gating. Present optional tools still participate
+in annotation and schema comparisons. Dropped tool names are counted even
+without a baseline, and do not establish one.
+
 ### Settings
 
 The configuration snapshot as tiles, tagged "Defined in code", with no
@@ -264,13 +311,13 @@ red when the calls span more than a minute.
 
 The top bar is one row: the mark, branding and deployment name, the section
 links (Overview, Endpoints, Connectors, Activity, Tokens, Settings), then
-Search (the command palette, also ⌘K or Ctrl+K), Appearance, and Account
+icon-only Search (the command palette, also ⌘K or Ctrl+K), Appearance, and Account
 (the signed-in account with Sign out or Change token). The mark is connecta's
 drawn "C" only when no product name, owner or favicon is configured; with
 `branding.favicon.svg` it is that SVG; otherwise there is none. The sign-in
 gate shows the same mark above "Sign in". Below 820px the section links move
 to a second row that scrolls sideways and keeps the current section in view,
-and Search shrinks to its icon. A member's top bar has only branding and
+with Search remaining an icon. A member's top bar has only branding and
 Account. The command palette searches visible pages, connectors and tools,
 opening connector results on Tools.
 

package/documentation/provider-auth-migration.md

@@ -13,6 +13,28 @@ uses one implementation: configure two ids for both.
 
 ## Stripe
 
+## Choose OAuth or an API key
+
+Import `stripe` from `@zackbart/connecta/providers/stripe`. Choose one of two setup paths:
+
+```ts
+// OAuth: Stripe's hosted MCP. Authorize the connection with Stripe.
+stripe("billing", { purpose: "Payments", auth: { type: "oauth" } });
+stripe("billing", { purpose: "Revenue reports", auth: { type: "oauth" }, readOnly: true });
+
+// API key: Connecta's REST connector. Paste the key into this connection in the operator UI.
+stripe("billing", { purpose: "Payments", auth: { type: "apiKey" }, mode: "production" });
+stripe("billing", { purpose: "Revenue reports", auth: { type: "apiKey" }, mode: "production", readOnly: true });
+```
+
+For an API key, set `mode` to `"production"` or `"sandbox"` to match the key.
+Use a secret (`sk_`) or restricted (`rk_`) key. For read-only access, prefer a
+restricted `rk_` key configured with only read permissions: Stripe enforces
+those permissions too. Connecta's `readOnly: true` omits non-read tools and
+refuses their calls on every endpoint. Omit it for the default writable connector;
+endpoint restrictions still apply. OAuth needs no `mode` and can reach both live
+and sandbox accounts through Stripe's account selectors.
+
 Stripe's hosted MCP server stops accepting secret keys and untagged
 restricted keys on 2026-10-31; Stripe still documents agent-tagged restricted
 keys for it. Connecta's hosted Stripe connection is OAuth only either way, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.34.0",
+  "version": "0.34.1",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of six meta-tools.",
@@ -114,6 +114,10 @@
       "types": "./dist/providers/infisical/index.d.ts",
       "import": "./dist/providers/infisical/index.js"
     },
+    "./providers/intercom": {
+      "types": "./dist/providers/intercom/index.d.ts",
+      "import": "./dist/providers/intercom/index.js"
+    },
     "./providers/linear": {
       "types": "./dist/providers/linear/index.d.ts",
       "import": "./dist/providers/linear/index.js"

package/templates/node/package.json

@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.34.0",
+    "@zackbart/connecta": "0.34.1",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {