@lanes-sh/link 0.6.10 → 0.7.0

package/src/dispatch/staging.ts

@@ -1,7 +1,14 @@
 import { createHash } from 'node:crypto';
 import type { AuditSink } from '#audit';
 import type { Principal } from '#auth';
-import { newHandle, putStaged, sweepStaged, STAGED_TTL_MS } from '#connectivity/mail';
+import {
+  getStaged,
+  newHandle,
+  putStaged,
+  sweepStaged,
+  STAGED_TTL_MS,
+  type StagedFile,
+} from '#connectivity/mail';
 import type { BlobStore } from '#stores/blobs';
 import { scopeBlobStore } from '#stores/blobs';
 import { scopeNamespace } from './context.ts';
@@ -100,3 +107,71 @@ export async function stageAttachment(
 
   return { handle, sha256, expiresAt };
 }
+
+export interface FetchStagedRequest {
+  readonly principal: Principal;
+  readonly providerId: string;
+  readonly connectionId: string;
+  readonly handle: string;
+  readonly clientLabel?: string | undefined;
+}
+
+/**
+ * Handing bytes back out, which is the half staging was missing.
+ *
+ * Upload always worked: bytes in over HTTP, a handle through the model, a send
+ * that names it. The other direction had no route at all — an attachment that
+ * arrived by mail could be *described* by `get_message` and attached to an
+ * outgoing message by `send_message`, and there was no way to simply have it.
+ * The only paths out were to mail it somewhere else or to base64 it through the
+ * conversation, which is the cost this whole design exists to avoid.
+ *
+ * So it is the same shape run backwards, and deliberately the same scoping: the
+ * store is namespaced by provider and connection here exactly as it is above, so
+ * a handle minted for `icloud_mail.main` is fetchable from that connection and
+ * from no other. Nothing is bridged and no provider gains reach it did not have
+ * — the bytes were already inside this account's namespace, and this is a door
+ * onto it rather than a route between two.
+ *
+ * Null for "no such handle", "expired", and "wrong connection" alike. A caller
+ * cannot act on the difference, and distinguishing them would let someone probe
+ * for handles staged against an account they cannot reach.
+ */
+export async function fetchStaged(
+  deps: {
+    readonly storage: BlobStore;
+    readonly audit: AuditSink;
+    readonly profile: string;
+  },
+  request: FetchStagedRequest,
+): Promise<StagedFile | null> {
+  const storage = scopeBlobStore(
+    deps.storage,
+    scopeNamespace(request.providerId, request.connectionId),
+  );
+
+  const found = await getStaged(storage, request.handle);
+
+  // Logged either way. "Did anything leave the endpoint" is the question this
+  // answers, and a miss is as worth having as a hit — a run of them against
+  // handles that do not exist is what probing looks like.
+  await deps.audit.append({
+    profile: deps.profile,
+    principal: request.principal.id,
+    ...(request.clientLabel ? { clientLabel: request.clientLabel } : {}),
+    provider: request.providerId,
+    connection: `${request.providerId}.${request.connectionId}`,
+    capability: 'attachments.fetch',
+    arguments: {
+      handle: request.handle,
+      ...(found
+        ? { filename: found.filename, bytes: found.bytes.byteLength, content_type: found.contentType }
+        : {}),
+    },
+    authorization: 'allowed',
+    status: found ? 'ok' : 'error',
+    durationMs: 0,
+  });
+
+  return found;
+}

package/src/profile/knowledge.ts

@@ -2,21 +2,28 @@ import { z } from 'zod';
 import { credentialRef } from './primitives.ts';
 
 /**
- * Where a profile's memory and skills live, when that is not where everything
- * else lives.
+ * Where a profile's memory, skills and entities live, when that is not where
+ * everything else lives.
  *
  * A target's `storage:` block names one backend for everything a profile holds
  * — runtime state, the audit log, memory entries, skills, cached attachments.
- * That is right for most of it and wrong for two: state and the log are
- * artefacts of one installation, and memory entries and skills are documents
- * the owner wrote. Documents want history, review, and to be readable from more
- * than one machine, and the backend that suits an object nobody reads is not
- * the backend that suits those.
+ * That is right for most of it and wrong for three: state and the log are
+ * artefacts of one installation, and memory entries, skills and entity files
+ * are documents the owner wrote. Documents want history, review, and to be
+ * readable from more than one machine, and the backend that suits an object
+ * nobody reads is not the backend that suits those.
  *
- * So this block moves exactly those two, and it is the whole of what it can
+ * ADR-041 said "memory and skills, and nothing else", and ADR-056 amends the
+ * count without touching the rule. That exclusion was never arithmetic: its
+ * argument is a discriminator — an artefact of one installation stays, a
+ * document the owner wrote may move — and an entity file is a Markdown document
+ * with frontmatter, hand-editable, wanting history and review. It is on the
+ * same side of that line as a memory entry, by the same test.
+ *
+ * So this block moves exactly those three, and it is the whole of what it can
  * move. There is no `credentials` or `vault` value here and there will not be:
  * a repository is a place to publish, and those two hold the material whose
- * entire value is that it is not published (`docs/detailed/security.md`). The
+ * entire value is that it is not published (`https://lanes.sh/docs/link/security`). The
  * exclusion is structural — a field that does not exist cannot be set by
  * accident, by a flag, or by an operator following an example.
  *
@@ -89,8 +96,8 @@ export type KnowledgeConfig = z.infer<typeof knowledgeTargetSchema>;
 /**
  * Where each area sits inside the repository.
  *
- * Two directories, named after the two things that move. `memory` is also the
- * memory provider's own blob namespace — the prefix core scopes it into under
+ * Three directories, named after the three things that move. `memory` is also
+ * the memory provider's own blob namespace — the prefix core scopes it into under
  * the profile's blob root — which is why the same word does both jobs: the
  * route that redirects it and the directory it lands in are the same fact, and
  * spelling them separately is how they would come to disagree.
@@ -101,6 +108,7 @@ export type KnowledgeConfig = z.infer<typeof knowledgeTargetSchema>;
 export const KNOWLEDGE_LAYOUT = {
   memory: 'memory',
   skills: 'skills',
+  entities: 'entities',
 } as const;
 
 export type KnowledgeArea = keyof typeof KNOWLEDGE_LAYOUT;

package/src/profile/schema.ts

@@ -116,7 +116,7 @@ export const auditTargetSchema = z.object({
  *
  * Its own block rather than a reuse of `credentials`, because the vault must
  * never be the credential store — the two hold different things and collapsing
- * them is the single most damaging mistake available here (`docs/detailed/security.md`).
+ * them is the single most damaging mistake available here (`https://lanes.sh/docs/link/security`).
  *
  * Optional, defaulting to `file`: every profile written before ADR-014 keeps
  * working unchanged, and a local run needs no vault configuration at all.
@@ -242,7 +242,7 @@ export const deployTargetSchema = z.object({
    *
    * It is also what makes `limits.requests_per_minute` mean something in
    * aggregate. Those limits are per instance and always were; with no ceiling
-   * the aggregate had no value at all, and `docs/detailed/deployment-cloudrun.md`
+   * the aggregate had no value at all, and `https://lanes.sh/docs/link/deployment-cloudrun`
    * told the reader to cap this themselves because nothing here did.
    */
   max_instances: z.number().int().min(1).max(100).default(DEPLOY_DEFAULTS.max_instances),

package/src/providers/README.md

@@ -0,0 +1,189 @@
+# Providers
+
+A hundred and five of them, and almost all are a folder and a line. This page is the inventory and the
+ins and outs; [Connect your accounts](https://lanes.sh/docs/link/connect) is the same list written for someone
+deciding what to connect.
+
+## What a provider is
+
+Two choices and nothing else: **how a service is reached** (`connector.kind`) and **how we prove who
+we are** (`auth.kind`). Both are closed unions, both are orthogonal, and everything else is data
+hung off the pair. That is why iCloud can speak IMAP with a password while Gmail speaks HTTP with
+OAuth and neither costs the other any code.
+
+- [`../connectivity/transports/README.md`](../connectivity/transports/README.md) — the six ways to reach a service
+- [`../connectivity/auth/README.md`](../connectivity/auth/README.md) — the credential types, and the ones not built yet
+- [Connectivity coverage](https://lanes.sh/docs/link/connectivity-coverage) — which pairs work, which are refused, and why
+
+Where they come from:
+
+| | |
+|---|---|
+| **connector** | `mcp` 77 · `http` 15 · `imap` 6 · `dav` 6 · `fs` 1 |
+| **auth** | `oauth (dynamic)` 70 · `oauth (manual)` 18 · `basic` 12 · `bearer` 2 · `header` 1 · `none` 1 · `strategy` 1 |
+
+Two of the hundred and five are code rather than data — `gmail`, which assembles an RFC 2822 message to
+send one, and `bunq`, which runs a signing handshake no declarative form describes. Everything else
+is a manifest.
+
+## Tested means somebody connected it
+
+**Twenty-one are tested. Eighty-four are not**, and the tables say which.
+
+A manifest can be right in every way this repository can check and still not work. What the checks
+prove: the schema validates, the vendored spec generates registrable tools inside the 64 KB budget,
+every scope has a described meaning, the redaction keys name arguments that exist, and — for the
+remote MCP servers — the endpoint answered a live protocol probe with an OAuth challenge.
+
+What only a real account proves: that the grant is the right one, that the identity probe reads a
+field the vendor actually returns, that a refresh token comes back, and that the tool list is worth
+having. Until somebody has done that, the honest label is untested — not broken, and not a warning,
+just a fact about what has been established.
+
+The list is [`untested.ts`](untested.ts), it is the single source of truth, and
+`../readme.test.ts` asserts the documentation marks exactly those and no others. A provider leaves
+the list when somebody connects it and it does what it says.
+
+## Adding one
+
+A folder here and a line in [`index.ts`](index.ts). That file says it too, and means it: the folder
+holds *all* of the provider — the manifest, the scopes it asks for, what it redacts from the audit
+log, the setup walkthrough, and any vendored specification.
+
+The full walkthrough is [Creating a provider](https://lanes.sh/docs/link/creating-a-provider),
+which opens by pointing out that most providers should not be built-ins at all — a YAML manifest in
+a profile's own `providers.d/` is validated by the same schema and loaded by [`custom/`](custom/).
+
+Four things bite, and all four are quiet:
+
+1. **A redaction key that misses is invisible.** It withholds every argument and reads exactly like
+   working redaction. Key it on the capability name *as served* — Microsoft Graph's operations are
+   `me.ListMessages`, dots and all, because `shortenName` strips the provider id and the provider is
+   not called "me".
+2. **Schema size is not spec size.** `mcp-from-openapi` inlines `$ref`s, so a request body that
+   references a wide entity explodes: Graph's `PATCH /me/messages` measured 346 KB against a 64 KB
+   budget. `projectRequestBody` is the remedy where the body is a schema reference, and it is
+   checked — a field the vendor renames fails the refresh instead of becoming an argument the API
+   ignores.
+3. **A placeholder in the address needs a variable, and the reverse.** A provider whose host belongs
+   to the account rather than the vendor declares `variables`; `defineProvider` refuses a
+   `{placeholder}` nothing fills and a variable nothing uses, because the first fails as DNS and the
+   second asks the operator a question nothing reads. See ADR-055.
+4. **A property key the Anthropic API refuses takes down every provider at once**, not just its own.
+   `^[a-zA-Z0-9_.-]{1,64}$`, and one bad key rejects the whole `tools` array. The `http` transport
+   renames them and leaves the wire name alone, so OData's `$top` reaches an agent as `top`.
+5. **`base_url` must equal the spec's own `servers[0].url`**, and the version lives in different
+   places per vendor — Drive puts it in the host, Sheets in the path. Copying the wrong one 404s
+   every call.
+
+## The inventory
+
+`tested` is blank where nobody has connected it yet.
+
+| id | name | connector | auth | tested |
+|---|---|---|---|---|
+| `fastmail_calendar` | Fastmail Calendar | `dav` | `basic` |  |
+| `fastmail_contacts` | Fastmail Contacts | `dav` | `basic` |  |
+| `icloud_calendar` | iCloud Calendar | `dav` | `basic` | yes |
+| `icloud_contacts` | iCloud Contacts | `dav` | `basic` | yes |
+| `nextcloud_calendar` | Nextcloud Calendar | `dav` | `basic` |  |
+| `nextcloud_contacts` | Nextcloud Contacts | `dav` | `basic` |  |
+| `icloud_drive` | iCloud Drive | `fs` | `none` | yes |
+| `bunq` | bunq | `http` | `strategy` | yes |
+| `calendar` | Google Calendar | `http` | `oauth (manual)` | yes |
+| `contacts` | Google Contacts | `http` | `oauth (manual)` | yes |
+| `discord` | Discord | `http` | `header` | yes |
+| `docs` | Google Docs | `http` | `oauth (manual)` | yes |
+| `drive` | Google Drive | `http` | `oauth (manual)` | yes |
+| `gmail` | Gmail | `http` | `oauth (manual)` | yes |
+| `google_tasks` | Google Tasks | `http` | `oauth (manual)` | yes |
+| `microsoft_todo` | Microsoft To Do | `http` | `oauth (manual)` |  |
+| `onedrive` | OneDrive | `http` | `oauth (manual)` |  |
+| `outlook_calendar` | Outlook Calendar | `http` | `oauth (manual)` |  |
+| `outlook_contacts` | Outlook Contacts | `http` | `oauth (manual)` |  |
+| `outlook_mail` | Outlook Mail | `http` | `oauth (manual)` |  |
+| `reddit` | Reddit | `http` | `oauth (manual)` | yes |
+| `sheets` | Google Sheets | `http` | `oauth (manual)` | yes |
+| `fastmail_mail` | Fastmail Mail | `imap` | `basic` |  |
+| `gmail_imap` | Gmail (IMAP) | `imap` | `basic` | yes |
+| `icloud_mail` | iCloud Mail | `imap` | `basic` | yes |
+| `mailbox` | Mailbox (any IMAP server) | `imap` | `basic` |  |
+| `yahoo_mail` | Yahoo Mail | `imap` | `basic` |  |
+| `zoho_mail` | Zoho Mail | `imap` | `basic` |  |
+| `airtable` | Airtable | `mcp` | `oauth (dynamic)` |  |
+| `algolia` | Algolia | `mcp` | `oauth (dynamic)` |  |
+| `amplitude` | Amplitude | `mcp` | `oauth (dynamic)` |  |
+| `apify` | Apify | `mcp` | `oauth (dynamic)` |  |
+| `asana` | Asana | `mcp` | `oauth (dynamic)` |  |
+| `atlassian` | Atlassian | `mcp` | `oauth (dynamic)` |  |
+| `attio` | Attio | `mcp` | `oauth (dynamic)` |  |
+| `betterstack` | Better Stack | `mcp` | `oauth (dynamic)` |  |
+| `box` | Box | `mcp` | `oauth (manual)` |  |
+| `brightdata` | Bright Data | `mcp` | `oauth (dynamic)` |  |
+| `buildkite` | Buildkite | `mcp` | `oauth (dynamic)` |  |
+| `calendly` | Calendly | `mcp` | `oauth (dynamic)` |  |
+| `canva` | Canva | `mcp` | `oauth (dynamic)` |  |
+| `circleci` | CircleCI | `mcp` | `oauth (dynamic)` |  |
+| `clickup` | ClickUp | `mcp` | `oauth (dynamic)` |  |
+| `close` | Close | `mcp` | `oauth (dynamic)` |  |
+| `cloudflare_bindings` | Cloudflare Bindings | `mcp` | `oauth (dynamic)` |  |
+| `cloudflare_observability` | Cloudflare Observability | `mcp` | `oauth (dynamic)` |  |
+| `contentful` | Contentful | `mcp` | `oauth (dynamic)` |  |
+| `datadog` | Datadog | `mcp` | `oauth (dynamic)` |  |
+| `drive_mcp` | Google Drive (Google MCP) | `mcp` | `oauth (manual)` | yes |
+| `dropbox` | Dropbox | `mcp` | `oauth (dynamic)` |  |
+| `expensify` | Expensify | `mcp` | `oauth (dynamic)` |  |
+| `figma` | Figma | `mcp` | `oauth (dynamic)` |  |
+| `fireflies` | Fireflies | `mcp` | `oauth (dynamic)` |  |
+| `flagsmith` | Flagsmith | `mcp` | `oauth (dynamic)` |  |
+| `gamma` | Gamma | `mcp` | `oauth (dynamic)` |  |
+| `github` | GitHub | `mcp` | `bearer` | yes |
+| `gmail_mcp` | Gmail (Google MCP) | `mcp` | `oauth (manual)` | yes |
+| `grafana` | Grafana | `mcp` | `oauth (dynamic)` |  |
+| `heroku` | Heroku | `mcp` | `oauth (dynamic)` |  |
+| `hubspot` | HubSpot | `mcp` | `oauth (manual)` |  |
+| `hygraph` | Hygraph | `mcp` | `oauth (dynamic)` |  |
+| `insightly` | Insightly | `mcp` | `oauth (dynamic)` |  |
+| `jam` | Jam | `mcp` | `oauth (dynamic)` |  |
+| `klaviyo` | Klaviyo | `mcp` | `oauth (dynamic)` |  |
+| `linear` | Linear | `mcp` | `oauth (dynamic)` | yes |
+| `mercury` | Mercury | `mcp` | `oauth (dynamic)` |  |
+| `miro` | Miro | `mcp` | `oauth (dynamic)` |  |
+| `mixpanel` | Mixpanel | `mcp` | `oauth (dynamic)` |  |
+| `monday` | monday.com | `mcp` | `oauth (dynamic)` |  |
+| `mux` | Mux | `mcp` | `oauth (dynamic)` |  |
+| `navan` | Navan | `mcp` | `oauth (dynamic)` |  |
+| `neon` | Neon | `mcp` | `oauth (dynamic)` |  |
+| `netlify` | Netlify | `mcp` | `oauth (dynamic)` |  |
+| `notion` | Notion | `mcp` | `oauth (dynamic)` | yes |
+| `paddle` | Paddle | `mcp` | `oauth (dynamic)` |  |
+| `paypal` | PayPal | `mcp` | `oauth (dynamic)` |  |
+| `posthog` | PostHog | `mcp` | `oauth (dynamic)` |  |
+| `prisma` | Prisma | `mcp` | `oauth (dynamic)` |  |
+| `ramp` | Ramp | `mcp` | `oauth (dynamic)` |  |
+| `recurly` | Recurly | `mcp` | `oauth (dynamic)` |  |
+| `remote` | Remote | `mcp` | `oauth (dynamic)` |  |
+| `render` | Render | `mcp` | `bearer` |  |
+| `replicate` | Replicate | `mcp` | `oauth (dynamic)` |  |
+| `resend` | Resend | `mcp` | `oauth (dynamic)` |  |
+| `riverside` | Riverside | `mcp` | `oauth (dynamic)` |  |
+| `rootly` | Rootly | `mcp` | `oauth (dynamic)` |  |
+| `rudderstack` | RudderStack | `mcp` | `oauth (dynamic)` |  |
+| `salesloft` | Salesloft | `mcp` | `oauth (dynamic)` |  |
+| `sanity` | Sanity | `mcp` | `oauth (dynamic)` |  |
+| `sentry` | Sentry | `mcp` | `oauth (dynamic)` |  |
+| `shortcut` | Shortcut | `mcp` | `oauth (dynamic)` |  |
+| `slack` | Slack | `mcp` | `oauth (manual)` | yes |
+| `square` | Square | `mcp` | `oauth (dynamic)` |  |
+| `storyblok` | Storyblok | `mcp` | `oauth (dynamic)` |  |
+| `stripe` | Stripe | `mcp` | `oauth (dynamic)` |  |
+| `supabase` | Supabase | `mcp` | `oauth (dynamic)` |  |
+| `tavily` | Tavily | `mcp` | `oauth (dynamic)` |  |
+| `todoist` | Todoist | `mcp` | `oauth (dynamic)` |  |
+| `vercel` | Vercel | `mcp` | `oauth (dynamic)` |  |
+| `vimeo` | Vimeo | `mcp` | `oauth (dynamic)` |  |
+| `webflow` | Webflow | `mcp` | `oauth (dynamic)` |  |
+| `whimsical` | Whimsical | `mcp` | `oauth (dynamic)` |  |
+| `wix` | Wix | `mcp` | `oauth (dynamic)` |  |
+| `workable` | Workable | `mcp` | `oauth (dynamic)` |  |
+| `zapier` | Zapier | `mcp` | `oauth (dynamic)` |  |

package/src/providers/airtable/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Airtable registers us at connect time — nothing for an operator to set up. */
+export const airtable = defineProvider({
+  id: 'airtable',
+  name: 'Airtable',
+  description: 'Bases, tables, records, fields, and schema, via Airtable\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.airtable.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/algolia/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Algolia registers us at connect time — nothing for an operator to set up. */
+export const algolia = defineProvider({
+  id: 'algolia',
+  name: 'Algolia',
+  description: 'Search indices, records, queries, and synonyms, via Algolia\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.algolia.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/amplitude/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Amplitude registers us at connect time — nothing for an operator to set up. */
+export const amplitude = defineProvider({
+  id: 'amplitude',
+  name: 'Amplitude',
+  description: 'Events, charts, cohorts, and user activity, via Amplitude\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.amplitude.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/apify/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Apify registers us at connect time — nothing for an operator to set up. */
+export const apify = defineProvider({
+  id: 'apify',
+  name: 'Apify',
+  description: 'Actors, runs, datasets, and scraped results, via Apify\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.apify.com' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/asana/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Asana registers us at connect time — nothing for an operator to set up. */
+export const asana = defineProvider({
+  id: 'asana',
+  name: 'Asana',
+  description: 'Tasks, projects, portfolios, and workspaces, via Asana\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.asana.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/assets/provider.ts

@@ -40,8 +40,15 @@ import {
  * model is the cost the five sources exist to avoid; there is no reason to pay
  * it on the way in that would not also apply on the way out.
  *
- * **Getting an asset into a mail is not done here**, and that is a boundary
- * rather than a gap. A staged handle is scoped to `<provider>/<connection>`
+ * **Neither direction between a mailbox and this store is done here**, and that
+ * is a boundary rather than a gap. It cost somebody a real attempt: `store` takes
+ * the shared attachment shape, which advertises `message_id`, so an agent asked to
+ * keep a PDF that had arrived by mail read the description, named the message, and
+ * was refused — twice, having tried the obvious workaround in between. The schema
+ * offered a route the handler never had. The description above now says so, and
+ * the refusal in `#connectivity/mail` names what does work instead.
+ *
+ * The reason it cannot is real rather than incidental. A staged handle is scoped to `<provider>/<connection>`
  * (`#dispatch`'s `stageAttachment`), so a handle minted under `assets/main` is
  * deliberately unresolvable from `gmail/main` — bridging the two means crossing
  * the isolation every provider relies on, and that belongs in dispatch if it
@@ -211,10 +218,10 @@ export const assetsProvider: ProviderDefinition = defineLocalProvider({
       name: 'store',
       title: 'Store a file',
       description:
-        'Keep a file in this profile. Name exactly one source — path, url, handle, message_id, or data — and the endpoint reads the bytes itself; never base64 a file into this call when any other source will do. Storing under a name that exists replaces it.',
+        'Keep a file in this profile. Name exactly one source — path, url, handle, or data — and the endpoint reads the bytes itself; never base64 a file into this call when any other source will do. Storing under a name that exists replaces it. An attachment sitting in a mailbox cannot be named here: this connection holds no mailbox, so ask the mail connection to send it somewhere it can be reached from.',
       inputSchema: z.object({
         source: attachmentRefSchema.describe(
-          'Where the bytes come from. Exactly one of path, url, handle, message_id, or data.',
+          'Where the bytes come from. Exactly one of path, url, handle, or data. The mailbox sources — message_id and uid — are part of the shared shape but cannot resolve here.',
         ),
         name: z
           .string()

package/src/providers/atlassian/index.ts

@@ -0,0 +1,19 @@
+import { defineProvider } from '#connectivity';
+
+/**
+ * Jira, Confluence and Compass, through Atlassian's own MCP server.
+ *
+ * The endpoint is `/v1/mcp/authv2` and the path matters: `/v1/mcp` and
+ * `/v1/sse` both answer and neither publishes the protected-resource metadata
+ * the SDK discovers from, so a client pointed at either gets a 401 it cannot act
+ * on. This one advertises dynamic client registration, which is why there is
+ * nothing here for an operator to set up.
+ */
+export const atlassian = defineProvider({
+  id: 'atlassian',
+  name: 'Atlassian',
+  description:
+    'Jira issues, Confluence pages, and Compass components, via Atlassian\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.atlassian.com/v1/mcp/authv2' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/attio/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Attio registers us at connect time — nothing for an operator to set up. */
+export const attio = defineProvider({
+  id: 'attio',
+  name: 'Attio',
+  description: 'Records, lists, notes, and tasks in the CRM, via Attio\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.attio.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/betterstack/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Better Stack registers us at connect time — nothing for an operator to set up. */
+export const betterstack = defineProvider({
+  id: 'betterstack',
+  name: 'Better Stack',
+  description: 'Incidents, monitors, heartbeats, and logs, via Better Stack\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.betterstack.com' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/box/index.ts

@@ -0,0 +1,64 @@
+import { defineProvider } from '#connectivity';
+
+export const BOX_APP = 'box';
+
+/** Matched literally by Box, so it is declared rather than picked at run time. */
+const BOX_REDIRECT_URI = 'http://127.0.0.1:8772/callback';
+
+/**
+ * Box, through the server Box runs.
+ *
+ * Box publishes protected-resource metadata and an ordinary authorization-code
+ * flow, and no dynamic client registration — so the client is the operator's,
+ * and there are two consoles it can come from. The admin route is the one Box
+ * prefers and the one that works on a managed enterprise account; the developer
+ * route is what an individual has. The steps below take the second, and say so.
+ */
+export const box = defineProvider({
+  id: 'box',
+  name: 'Box',
+  description: 'Files, folders, and metadata in Box, via Box\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.box.com/' },
+  auth: {
+    kind: 'oauth',
+    registration: 'manual',
+    app: BOX_APP,
+    authorize_url: 'https://account.box.com/api/oauth2/authorize',
+    token_url: 'https://api.box.com/oauth2/token',
+    redirect_uri: BOX_REDIRECT_URI,
+  },
+  setup: {
+    summary:
+      'Box needs an OAuth app of your own. On a managed account an administrator can instead add ' +
+      'credentials to the Custom Box MCP Server integration in the Admin Console, which is the route ' +
+      'Box prefers; these steps take the developer one, which is what an individual account has.',
+    docs_url: 'https://developer.box.com/guides/box-mcp/remote/',
+    steps: [
+      'Sign in at https://app.box.com/developers/console and choose "Create Platform App" → "Custom App".',
+      'Pick "User Authentication (OAuth 2.0)" as the authentication method. Not Server Authentication — that one issues a service identity with no access to your own files.',
+      `Under Configuration → OAuth 2.0 Redirect URIs, add exactly: ${BOX_REDIRECT_URI} — the whole URL, including the port. Box matches it literally.`,
+      'Under Application Scopes, tick at least "Read all files and folders stored in Box"; add write access only if you want the agent to be able to change files.',
+      'Save, then copy the Client ID and Client Secret from the Configuration page.',
+      'If your Box account is managed by an administrator, the app also has to be authorised in the Admin Console under Apps → Custom Apps Manager before it will work.',
+    ],
+    troubleshooting:
+      'redirect_uri_mismatch means the URI on the app is not the one above — check the port, and 127.0.0.1 rather than localhost. ' +
+      'A sign-in that succeeds and then reaches nothing is usually an app awaiting administrator authorisation, or one created with Server Authentication rather than User Authentication.',
+    prompts: [
+      {
+        key: 'client_id',
+        label: 'Box app Client ID',
+        secret: false,
+        scope: 'shared' as const,
+        credential_ref: `${BOX_APP}/client_id`,
+      },
+      {
+        key: 'client_secret',
+        label: 'Box app Client Secret',
+        secret: true,
+        scope: 'shared' as const,
+        credential_ref: `${BOX_APP}/client_secret`,
+      },
+    ],
+  },
+});

package/src/providers/brightdata/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Bright Data registers us at connect time — nothing for an operator to set up. */
+export const brightdata = defineProvider({
+  id: 'brightdata',
+  name: 'Bright Data',
+  description: 'Web scraping, search results, and datasets, via Bright Data\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.brightdata.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/buildkite/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Buildkite registers us at connect time — nothing for an operator to set up. */
+export const buildkite = defineProvider({
+  id: 'buildkite',
+  name: 'Buildkite',
+  description: 'Pipelines, builds, jobs, and artifacts, via Buildkite\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.buildkite.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/bunq/index.ts

@@ -54,7 +54,7 @@ const manifest = defineProvider({
       'bunq issues an API key from inside the app, not from a web console. The key is bound to the IP addresses ' +
       'it is used from unless you mark it as a wildcard key — which you must do in the app if this endpoint will ' +
       'ever run anywhere but this machine.',
-    docs: 'docs/detailed/setup/bunq.md',
+    docs: 'https://lanes.sh/docs/link/bunq',
     docs_url: 'https://doc.bunq.com/basics/authentication/api-keys',
     steps: [
       'In the bunq app: Profile → Security & Settings → Developers → API keys → Add API key.',
@@ -63,7 +63,7 @@ const manifest = defineProvider({
       'If this endpoint will run deployed rather than on this machine, mark the key as a wildcard key in the same screen. bunq refuses to set that over the API, deliberately, so it cannot be done for you.',
       'Copy the key and paste it below. Nothing is sent anywhere until you do — the handshake that registers this device runs immediately afterwards.',
       'You will be asked what to call this connection. bunq has no endpoint that reports whose account a key belongs to, so the label is yours to choose.',
-      'To try this without a real account first, use bunq\'s sandbox: https://public-api.sandbox.bunq.com issues a test key and needs no bank account at all. Put a manifest of your own in providers.d/ naming that base_url — see docs/detailed/setup/bunq.md.',
+      'To try this without a real account first, use bunq\'s sandbox: https://public-api.sandbox.bunq.com issues a test key and needs no bank account at all. Put a manifest of your own in providers.d/ naming that base_url — see https://lanes.sh/docs/link/bunq.',
     ],
     troubleshooting:
       'bunq refused the key. The usual causes are a key that was revoked in the app, a request from an address the key ' +

package/src/providers/calendly/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Calendly registers us at connect time — nothing for an operator to set up. */
+export const calendly = defineProvider({
+  id: 'calendly',
+  name: 'Calendly',
+  description: 'Scheduled events, invitees, event types, and availability, via Calendly\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.calendly.com' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/canva/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Canva registers us at connect time — nothing for an operator to set up. */
+export const canva = defineProvider({
+  id: 'canva',
+  name: 'Canva',
+  description: 'Designs, folders, brand templates, assets, and exports, via Canva\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.canva.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/circleci/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** CircleCI registers us at connect time — nothing for an operator to set up. */
+export const circleci = defineProvider({
+  id: 'circleci',
+  name: 'CircleCI',
+  description: 'Pipelines, workflows, jobs, and test results, via CircleCI\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.circleci.com/v1/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/clickup/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** ClickUp registers us at connect time — nothing for an operator to set up. */
+export const clickup = defineProvider({
+  id: 'clickup',
+  name: 'ClickUp',
+  description: 'Tasks, lists, spaces, docs, and time entries, via ClickUp\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.clickup.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});