@zackbart/connecta 0.33.0 → 0.34.1

package/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 All notable changes to this package are documented here.
 
+## 0.34.1 — 2026-10-19
+
+Connecta 0.34.1 is a patch release with a security fix. The Cloudflare provider passed stored AI Search crawler headers through unredacted, including on the routes 0.34.0 already served, so any caller allowed to read those resources could see header values that may carry credentials. 0.34.1 withholds them, along with conditional firewall match credentials, Vercel daemon probe headers, setup-form defaults and payment client secrets, and refuses Cloudforce One match responses that have no published schema before any request is sent. Deployments that use the Cloudflare or Vercel providers should upgrade.
+
+Connectors can now set `readOnly: true` (#895). A read-only connector serves only reviewed reads on every endpoint, maintainers' plain `/mcp` included; write and unclassified tools are hidden from discovery and refused on every call path. It combines with endpoint and pool `readOnly`, and the default is unchanged. The Stripe guide now shows both setups side by side: OAuth to Stripe's hosted MCP, or a secret or restricted key through the REST connector, with or without `readOnly`. A new maintained Intercom provider supports personal OAuth or a shared bearer token in the US or EU region; its schemas are not pinned yet because Intercom's catalog requires authentication to list.
+
+Catalog drift no longer counts as connector health (#867): a drifted connector reads Connected and stays out of Needs attention, while drift details remain on the connector page and in Activity. Connector cards, counts and the attention list keep their last verdict and position while details reload, and the top bar is more compact. Drift detection itself is corrected (#884): reordered schema arrays no longer report false changes for schemas pinned in the new format (existing pins keep their original hashing until re-reviewed), plan-gated tools can be marked optional, schema coverage is reported honestly, failed fingerprints mark verification unavailable instead of keeping a clean report, and per-person connectors keep separate observations. The Linear, Mixpanel, RevenueCat and Stripe reviews are reconciled with their live hosted catalogs and pin schemas; Mixpanel's Get-Events, Get-Dashboard, List-Cohorts and Get-Metric serve as reads again without deployment overrides, so a `classification: { mixpanel: { "Get-Events": "read" } }` override can be removed. Upgrading from 0.34.0 needs no configuration, storage migration or token rotation.
+
+### Added
+
+- Add a maintained Intercom hosted MCP provider with explicit US/EU region selection, personal OAuth or shared bearer-token auth, reviewed tool classifications, and guidance for sensitive support data and optional Fin Operator actions. Permission-gated Fin tools are optional for missing-tool drift while present tools retain classification checks. Schema coverage reports present reviewed tools as unpinned. Schema digests remain unpinned because anonymous catalog discovery requires authentication.
+- Add optional connector-level `readOnly` to every connector and maintained provider, enforcing read-only discovery and calls on every endpoint. Show the policy in the operator UI and clarify Stripe OAuth and API-key setup.
+
+### Fixed
+
+- Correct catalog drift reporting with schema coverage and verification states,
+  identity-partitioned observations, optional gated tools, and versioned schema
+  set canonicalization that preserves existing pins. Detect documented tool
+  access changes and stale unclassified acknowledgements in provider checks.
+  Operator refresh responses include the catalog comparison from that refresh,
+  so hashing failures and changed schemas cannot return an earlier clean report.
+  Provider pin assertions select the stored digest format, and a generated-roster
+  guard verifies every pin against captured schemas and rejects input/output drift.
+- Reconcile the maintained Linear catalog with hosted label lifecycle, inbox, saved view, triage, and diff tools. Preserve plan-gated customer requests, review the documented customer-needs read, and pin the observed hosted schemas so later changes fail closed.
+- Refresh reviewed hosted Mixpanel schemas so Get-Events, Get-Dashboard, List-Cohorts, and Get-Metric remain available to read-only endpoints without deployment overrides. Review the limited-beta Get-Audit-Log as a read, retain Fill-Event-Metadata as a write, and classify Get-Experiment as destructive because its optional computations can persist results and auto-conclude experiments.
+- Keep catalog drift informational, keep each connector's last verdict on every operator view while its details are read again so cards, counts and the attention list stop bouncing, keep attention rows in configuration order as their verdicts settle, safely hold prototype-named connector IDs, keep card and detail headers and Overview attention text on single lines with accessible ellipsis, including long connector ids, auth scopes and Read-only badges, reserve the card action footer and empty tool bar row, and compact the top bar for long deployment names and all page tabs.
+- Refresh Vercel and Cloudflare REST contracts and value-safety reviews, withhold conditional firewall match credentials, stored AI Search crawler headers and daemon probe headers, setup-form defaults, and payment client secrets, refuse schemaless Cloudforce match responses before dispatch, admit two stateless Cloudflare POST reads, classify hosted Cloudflare documentation search as read-only, and reconcile Vercel's complete hosted tool inventory.
+- Review RevenueCat subscription-group listing, audience preview, and paywall screenshot rendering as reads, pin four live schemas, and clarify permission-gated catalogs and conservative credential-validation routing.
+- Refresh Stripe hosted MCP tool reviews for money movement, recipient setup, Atlas formation, and renamed feedback; remove retired reviews, pin captured schemas for drift detection, and document account, mode, and human-confirmation requirements.
+
+## 0.34.0 — 2026-10-16
+
+Connecta 0.34.0 rebuilds the operator UI around an Overview with connector health, endpoints, people and agents, a Needs attention list with fix prompts, and a connection map (#867). Maintainers now land on Overview at `/`; Endpoints moves to `/endpoints`, and `/access` redirects there. Update bookmarks, links and browser automation that expected Endpoints at `/`. Members still get their member page on every operator page path. The upgrade steps are in `documentation/migration-0.34.md`.
+
+The redesign carries through Connectors, Endpoints, the access matrix, Tokens, Settings, Activity and the member page, with warm neutral surfaces, one accent, self-hosted Hanken Grotesk and JetBrains Mono, and light and dark themes. Configuration uses tiles, connector tools open in a schema drawer, Activity groups calls by request, and Account holds Sign out and Change token. Default browser titles now join the product and owner with `·`; set `branding.pageTitle` explicitly if an integration needs the old title. Custom titles stay unchanged. Activity outcome links can use `failed` or `succeeded`; older exact outcome values still filter by that value. Custom activity stores may optionally report `describe().optionSources.retentionDays` as `"config"` or `"default"` so Settings can distinguish an explicit retention setting; existing stores need no change.
+
+Agents in a pool without an `owner` no longer discover Google Workspace connectors whose `subject` is a mapping function (#873). Those connectors previously appeared but failed calls with `auth_required`; now they are absent from discovery, search, describe, skills and code mode, and calls by address fail `unknown_address`. Saved program returns are rechecked too. To give an agent Workspace access, use a pool with the intended person's Workspace address as its `owner`, such as `alice@example.com`; do not add an owner to a shared pool just to restore discovery. People, agents in owned pools and fixed-subject connectors keep their behavior.
+
+Pools can now take a one-line `description` of 1 to 500 characters, appended to that pool's MCP instructions after `This endpoint: ` (#872). Pools without a description and plain `/mcp` keep their instructions. The auth guide now documents group tiers: pick the most capable pool everyone present is cleared for, use the base pool when anyone is unknown, and build personal pools on that person's highest tier (#875). Shipped docs also correct operator, provider and deployment guidance (#866). Repository development and CI now use pnpm (#877); installed deployments, the Node template and npm publishing keep using npm. Upgrading from 0.33.0 needs no storage migration or token rotation. Deployments that do not use the operator UI or mapping-subject Workspace connectors in owner-less agent pools can ignore the UI and discovery migration steps; all new configuration fields are optional.
+
+### Added
+
+- Add an Overview page as the maintainer's landing page at `/`: a status pill and stat cards for connector health, endpoints, and people and agents, a "Needs attention" list that links each problem to its existing fix with a copyable fix prompt, and a connection map of callers, endpoints and connectors that traces what a node reaches on hover or focus and opens its page on click. Endpoints moves to `/endpoints`, and `/access` now redirects there. Members still get their member page on every path.
+- Pools take an optional `description`: one line of plain text, 1 to 500 characters, that `/mcp/<pool>` and `/agent/<pool>` append to their MCP instructions after `This endpoint: ` so the model learns that endpoint's scope. Plain `/mcp` and pools without one keep the shared instructions, and `describeConfig()` lists each pool's `description` (`null` when unset).
+
+### Changed
+
+- The operator UI's Activity page and the member page ("Your connections") follow the calm redesign (#867). Activity shows counts and a calls-over-time strip, filters with a search box, an All / Failed / Succeeded control and connector and source chips instead of select menus, and rows grouped by request with one status dot, the caller as a person or agent chip, a connector monogram, the tool, and duration and size; a row opens for the rest of what was recorded. A connector's Activity tab uses the same rows. The member page shows the signed-in email, endpoints as cards, accounts with distinct monograms and aligned status badges, and a compact shared list. The Activity outcome filter now takes `failed` or `succeeded`; an older exact outcome value in a link still filters by that value.
+- An agent in a pool without an `owner` no longer sees Google Workspace connectors whose `subject` is a mapping function: they are absent from discovery, search, describe, skills and code mode, and a call by address fails `unknown_address`, as for a personal connector. Before, the agent saw them and every call failed `auth_required`. People in the same pool, agents in owned pools, and fixed-subject connectors are unchanged (#870).
+  
+  Paging a saved program return rechecks every connector contributing to search counts, ranking, term analysis, or guidance, including matches outside the returned page and connector references when no tools matched. Removing a pool owner therefore also hides those saved contributions from agents.
+- Document group tiers in the agent pool layout: a chat gets the most capable tier everyone present is cleared for, tiers nest by spreading tool lists, the base pool is the lowest tier and the fallback for anyone unknown, a tier can double as a team pool for the people cleared for it, and personal pools build on their person's highest tier. Shorten the README to the visual overview.
+- The operator UI and the pages connecta renders for people (sign-in, no access, OAuth results, 404s) take a new look: warm neutral surfaces, one indigo accent, soft cards, status pills, and Hanken Grotesk with JetBrains Mono for values, in light and dark. The fonts stay self-hosted. The top bar puts the sections, Search, Appearance and a new Account button on one row; Sign out and Change token now live under Account. The drawn connecta mark shows only on an unbranded deployment; a configured `favicon.svg` shows instead. A custom accent derives readable button text and dark-mode link color from itself.
+- The operator UI's Connectors page shows a card per connector with its status, Shared or Per person badge, a read/write tool bar and its last call, filtered by All, Needs attention or Healthy. A connector's page opens with its status and badges; Tools filters by Read or Write and opens a schema in a side drawer, and Connection shows authentication facts, a credential card with its masked last four, and diagnostics as tiles (#867).
+- The operator UI's Endpoints, access matrix and Tokens pages adopt the calm design. Endpoint rows show who can use them as an avatar stack, their connectors as monograms and their tools over a read/write bar, with a read-only pill only where it applies; client setup switches between Claude Code, Codex and JSON over one snippet. Matrix cells show the share of a connector they grant as a pie, read-only columns are hatched, and the Status and Runs as columns give way to a status dot and each cell's popover, which marks every tool read or write. Tokens rows show the agent mark, pool chips, a state pill and dates, with one primary action at most, and stack into cards on a narrow screen. Matrix shares count only live granted tools, show unknown coverage when the catalog is unavailable, and name both granted and total live counts for assistive technology.
+- Develop the repository with pnpm instead of npm: `pnpm-lock.yaml` replaces `package-lock.json`, `pnpm-workspace.yaml` allows only the esbuild and workerd build scripts, CI installs with `pnpm install --frozen-lockfile`, and `check:security` runs `pnpm audit`. The published package, its install instructions, and the Node template still use npm, and releases still publish through `npm publish` with trusted publishing.
+- Settings and the connector Configuration card show configuration as tiles instead of a key/value tree. Deployment facts are chips (name with server version, Writes allowed or Read-only, and a warning chip for unconfigured memory storage); sign-in shows provider tiles, an agent count and one Maintainers tile; features show on or off; headline limits draw large with an accent dot when set in code, and the remaining defaults fold into one "17 defaults" disclosure of grouped cards. Sizes read in decimal units with the exact byte count as a tooltip, and a null tool timeout shows the host-call timeout it falls back to. A connector's card adds an auth row: mode, header names, OAuth scope, API origins and OAuth endpoints as compact badges. The D1 and SQLite activity stores report whether code set `retentionDays`, and Settings marks retention set only then. Snapshot keys the UI does not map still appear as labelled tiles.
+  
+  Open deployments retain the Maintainers tile beside Open, with "None" when no maintainers are configured.
+- The operator UI uses shorter copy throughout (#867): labels, empty and error states, confirmations, notices, gates and the OAuth callback and 404 pages, with no em dashes. Page titles separate with a middle dot. On the Overview, narrow stat tiles sit two up, the map draws a muted dash instead of "0 tools" for a connector whose catalog is unknown, and caller chips in the narrow list link like map nodes.
+
+### Fixed
+
+- Correct inaccurate guidance across the shipped docs, provider skills, and the usage skill: token-route statuses, OAuth control labels, meta-tool paging and timing, host-call budgets, error codes, doctor output and credentials, local `.env` use, Worker secrets and copied-repo setup, the 0.33 Node template script upgrade, and provider argument names and write classifications. Rewrite the README to explain people, agents, pools, and account ownership with diagrams, and drop the hero image.
+
 ## 0.33.0 — 2026-10-16
 
 Connecta 0.33.0 makes pools the access model, and every deployment with inbound auth must change its configuration (#837). Work through `documentation/migration-0.33.md` before upgrading; it maps every removed option to its replacement. A new top-level `maintainers` list names the people who reach plain `/mcp` and administer the deployment. Each pool now has a static `members` list and serves exactly its `tools` to those members. Agents are declared by name in `agents`, each with one rotatable `cta_` token. Each removed option fails at startup with a message naming its replacement, so a deployment that starts has nothing silently ignored: `identity` (even `{}`) and its `connectorAccess`, `credentialAdministration`, `personalConnection`, `accessTokenManagement` and `activityAccess`, plus the top-level `grant` and pool `grant`.

package/README.md

@@ -1,157 +1,129 @@
 # connecta
 
-![A monochrome clay Connecta hub joining many tools](https://raw.githubusercontent.com/zackbart/connecta/main/assets/connecta-clay-hero.png)
+**One connection between your agent and the services you choose.**
 
-One connection between your agent and the services you choose.
+Connecta puts your MCP servers and HTTP APIs behind one endpoint that you run
+yourself. Connect your agent once; decide in code who can reach what.
 
-Connecta brings your MCP servers and HTTP APIs together behind one endpoint.
-Connect your agent once, then choose which integrations it can use. You run
-Connecta yourself, on your own machine or infrastructure.
-
-## The mental model
-
-Ask your agent to find open issues, compare them with customer feedback, or
-prepare a report. Connecta gives it a small set of tools for finding and using
-the services you connected, without loading every service's tool definitions
-into the conversation.
-
-The agent writes a short program that runs in a sandbox beside those
-integrations. It can gather results, combine them, and return the parts that
-answer your question. Fifty issues can become a short list grouped by owner
-before the result reaches the conversation. The agent writes the code; you
-ask for the work.
+## How it works
 
 ```mermaid
 flowchart LR
-    Agent["Your agent"] <-->|"One connection"| Connecta["Your Connecta deployment"]
-    Connecta <--> Work["Work tools<br/>Linear, GitHub, Notion"]
-    Connecta <--> Business["Business services<br/>Stripe, RevenueCat, Mixpanel"]
-    Connecta <--> Yours["Your other services<br/>Remote MCP servers and HTTP APIs"]
+    Agent["Your agent"] <-->|"One connection<br/>six small tools"| Connecta
+
+    subgraph Connecta["Your Connecta deployment"]
+        Sandbox["Sandbox<br/>runs the agent's short programs"]
+        Keys["Credentials<br/>stay on the server"]
+    end
+
+    Connecta <--> Work["Linear, GitHub, Notion"]
+    Connecta <--> Business["Stripe, RevenueCat, Mixpanel"]
+    Connecta <--> Yours["Any remote MCP server<br/>or HTTP API"]
 
     style Connecta fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b,stroke-width:2px
 ```
 
-You choose which services to connect and who can use them: the maintainers
-you name reach everything, and everyone else, people and agents alike, reaches
-only the pools of tools you list them in. Your agent keeps the same connection
-as those services change.
+The agent doesn't load every service's tools into the conversation. It writes
+a short program that gathers, joins, and trims results inside Connecta, so
+only the answer comes back.
+
+## What you can connect
 
-## From a question to an answer
+Maintained connections: <!-- providers:start -->Basecamp, Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Infisical, Intercom, Linear, Mixpanel, Notion, Overflow, Planning Center, RevenueCat, Stripe, Tithe.ly, Vercel, and Wispr Flow<!-- providers:end -->.
+Plus any remote MCP server or HTTP API you describe.
 
-Say you ask, "Which open issues affect our highest-value customers?" Your agent
-can gather information from your issue tracker and customer records, combine
-it inside Connecta, and bring back a focused answer.
+## Who can use it
+
+|                   | People                                               | Agents                                   |
+| ----------------- | ---------------------------------------------------- | ---------------------------------------- |
+| What they are     | You and your team                                    | Bots, assistants, CI, scheduled jobs     |
+| How they prove it | Sign in: Clerk (Node) or Cloudflare Access (Workers) | One token Connecta issues to that agent  |
+| Their own logins  | Yes, on personal connections                         | No. An agent uses accounts you assign it |
+
+**Maintainers** are the people who run the deployment: they reach every tool
+and manage credentials and agent tokens. Everyone else reaches only the pools
+they are listed in.
+
+### Pools
+
+A **pool** is a named set of tools plus a list of who may use it. Each pool
+has its own address, and every caller sees exactly that pool's tools.
 
 ```mermaid
-flowchart TB
-    Question["You ask a question"] --> Plan["Your agent works out what to look up"]
-    Plan --> Gather["A program in Connecta gathers the relevant records"]
-    Gather --> Tracker["Open issues from your tracker"]
-    Gather --> Customers["Customer records from a connected service"]
-    Tracker --> Combine["The program matches, filters, and groups the results"]
-    Customers --> Combine
-    Combine --> Answer["Your agent explains the answer"]
-
-    style Combine fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b,stroke-width:2px
-    style Answer fill:#dcfce7,stroke:#15803d,color:#14532d
+flowchart LR
+    Maint["Maintainer<br/>(signs in)"] --> Main["/mcp<br/>every tool"]
+    Bob["Bob<br/>(signs in)"] --> Team["/mcp/team<br/>CRM + tickets"]
+    Bot["assistant agent<br/>(token)"] --> AgentPool["/agent/assistant<br/>CRM + tickets"]
+
+    style Main fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b
+    style Team fill:#dcfce7,stroke:#15803d,color:#14532d
+    style AgentPool fill:#fef3c7,stroke:#b45309,color:#78350f
 ```
 
-The records are an example; the available information depends on the services
-and access you have configured. Processing results inside Connecta keeps the
-conversation focused on the answer.
-
-## What you can do with it
-
-Connect hosted MCP services, add an internal HTTP API, and let the agent work
-across them in one task. Changing your connected services does not require
-changing the agent's connection. Your deployment decides which services and
-operations each caller can reach.
-
-Connecta includes maintained connections for <!-- providers:start -->Basecamp, Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Infisical, Linear, Mixpanel, Notion, Overflow, Planning Center, RevenueCat, Stripe, Tithe.ly, Vercel, and Wispr Flow<!-- providers:end -->.
-Each connection has its own setup guide.
-Stripe, Notion, Cloudflare, and Vercel use their hosted MCP servers when you
-sign in with OAuth, and Connecta's own API connections when you use an API key,
-a Cloudflare API token or Global API Key, a Notion integration token, or a
-Vercel access token. You can also
-connect other remote MCP servers or define the operations you need from an
-HTTP API.
-
-Google Workspace connections use the account your deployment assigns to each
-signed-in person. A Workspace administrator authorizes them for your domain.
-Gmail reads mail and attachments and writes drafts, but does not send mail.
-Google Drive can read, write, and share files, but does not permanently delete
-them. Available
-operations and account access depend on the integration and your deployment.
-
-Large results need not fill the conversation. The agent can filter and
-summarize them in its program, or read a large result in smaller pieces.
-
-## Writes, credentials, and access
-
-Connecta distinguishes reads from writes, and each endpoint is either writable
-or read-only. By default an endpoint is writable: your agent can make a change
-with one visible tool call or inside a program, and your agent's host decides
-whether to ask for approval; it sees the program tool as a write. You can mark
-the whole deployment or a single endpoint read-only, and then nothing there can
-change anything: search leaves write tools out and every write is refused. You
-make this choice explicitly for each deployment. Neither choice gives a caller
-access to additional services.
+People use a pool at `/mcp/<pool>` and agents at `/agent/<pool>`. A caller
+outside a pool gets the same "not found" as a pool that doesn't exist, and
+someone in two pools uses two addresses: pools never merge.
+
+### One agent, many people
+
+An assistant that talks to several people keeps **one token and one
+connection**. Its harness, not the model, picks the pool each turn: a chat
+gets the most capable tier that everyone in it is cleared for, and a
+one-on-one gets that person's own pool.
 
 ```mermaid
-flowchart TB
-    Change["Your agent wants to change something"] --> Choice{"Is this endpoint<br/>read-only?"}
-    Choice -->|"Explicit choice: yes"| Refused["Refused; nothing is sent"]
-    Choice -->|"Default: no"| Host["Your agent's host handles approval"]
-    Host --> Access["Connecta checks the caller's access"]
-    Access --> Services["The connected service receives the change"]
-
-    style Host fill:#fef3c7,stroke:#b45309,color:#78350f
-    style Access fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b,stroke-width:2px
+flowchart LR
+    Guests["Chat with anyone unknown"] --> Base["/agent/assistant<br/>read-only basics"]
+    Group["Chat of team members"] --> TeamTier["/agent/assistant-team<br/>shared tools"]
+    Leads["Chat of leads only"] --> LeadsTier["/agent/assistant-leads<br/>shared tools + billing"]
+    Alice["One-on-one<br/>with Alice"] --> PA["/agent/assistant-alice<br/>her tier + her accounts"]
+
+    Base -.-> TeamTier -.-> LeadsTier
+
+    style Base fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b
+    style TeamTier fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b
+    style LeadsTier fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b
+    style PA fill:#dcfce7,stroke:#15803d,color:#14532d
 ```
 
-Connecta handles integration credentials on the server. Its sandbox does not
-receive them. Optional encrypted storage protects saved credentials. Connections can use
-shared credentials or a person's own account, with access rules set by the
-deployment owner. Permission to use a connection is separate from permission
-to manage its credentials.
-
-People sign in through Clerk on Node or Cloudflare Access on Workers. Machine
-clients are agents you name in deployment code, each with one token issued by
-your Connecta deployment. Agents connect through their own address for each
-pool, separate from the one people use, so an agent sends only its token, even
-behind Cloudflare Access. A deployment can serve
-several people within one tenant, each with the access you assign. An agent
-that serves several people keeps one connection and switches pools per turn:
-a shared pool for group chats and scheduled work, and a pool per person, with
-that person's own accounts, used only when that person is the one talking.
-
-## A place to see your connections
-
-The optional operator UI shows connected services, available tools, access,
-and configuration. Maintainers manage shared credentials, issue or rotate agent
-tokens, and read the optional activity history, which shows who called what,
-when, and whether it worked, without recording arguments, results, or program
-code. Pool members connect their own accounts on personal connections.
-
-Your agent or developer changes the integrations and access rules in deployment
-code. The UI helps you inspect them and manage authentication.
+Each tier builds on the one below it. A person's own pool builds on the
+highest tier they are cleared for and holds only the agent, since anyone else
+in it would act as that person. A tier can double as a team's own pool for
+the people cleared for it. [Organizing an agent's pools](./documentation/auth.md#organizing-an-agents-pools)
+has the full layout.
+
+### Whose account a connection uses
+
+- **Shared** (the default): the deployment's account, connected once by a
+  maintainer.
+- **Personal**: each person's own account. Agents never see these.
+- **Google Workspace**: the signed-in person's account; for an agent, the
+  owner of a person's pool, or one fixed shared account. Without an owner,
+  mapping connections are absent for agents.
+
+## Reads and writes
+
+Every endpoint is writable or read-only, and you choose explicitly. A
+read-only endpoint hides write tools and refuses every write. You can also make
+one connection read-only across all endpoints. On a writable
+one, your agent's host decides what to approve.
 
 ## Where it runs
 
-Run Connecta locally or on a server with Node, including in Docker, or host it
-on Cloudflare Workers. Both offer the same agent tools. Running programs on
-Workers requires Cloudflare's Workers Paid plan.
+Node or Docker (Clerk sign-in, SQLite) or Cloudflare Workers (Cloudflare
+Access, D1). Both serve the same agent tools. An optional operator UI shows
+a connection map, endpoints, connectors, and activity; integrations and access
+still change only in deployment code.
 
 ## Getting started
 
-Give your agent the [agent documentation](./documentation/README.md) and ask it
-to set up Connecta with the integrations you want. Tell it where you want to
-run it and who should have access. The setup guides cover Node, Docker, and
-Cloudflare Workers, including connecting your agent client.
+Give your agent the [agent documentation](./documentation/README.md) and ask
+it to set up Connecta with the integrations you want, where to run it, and who
+should have access.
 
 <a id="existing-client-tokens"></a>
 
-For an existing deployment, ask your agent to follow the
+Upgrading? Point your agent at the
 [upgrade guidance](./documentation/deploying.md#upgrade-an-existing-deployment).
 
 ## Status
@@ -160,7 +132,7 @@ Built for its author's deployments first and published openly. Breaking
 changes are expected before 1.0. See the [changelog](./CHANGELOG.md) and
 [security policy](./SECURITY.md).
 
-The [principles](https://github.com/zackbart/connecta/blob/main/PRINCIPLES.md)
-state the goals and tested rules. [Decision records](https://github.com/zackbart/connecta/tree/main/decisions)
-explain past choices. [GitHub issues](https://github.com/zackbart/connecta/issues)
-track planned work; a plan is not a shipped feature.
+[Principles](https://github.com/zackbart/connecta/blob/main/PRINCIPLES.md) ·
+[Decision records](https://github.com/zackbart/connecta/tree/main/decisions) ·
+[Planned work](https://github.com/zackbart/connecta/issues) (a plan is not a
+shipped feature)

package/SECURITY.md

@@ -20,5 +20,5 @@ The MCP TypeScript SDK 2.x packages and Effect are exact-pinned. Effect is the
 runtime core, and its unstable modules can break in a minor release, so its pin
 moves in a dedicated upgrade. The split client and server packages no longer
 install Hono or `@hono/node-server`, so the temporary root-project override
-used with SDK 1.x is gone. A dependency bump must pass `npm run release:check`
+used with SDK 1.x is gone. A dependency bump must pass `pnpm run release:check`
 and the Node/Workers runtime suites before a pin moves.

package/bin/version.mjs

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.33.0";
+export const CONNECTA_VERSION = "0.34.1";

package/dist/activity.d.ts

@@ -126,10 +126,13 @@ export interface ActivityStore extends ActivitySink {
     /**
      * The adapter and its retention, for `Connecta.describeConfig()`. Kinds
      * other than the shipped `"d1"` and `"sqlite"` are described as `"custom"`.
+     * `optionSources` says whether code set `retentionDays` (`"config"`) or the
+     * store chose it (`"default"`); without it the retention reads as a default.
      */
     describe?(): {
         kind: string;
         retentionDays?: number;
+        optionSources?: Readonly<Record<string, "default" | "config">>;
     };
 }
 /** Reader implementations throw this for an opaque cursor they cannot decode. */

package/dist/branding.d.ts

@@ -99,6 +99,13 @@ export interface PageLayout {
  * `mastheadEnd`, and `tail` are the caller's markup and are not.
  */
 export declare function renderPage(branding: ConnectaBranding | undefined, layout: PageLayout): string;
+/**
+ * The mark beside the brand name. Connecta's drawn "C" belongs to an
+ * unbranded deployment only; a deployment that serves its own SVG favicon
+ * shows that; any other branding shows its name alone.
+ */
+export type BrandMark = "connecta" | "favicon" | "none";
+export declare function brandMark(branding: ConnectaBranding | undefined, uiMounted: boolean): BrandMark;
 /**
  * Status marks for one-message pages. Decorative: the label and heading beside
  * each carry the meaning, so the shape repeats it and color is never alone.

package/dist/branding.js

@@ -1,4 +1,4 @@
-import { PAGE_CSS, TOKENS_CSS } from "./page-styles.js";
+import { PAGE_CSS, PAGE_FONTS, TOKENS_CSS } from "./page-styles.js";
 import { htmlSecurityHeaders } from "./html-security.js";
 /** Connecta's default monochrome "C" mark. */
 export const CONNECTA_FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
@@ -9,6 +9,7 @@ export const CONNECTA_FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" vie
   <path class="fg" d="M27 9.4A13 13 0 1 0 27 22.6l-4.4-2.5a8 8 0 1 1 0-8.2z"/>
 </svg>`;
 const DEFAULT_FAVICON_HREF = "/favicon.svg";
+const DEFAULT_PRODUCT_NAME = "Connecta";
 /**
  * Branding arrives from operator config, which is untyped at a JS call site, so
  * every field is treated as `unknown`: a non-string is read as unset rather than
@@ -19,7 +20,7 @@ function trimmedString(value) {
     return typeof value === "string" ? value.trim() || undefined : undefined;
 }
 export function resolveBranding(branding) {
-    const productName = trimmedString(branding?.productName) ?? "Connecta";
+    const productName = trimmedString(branding?.productName) ?? DEFAULT_PRODUCT_NAME;
     const ownerName = trimmedString(branding?.ownerName);
     // Operator branding URLs become masthead/callback hrefs, so a non-http(s)
     // scheme (javascript:, data:) is dropped the same as an unset URL — the
@@ -34,7 +35,7 @@ export function resolveBranding(branding) {
         ...(ownerUrl && isSafeHttpUrl(ownerUrl) ? { ownerUrl } : {}),
         description: trimmedString(branding?.description) ??
             `Manage the services this ${productName} instance makes available to agents.`,
-        pageTitle: trimmedString(branding?.pageTitle) ?? (ownerName ? `${productName} — ${ownerName}` : productName),
+        pageTitle: trimmedString(branding?.pageTitle) ?? (ownerName ? `${productName} · ${ownerName}` : productName),
         faviconHref: faviconHref && isSafeIconHref(faviconHref) ? faviconHref : DEFAULT_FAVICON_HREF,
         themeColor: configuredThemeColor(branding) ?? "#ffffff",
         theme: resolveTheme(branding?.theme),
@@ -128,6 +129,46 @@ export function droppedThemeTokens(theme) {
     }
     return dropped.map((token) => `theme.${token}`);
 }
+function rgbOf(hex) {
+    const digits = hex.slice(1);
+    // `#rgb` and `#rgba` double each digit; alpha never affects contrast here.
+    const short = digits.length <= 4;
+    const pairs = [0, 1, 2].map((i) => (short ? digits[i].repeat(2) : digits.slice(i * 2, i * 2 + 2)));
+    return pairs.map((pair) => parseInt(pair, 16));
+}
+function luminance([r, g, b]) {
+    const channel = (value) => {
+        const c = value / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+function contrast(a, b) {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+}
+const hexOf = (rgb) => `#${rgb.map((c) => Math.round(c).toString(16).padStart(2, "0")).join("")}`;
+/** The dark palette's lightest surface that carries accent text (`--hover`). */
+const DARK_TEXT_GROUND = [0x24, 0x22, 0x1e];
+/**
+ * A configured accent's two derived colors. Text on its fill is white or
+ * near-black, whichever reads better; accent text on dark surfaces mixes the
+ * accent with white until it reaches 4.5:1, starting from the built-in
+ * accent's 80% so a light accent keeps its color.
+ */
+function accentTokens(accent) {
+    const rgb = rgbOf(accent);
+    const ink = [0x0f, 0x0e, 0x1f];
+    const onAccent = contrast(rgb, [255, 255, 255]) >= contrast(rgb, ink) ? "#ffffff" : hexOf(ink);
+    let darkText = hexOf(rgb.map((c) => c * 0.8 + 255 * 0.2));
+    for (let share = 0.8; share >= 0; share -= 0.05) {
+        const mixed = rgb.map((c) => c * share + 255 * (1 - share));
+        darkText = hexOf(mixed);
+        if (contrast(mixed, DARK_TEXT_GROUND) >= 4.5)
+            break;
+    }
+    return { onAccent, darkText };
+}
 /**
  * The resolved theme as a `:root` block, or "" when a deployment configured
  * nothing. It is emitted after the stylesheet so it overrides the defaults.
@@ -135,8 +176,10 @@ export function droppedThemeTokens(theme) {
  * anything that would need escaping is dropped rather than rewritten.
  */
 export function themeCss(theme) {
+    const derived = theme.accent ? accentTokens(theme.accent) : undefined;
     const declarations = [
         theme.accent ? `--accent:${theme.accent}` : "",
+        derived ? `--custom-on-accent:${derived.onAccent};--custom-accent-text:${derived.darkText}` : "",
         theme.radius !== undefined ? `--radius:${theme.radius}` : "",
         theme.fontFamily ? `--sans:${theme.fontFamily}` : "",
         theme.monoFamily ? `--mono:${theme.monoFamily}` : "",
@@ -156,11 +199,11 @@ export function escapeHtml(value) {
     return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }
 /**
- * The masthead's `--surface` in each palette, for the browser chrome a
+ * The top bar's `--bg` in each palette, for the browser chrome a
  * `theme-color` paints. A configured `themeColor` wins; without one a dark
  * page should not sit under a white status bar.
  */
-const SURFACE = { light: "#ffffff", dark: "#151a21" };
+const SURFACE = { light: "#f6f4ef", dark: "#12110f" };
 /** The operator's own `themeColor`, read the one way both callers read it. */
 function configuredThemeColor(branding) {
     return trimmedString(branding?.themeColor);
@@ -202,6 +245,7 @@ export function renderPage(branding, layout) {
         : label("brand", brand.productName, brand.productUrl);
     const product = brand.ownerName ? label("product", brand.productName, brand.productUrl) : "";
     const customIcon = brand.faviconHref !== DEFAULT_FAVICON_HREF;
+    const mark = brandMarkHtml(brandMark(branding, layout.uiMounted));
     // `isSafeIconHref` already limited a relative href to one leading slash, so
     // resolving it can only land on `iconOrigin` itself.
     const iconHref = (href) => layout.iconOrigin && href.startsWith("/") ? new URL(href, layout.iconOrigin).toString() : href;
@@ -214,7 +258,13 @@ export function renderPage(branding, layout) {
     const skip = layout.skipTo
         ? `<a class="skip-link" href="#${escapeHtml(layout.skipTo.id)}">${escapeHtml(layout.skipTo.label)}</a>\n`
         : "";
-    const styles = (layout.styles ?? TOKENS_CSS + PAGE_CSS) + (layout.extraStyles ?? "");
+    // The operator bundle declares its own fonts. Other pages link the same
+    // files only where the UI module serves them, root-relative so the page's
+    // own origin serves them; elsewhere the stacks fall back to system fonts.
+    const fonts = layout.uiMounted
+        ? PAGE_FONTS.map((font) => `@font-face{font-family:"${font.family}";font-style:normal;font-weight:${font.weight};font-display:swap;src:url("${font.path}") format("woff2")}`).join("")
+        : "";
+    const styles = (layout.styles ?? fonts + TOKENS_CSS + PAGE_CSS) + (layout.extraStyles ?? "");
     return `<!doctype html>
 <html lang="en"${schemeAttribute(brand.theme)}>
 <head>
@@ -231,7 +281,7 @@ ${layout.head ?? ""}
 ${skip}<header class="masthead shell">
   <div class="masthead-inner">
     <div class="mast-nav">
-      ${owner}${product ? `\n      ${product}` : ""}
+      ${mark}${owner}${product ? `\n      ${product}` : ""}
     </div>${layout.mastheadEnd ? `\n    ${layout.mastheadEnd}` : ""}
   </div>
 </header>
@@ -239,6 +289,23 @@ ${layout.body}${layout.tail ? `\n${layout.tail}` : ""}
 </body>
 </html>`;
 }
+export function brandMark(branding, uiMounted) {
+    if (uiMounted && trimmedString(branding?.favicon?.svg))
+        return "favicon";
+    const brand = resolveBranding(branding);
+    const unbranded = brand.productName === DEFAULT_PRODUCT_NAME &&
+        !brand.ownerName &&
+        brand.faviconHref === DEFAULT_FAVICON_HREF &&
+        !branding?.favicon?.svg;
+    return unbranded ? "connecta" : "none";
+}
+function brandMarkHtml(mark) {
+    if (mark === "connecta")
+        return '<span class="brand-mark" aria-hidden="true"></span>';
+    if (mark === "favicon")
+        return `<img class="brand-mark" src="${DEFAULT_FAVICON_HREF}" alt="">`;
+    return "";
+}
 /**
  * Status marks for one-message pages. Decorative: the label and heading beside
  * each carry the meaning, so the shape repeats it and color is never alone.
@@ -281,12 +348,12 @@ export function notFoundResponse(request, opts) {
       <p class="status-label">404</p>
     </div>
     <h1>Page not found</h1>
-    <p class="status-copy">Nothing is served at this address. Check the link, or ask whoever runs ${escapeHtml(brand.productName)} for the right one.</p>
+    <p class="status-copy">Nothing is here. Check the link, or ask whoever runs ${escapeHtml(brand.productName)}.</p>
     ${home}
   </section>
 </main>`;
     return new Response(renderPage(opts.ui?.branding, {
-        title: `Page not found — ${brand.pageTitle}`,
+        title: `Page not found · ${brand.pageTitle}`,
         uiMounted,
         // Same bytes on either host: the icons, like the home link, come from
         // the public origin.