@zibby/skills 2.0.4 → 2.0.6

package/docs/templates/requires.md

@@ -0,0 +1,183 @@
+---
+sidebar_position: 4
+title: requires
+---
+
+# `requires`
+
+## What it is
+
+One agent needs a capability another agent publishes — a browser, a knowledge
+base, a bridge to an internal API. `requires` declares that need by **name**.
+
+At deploy the platform installs the provider as one of **this agent's own
+members** — the same cascade, the same binding record and the same delete
+cascade a sub-graph child gets — and then attaches the provider's endpoint to
+your agent as a managed MCP server.
+
+Nothing concrete is written in the template: no id, no URL, no credential.
+
+## There is no field to put a token in
+
+This is the part people look for and do not find, so it is worth stating plainly:
+
+- **A consumer declares WHO it uses.** Board Autopilot declares
+  `requires: [{ ref: 'endpoint:gbrain-kb/mcp', as: 'kb' }]` — and nothing else.
+- **A provider declares WHAT IT NEEDS.** The knowledge base declares its own
+  embedding model, in its own template.
+- **The credential that lets one call the other is in neither declaration.** The
+  platform mints it, encrypts it into the consumer's own environment, and never
+  returns it, logs it, or shows it to a model.
+
+So there is no token field, no shared secret to distribute and nothing for you
+to rotate. If you find yourself wanting to write a credential into a template,
+the design has gone wrong somewhere — a declaration is public data that travels
+with the card.
+
+:::info Your agent installs its own members
+A consumer never borrows a provider that happens to already exist in the
+project. It installs its own, always. The heavy engine underneath is shared per
+box anyway, so the extra agent row is just configuration.
+:::
+
+## Syntax
+
+```js
+spec: {
+  requires: [{ ref: 'endpoint:browser/mcp', as: 'browser' }],
+}
+```
+
+A bare string works too — `as` then defaults to the provider's slug:
+
+```js
+requires: ['endpoint:browser/mcp'],
+```
+
+## Properties
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `ref` | string | **Yes** | `<kind>:<provider-slug>/<entry-name>`. All lowercase, letters/digits/hyphens; each part must start with a letter or digit. **`endpoint` is the only kind today** | — | Re-applied. The member is installed and the endpoint attached, idempotently |
+| `as` | string | No | letters, digits, `-`, `_`; must start with a letter or digit | the provider slug | Re-applied. This is the handle your code looks the link up by |
+
+`<entry-name>` is a surface the provider **publishes** — `mcp` for an agent that
+serves an MCP endpoint.
+
+## What deploy does
+
+1. Adds the provider to this agent's member list, alongside any sub-graph
+   children.
+2. Installs it (recursively — its own members come too).
+3. Records the binding on your agent.
+4. Attaches the bound provider's endpoint as a managed MCP server, tagged with
+   your alias.
+
+Re-deploying is safe. An existing link is kept as-is; a stale one is replaced;
+a link you added by hand to the same provider is adopted rather than duplicated.
+
+## The two ways to consume it
+
+This is the part worth reading twice. Both shipped examples are mechanically
+identical to the platform — the attached endpoint is reachable from every node's
+model either way. **What differs is the choice your template makes.**
+
+| | **A. Model-driven** | **B. Code-driven** |
+|---|---|---|
+| Who calls the endpoint | the model, by calling its tools | your node's own code |
+| What the node does to resolve it | nothing | looks the link up by its alias |
+| What the model sees | tools in its tool list | nothing — just text in the prompt |
+| When it is missing | the model is told to skip and say why | one log line, an empty block |
+| Reach for it when | the work is open-ended | the retrieval must happen every run |
+
+### A. Model-driven — the model calls the tools
+
+The **Frontend Specialist** agent requires a browser. Its QA node does not
+resolve anything: it simply prompts, and the model discovers `browser_navigate`,
+`browser_take_screenshot` and the rest in its tool list.
+
+```js
+// the declaration
+requires: [{ ref: 'endpoint:browser/mcp', as: 'browser' }],
+
+// the node — no MCP wiring at all
+const out = await invokeAgent(prompt, { state });
+```
+
+The prompt is written to degrade honestly:
+
+> If you do **not** have browser tools, or the preview is unreachable: do not
+> fabricate anything and do not mark checks passed. Set `skippedReason`
+> explaining exactly what was missing.
+
+So with no browser attached the node returns `qaRan: false` plus an honest
+reason, and the run still completes.
+
+**Choose this** when the work is open-ended and the model should decide how many
+calls to make.
+
+### B. Code-driven — your code calls it, the model never sees a tool
+
+The **Board Autopilot** manager requires a knowledge base. Its `observe` node
+retrieves the top few relevant records *in code* and splices the text into the
+briefing. The model is never told a KB exists.
+
+```js
+const KB_REQUIRE_AS = 'kb';                        // must equal the `as` above
+const KB_MANAGED_BY = `requires:${KB_REQUIRE_AS}`;
+
+// 1. read this agent's own row
+//    GET {api}/projects/{PROJECT_ID}/workflows/{WORKFLOW_TYPE}
+// 2. find the link the platform attached under our alias
+const entry = (row.customMcp || [])
+  .find((e) => e && e.managedBy === KB_MANAGED_BY && e.id && e.url);
+
+// 3. call it through the broker
+//    POST {api}/mcp/broker/{WORKFLOW_UUID}/{entry.id}   → tools/call
+```
+
+If the link is missing, the node logs once, returns an empty block, and the tick
+carries on.
+
+**Choose this** when the retrieval is deterministic, must happen on every run,
+and the model must not be able to skip it or spend a turn deciding to.
+
+:::tip Pin the alias with a test
+A code-driven consumer looks the link up by the literal
+`requires:<alias>`. Assert in a test that the constant in your node and the `as`
+in your `spec` block are the same string — nothing else checks it.
+:::
+
+## Gotchas
+
+**A malformed `ref` is dropped silently.** A wrong kind, a capital letter or an
+underscore inside a segment makes the entry vanish at normalisation, with no
+diagnostic anywhere — the agent deploys without its capability. Copy a working
+ref; do not retype one.
+
+**A bad `as` degrades to the provider slug** rather than failing. That then
+breaks a code-driven consumer looking for a different alias.
+
+**The provider has to publish the entry you name.** If it does not, the deploy
+fails with a message naming the ref.
+
+**Dangling refs fail the deploy loudly.** Provider not bound, endpoint not
+published, link not buildable — each returns an error naming the ref and telling
+you to fix it and re-deploy. The cascade is idempotent, so re-deploying
+re-attaches.
+
+**At run time nothing throws.** Both patterns degrade: an honest skip, or an
+empty block. That is deliberate — a missing capability should not lose the run.
+
+:::caution Self-hosted only, today
+`requires` attaches one agent to another over the per-agent MCP endpoint, and
+that endpoint exists on self-hosted boxes only. A template with a `requires`
+block cannot finish deploying on Zibby Cloud yet.
+:::
+
+## See also
+
+- [`surfaces` and `entryPoints`](./surfaces.md) — what a provider must publish.
+- [Composition](./composition.md) — the other kind of member; the two share one
+  member list.
+- [`remoteMcp`](./remote-mcp.md) — the same idea for a third-party server.

package/docs/templates/sidecars.md

@@ -0,0 +1,163 @@
+---
+sidebar_position: 7
+title: sidecars & sidecarSpecs
+---
+
+# `sidecarSpecs` and `sidecars`
+
+## What it is
+
+Some agents need a long-lived service running beside them: a browser, a vector
+database, a bridge that turns a REST API into tools. Those are **sidecars**.
+
+`sidecarSpecs` carries the **whole specification** — name, a checksum-pinned
+image on Zibby's own CDN, the port, the per-tenant config it reads — rather than
+a name the platform must already know. That is what makes a brand-new
+sidecar-backed agent *a template and nothing else*.
+
+`sidecars` is the short form: a name for a sidecar the platform already ships.
+
+At deploy the control plane fetches the image, **verifies its SHA-256**, loads it
+and starts it on the internal network. The agent's run container never pulls
+anything and never dials it directly.
+
+:::caution Self-hosted only
+Sidecar hosting is not built on Zibby Cloud yet. A template that declares one is
+marked self-hosted-only and the cloud catalog will not deploy it. There is one
+exception, [below](#the-one-cloud-exception).
+:::
+
+## Syntax
+
+```js
+spec: {
+  selfHostOnly: true,
+  sidecarSpecs: [{
+    name: 'openapi-mcp',
+    version: '0.2.3',
+    s3Url: 'https://dl.zibby.app/sidecars/openapi-mcp/0.2.3.tar.gz',
+    sha256: 'caa4ebfc04acf725f3afd0afa8d0ddf942a600eea364ec821351e3f19af53b4f',
+    bytes: 2500336,                        // informational — shown in the dialog
+    arch: {
+      arm64: {
+        s3Url:  'https://dl.zibby.app/sidecars/openapi-mcp/0.2.3-arm64.tar.gz',
+        sha256: '38fe9ca08961eed8c2768e3d036da6deaf4ca2384543ea243deb9685a77ca566',
+        bytes:  2305415,
+      },
+    },
+    port: 8080,
+    healthPath: '/health',
+    warm: true,
+    requestConfigKeys: ['OPENAPI_APIS', 'API_ROOT', 'API_TOKEN'],
+  }],
+  // NO `sidecars: ['openapi-mcp']` — a full spec implies its own name.
+}
+```
+
+## Properties
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `name` | string | **Yes** | lowercase, starts with a letter, letters/digits/hyphens, 2–31 chars. May not shadow a built-in name | — | Re-applied |
+| `port` | integer | **Yes** | 1–65535 | — | Re-applied |
+| `sha256` | string | **Yes** | 64 hex characters | — | Re-applied — a new checksum pulls a new image |
+| `s3Url` | string | **Yes** | an allow-listed host | — | Re-applied |
+| `version` | string | No | a version string you own | none | Re-applied; shown in the Update dialog |
+| `arch.<arch>` | object | No | `{ s3Url, sha256, bytes }`, validated identically | none | Re-applied |
+| `healthPath` | string | No | a path | `/health` | Re-applied |
+| `warm` | boolean | No | | `false` | Re-applied |
+| `bytes` | integer | No | **informational only** — never checked against the download | none | Card only |
+| `dataPath` | string | No | an absolute path — and it must be `/data` | none | Re-applied |
+| `dataPurpose` | string | No | `data`, `credentials` | `data` | Re-applied — decides what uninstall deletes |
+| `requestConfigKeys` | string[] | No | Env keys read **per request** from the declaring agent's own encrypted bag | `[]` | Re-applied |
+| `envKeys` | string[] | No | container-wide environment | `[]` | Re-applied |
+| `publicPaths` | string[] | No | prefixes exposed **anonymously** on your box's public origin — refused by default | none | Re-applied |
+| `storeTypes` | string[] | No | store types this sidecar serves | `[]` | Re-applied |
+| `instancePerAgent` | boolean | No | | `false` | Re-applied |
+| `memoryBytes` / `pidsLimit` | integer | No | 64 MiB – 8 GiB / 16 – 4096 | platform defaults | Re-applied |
+
+`sidecars` is simply `string[]`. A name nobody knows is skipped with a warning,
+not an error.
+
+## One shared service, many isolated tenants
+
+A sidecar is **one process hosting N isolated tenants**, not one container per
+agent. Everything that differs per agent — data *and* configuration — is
+isolated:
+
+- **Data** is keyed by a server-derived tenant key, so different tenants run in
+  parallel and the same tenant serialises.
+- **Configuration and secrets** come from `requestConfigKeys`, injected **per
+  request** from the declaring agent's encrypted Env bag — never as
+  container-wide environment.
+
+That last point is the one people get wrong. Putting an OAuth client id and
+secret in `envKeys` means two projects with different apps collide, and the fix
+is not "error on conflict" — it is per-request injection.
+
+## Gotchas
+
+:::danger A full spec implies its name
+If you declare `sidecarSpecs`, do **not** also list that name in `sidecars`.
+The name is taken from the spec. Repeating it is a second place to keep in sync.
+:::
+
+:::danger Durable state lives at `/data` — one path, every sidecar
+The `dataPath` you declare and the path your app actually writes must be the
+**same string**. Nothing cross-checks them, so a mismatch is silent: the data
+lands in the container's throwaway layer and dies with it, while the volume you
+declared sits empty. A live OAuth token store was lost exactly that way. Do not
+"fix" a mismatch by injecting a path variable — change one of them.
+:::
+
+**A checksum pins bytes, not a CPU.** There is deliberately no fallback between
+architectures: an x86 image verifies perfectly on an ARM box and then dies with
+`exec format error`. Publish and pin each architecture, or that architecture
+fails loudly.
+
+**A URL with no checksum fails closed.** The image is never loaded unverified.
+
+**A template-carried sidecar does not auto-update.** Its version belongs to you:
+it moves when your `version`/`sha256`/`s3Url` move and the user takes the
+Update. Platform-shipped sidecars follow a CDN channel instead.
+
+:::danger A sidecar with no authentication of its own must not declare `publicPaths`
+`publicPaths` exposes those prefixes **anonymously** on your box's public
+origin, with no platform authentication added. Agents and the chat assistant
+reach a sidecar over the internal network and do not need it.
+
+Declare an [`entryPoints.mcp`](./surfaces.md) with `auth: 'bearer-pat'` instead,
+and let the platform's own authenticated endpoint forward to you — it adds the
+token check, the ownership check, and per-request tenant configuration.
+
+It also costs you cloud deployability. See below.
+:::
+
+**`warm: true` is sometimes required, not an optimisation.** A sidecar is
+started by the boot pre-warmer, by a public-path proxy, or by the store router.
+An agent that is dialled directly as an MCP server matches none of those, so
+without `warm` it would never be running.
+
+**Share a spec, do not copy it.** If several templates use the same sidecar,
+import the spec from one place. Two inlined copies at different versions will
+fight, and the last deploy wins — which can silently downgrade the shared engine.
+
+## The one cloud exception
+
+A self-hosted-only template **is** deployable on Zibby Cloud when it is
+browser-host-servable — judged from the declaration, never from the name:
+
+- every carried spec is fully pinned (`name`, `version`, `port`, `s3Url`,
+  `sha256`), **and**
+- no spec declares `publicPaths`, **and**
+- the template declares an `entryPoints.mcp` pointing at one of its sidecars.
+
+One `publicPaths` entry costs the template its cloud deployability.
+
+## See also
+
+- [`surfaces` and `entryPoints`](./surfaces.md)
+- [`stores`](./stores.md) — a store type brings its own sidecar; do not name it
+  twice.
+- [Bring your own sidecar](../self-host/custom-sidecars.md) — the operator route,
+  for a service that is not a catalog agent.

package/docs/templates/stores.md

@@ -0,0 +1,113 @@
+---
+sidebar_position: 3
+title: stores
+---
+
+# `stores`
+
+## What it is
+
+Durable storage the agent needs. Declared **on a node**, not in the
+`spec` block.
+
+At deploy the platform creates (or re-uses) one store per declaration and writes
+its id into the agent's encrypted Env bag under the name you chose. Your code
+never sees an id in the template — it asks for the name and gets the resource.
+
+This is the reference implementation of the naming rule: declare a name, the
+platform binds it, the consumer resolves it late.
+
+## Syntax
+
+```js
+// nodes/ingest-node.js
+import { SKILLS } from '@zibby/core';
+
+export const ingestNode = {
+  name: 'ingest',
+  skills: [SKILLS.DATASET_STORE],        // required — see gotchas
+  stores: [
+    { name: 'knowledge_docs', type: 'docs',   description: 'Verbatim markdown archive' },
+    { name: 'knowledge_meta', type: 'sqlite', description: 'Per-document metadata',
+      schema: {
+        tables: {
+          knowledge_meta: {
+            ddl: 'CREATE TABLE IF NOT EXISTS knowledge_meta (id TEXT PRIMARY KEY, title TEXT)',
+          },
+        },
+      },
+    },
+  ],
+};
+```
+
+The minimal form is just a name and a description:
+
+```js
+stores: [{ name: 'scorecards', description: 'Per-commit engineering scorecard' }],
+```
+
+## Properties
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `name` | string | **Yes** | lowercase, starts with a letter, letters/digits/underscore, ≤ 41 chars. **Unique across the whole agent**, not just the node | — | Re-applied (idempotent). A **new** name creates a **new** store; renaming leaves the old one behind |
+| `type` | string | No | `dataset`, `sqlite`, `file`, `docs`, `postgres` (self-hosted only) | `dataset` | Re-applied. An unknown type fails the deploy loudly |
+| `description` | string | No | any — it is what the agent's store catalogue shows the model | none | Re-applied |
+| `schema` | object | No | `{ tables: { <name>: { ddl } } }` — **`sqlite` only**. Each `ddl` must begin `CREATE TABLE IF NOT EXISTS` and the table it creates must match the key | none | Re-applied, but an existing table is never altered |
+
+## Store types
+
+| Type | Use it for |
+|---|---|
+| `dataset` | append-and-query records — the default |
+| `sqlite` | relational data with a schema you declare |
+| `file` | opaque blobs |
+| `docs` | a verbatim document archive |
+| `postgres` | a vector knowledge base (self-hosted only) |
+
+## What deploy does
+
+1. Computes a stable key from the agent, the node and the name, so re-deploying
+   re-uses the same store instead of creating another one.
+2. Creates the store if it does not exist.
+3. Writes `ZIBBY_STORE__<name> = <store id>` into the encrypted Env bag.
+4. Creates any declared SQLite tables.
+5. Seeds the node's store catalogue so the model can see what it has.
+
+At run time the store skill turns those environment entries back into names, and
+sub-graph children inherit them.
+
+## Gotchas
+
+:::danger A `stores` block on a node with no store skill is silently ignored
+The same node must also declare a store skill (`dataset-store`, or `gbrain` for
+a vector KB) in its **`skills`** array. Putting it in `optionalSkills` instead
+provisions nothing — no store, no error, no warning.
+:::
+
+**Names are unique per agent, not per node.** Two nodes cannot each declare a
+store called `results`.
+
+**If you re-point a store by hand, that wins forever.** Setting
+`ZIBBY_STORE__<name>` yourself to something other than the provisioned id tells
+the platform this is deliberate: it stops re-binding the name and stops applying
+the declared schema.
+
+**A schema on a non-SQLite store is a hard error at deploy**, not a warning.
+
+**Declared tables are created, never migrated.** If a table already exists it is
+left exactly as it is, even when your `ddl` has changed. Adding a column is your
+migration to write.
+
+**A store type brings its own service.** `postgres` pulls the vector-KB engine
+by itself — do not also name it under [`sidecars`](./sidecars.md).
+
+**`postgres` cannot be deployed on Zibby Cloud today.** Templates that need it
+are marked self-hosted-only.
+
+## See also
+
+- [Node declarations](./node-declarations.md) — the store skill is a
+  precondition, not a nicety.
+- [Sidecars](./sidecars.md)

package/docs/templates/surfaces.md

@@ -0,0 +1,184 @@
+---
+sidebar_position: 6
+title: surfaces & entryPoints
+---
+
+# `surfaces` and `entryPoints`
+
+Two blocks, one subject: **which channels your agent offers, and where each one
+lives.**
+
+- `surfaces` — *which* channels the agent's page should show.
+- `entryPoints` — *where* a channel lives when it is not served by the platform
+  itself, and every word the card shows.
+
+---
+
+## `surfaces`
+
+### What it is
+
+The deployed agent's page renders one section per interaction channel.
+`surfaces` says which of them are meaningful, so a pure knowledge-base agent
+does not show a Trigger button that does nothing.
+
+### Syntax
+
+```js
+spec: { surfaces: ['mcp', 'connect'] }
+```
+
+### Properties
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `surfaces` | string[] | No | `cli`, `webhook`, `schedule`, `mcp`, `connect` | `['cli','webhook','schedule','mcp']` | Re-applied |
+
+| Value | Meaning |
+|---|---|
+| `cli` | started from the command line |
+| `webhook` | started by an inbound HTTP call |
+| `schedule` | started by cron |
+| `mcp` | a machine endpoint an MCP client attaches to |
+| `connect` | a public page a **human opens in a browser** to link their own account — an OAuth sign-in, a device pairing, a licence activation |
+
+`connect` is not a webhook: nothing third-party posts to it and it starts no run.
+
+Unknown values are ignored. Declaring nothing gives you the four standard
+channels — **not** all five, because `connect` is opt-in by design.
+
+### Use cases
+
+| Agent shape | Declare |
+|---|---|
+| An ordinary triggerable workflow | nothing |
+| A pure store — running it directly is a no-op, it is driven over MCP | `['mcp']` |
+| A service a person signs into, then uses from their editor | `['mcp', 'connect']` |
+
+### Gotchas
+
+Declaring `mcp` does not create an endpoint — it says the agent has one. The
+endpoint still has to exist.
+
+---
+
+## `entryPoints`
+
+### What it is
+
+For a channel that need not be served by the platform, `entryPoints` names which
+service serves it and at which path. **The URL itself is derived when the page
+is read** — from the service's resolved public mount and your installation's
+origin. No template ever writes a URL down.
+
+For `connect` it also carries every word on the card, because the renderer has
+none of its own.
+
+### Syntax
+
+An MCP endpoint the platform authenticates and forwards to a service:
+
+```js
+spec: {
+  surfaces: ['mcp'],
+  entryPoints: {
+    mcp: {
+      sidecar: 'openapi-mcp',
+      path: '/mcp',
+      auth: 'bearer-pat',
+      label: 'MCP endpoint for the APIs this agent bridges',
+    },
+  },
+}
+```
+
+A sign-in the platform drives, on an agent with no service container at all:
+
+```js
+spec: {
+  surfaces: ['mcp', 'connect'],
+  entryPoints: {
+    connect: {
+      kind: 'oauth',
+      server: 'figma',                  // a name from this agent's own remoteMcp block
+      label: 'Connect your Figma account',
+      button: 'Connect',
+      buttonDisconnect: 'Disconnect',
+      disconnectConfirm: 'Disconnect Figma? The stored sign-in is deleted.',
+      connectedLine: 'Connected to Figma as {account}.',
+    },
+    // NO `mcp` entry — the absence IS the declaration. See below.
+  },
+}
+```
+
+### Properties
+
+Only `mcp` and `connect` can be redirected. `cli`, `webhook` and `schedule` are
+platform mechanics with no alternative home.
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `sidecar` | string | **Yes**, except for `connect` with `kind: 'oauth'` | a service this agent declares, or one the platform ships | — (entry is dropped without it) | Re-applied |
+| `path` | string | **Yes**, same exception | must start with `/`; `..` is refused | — | Re-applied |
+| `auth` | string | No | `bearer-pat`, `connect-bearer`, `none` | `connect-bearer` for `mcp`, `none` for `connect` | Re-applied |
+| `label` | string | No | any | none | Card only |
+| `kind` (connect) | string | No | `sidecar-page`, `oauth` | `sidecar-page` | Re-applied |
+| `server` (connect + `oauth`) | string | **Yes** for that kind | a name from `remoteMcp` | — | Re-applied |
+| copy (`button`, `buttonDisconnect`, `disconnectConfirm`, `disconnectedLine`, `waitingLine`, `connectedLine`, `note`) | string | No | `{account}` is substituted | none — a field you omit renders nothing | Card only |
+
+### `auth` names what the CALLER presents
+
+| Value | The caller presents |
+|---|---|
+| `bearer-pat` | a Zibby access token — the platform authenticates and forwards |
+| `connect-bearer` | the token this agent's own sign-in handed the user |
+| `none` | nothing — the surface authenticates the caller itself |
+
+:::warning A misspelt `auth` is silently corrected, not rejected
+An unrecognised value falls back to the channel's default, so a typo quietly
+describes an authentication your endpoint does not use. Spell it exactly.
+:::
+
+### An absent `entryPoints.mcp` is itself a declaration
+
+Leave it out and **the platform serves the surface itself**, at the agent's own
+authenticated MCP address, with a Zibby bearer token.
+
+That is the right choice whenever your service has no authentication of its own.
+Naming a source when you did not need to is how an endpoint gets taken away from
+the sign-in that feeds it: the declared service wins the address and answers
+every call with its own "missing token".
+
+:::tip One agent, one MCP address
+A declared MCP service takes the **whole** surface — other MCP servers attached
+to the same agent are not merged into it. If you need both, you need two agents.
+:::
+
+### Use cases
+
+| You want | Declare |
+|---|---|
+| Platform-served MCP with a Zibby token | `surfaces: ['mcp']` and nothing else |
+| MCP forwarded to your own service, platform-authenticated | `entryPoints.mcp` with `auth: 'bearer-pat'` |
+| A service that runs its own OAuth and issues its own bearer | `connect` with `auth: 'none'` **and** `mcp` with `auth: 'connect-bearer'` |
+| A hosted third-party MCP the platform signs you into | `connect` with `kind: 'oauth'`, and **no** `mcp` entry |
+
+### Gotchas
+
+**Both halves are required.** A channel must be in `surfaces` *and* have an
+`entryPoints` entry before anything is derived.
+
+**A path the proxy would not serve is never advertised.** If the mount does not
+publish it, the entry is dropped rather than shown as a dead link.
+
+**`connect-bearer` turns off the platform's own token check** on the agent's MCP
+address. Only declare it when your service really does authenticate.
+
+**Service-served entries need a self-hosted box.** A `connect` entry with
+`kind: 'oauth'` works everywhere.
+
+## See also
+
+- [`sidecars`](./sidecars.md), [`remoteMcp`](./remote-mcp.md),
+  [`requires`](./requires.md)