@zibby/skills 2.0.3 → 2.0.5

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)

package/docs/templates/update-behavior.md

@@ -0,0 +1,108 @@
+---
+sidebar_position: 12
+title: Update behavior
+---
+
+# Update behavior
+
+CloudFormation tells you, per property, whether a change updates the resource in
+place or replaces it. Zibby's declaration model has the same question and four
+answers. Every properties table in this section carries the column.
+
+| Class | What happens on the next deploy |
+|---|---|
+| **Re-applied** | the platform re-runs the action — provision the store, register the sidecar, attach the endpoint, bind the server. Idempotent: nothing is duplicated and nothing working is broken |
+| **Seeded once** | written on the **first** install only. Whatever the operator set afterwards survives every Update |
+| **Card only** | reaches the catalog card and nothing else. A deployed agent never consumes it, so changing it never offers an Update |
+| **Frozen** | baked into the deployed agent when it was installed. Changing it needs a re-deploy |
+
+---
+
+## Seeded once — the list
+
+These are written on a fresh install and never again:
+
+- [`selections`](./deploy-time-config.md#selections) — a value already set is kept, and the deploy tells you so
+- [`defaultSchedule`](./deploy-time-config.md#defaultschedule) — **any** existing schedule blocks the seed, including a paused one
+- [`deployInput`](./deploy-time-config.md#deployinput) values
+- [`maxRuntimeMinutes`](./catalog-metadata.md)
+- `defaultSlug` — an agent's name is fixed at first install
+
+The rule behind all of them: **the platform never overwrites a decision you
+made.** If your agent needs an operator to change something, say so in the
+release notes; do not try to write it for them.
+
+---
+
+## Frozen — why a published fix does not reach a deployed agent
+
+:::danger This is the one that surprises people
+When you deploy an agent, the platform stores **that version's source** —
+including its `package.json` and every version range in it — against the agent.
+That copy is what runs, forever, until somebody re-deploys.
+
+So publishing a fixed package **does not reach an agent that is already
+running**. An agent installed against `^0.1.x` can never pick up a `0.2.x`. It
+does not error; the runs simply keep failing the same way.
+:::
+
+**The fix is always a re-deploy** — take the Update on the agent's page, or
+deploy the card again. There is no other route.
+
+The same is true of the agent's `deps`, and of anything else that travels inside
+the source bundle.
+
+---
+
+## What lights the "Update available" badge
+
+Two independent signals, either of which is enough:
+
+1. **The template's files changed** — a checksum over your template directory.
+2. **The declaration changed** — a per-template signature over your
+   `spec` block, minus the fields listed as *Card only*.
+
+The second exists because your `spec` block lives **outside** the
+template directory, so a metadata-only change (a sidecar version pin, a new
+`selections` picker) moves no source byte and the first signal cannot see it.
+
+The rule the badge states, and the one to test your own field against:
+
+> **Re-installing this agent from the current template would change this agent.**
+
+A field is excluded from the signal only when updating provably changes nothing
+for somebody already running it — tags, taglines, icons, capability bullets,
+sample trigger bodies, and the release notes themselves. (Notes *describing* an
+update cannot be the reason to offer one.)
+
+:::tip Why your card is not showing an update
+Two common causes:
+
+- You changed only a *Card only* field. That is working as designed — the card
+  updated, nobody was offered a re-install.
+- You added a new declared field to a template but the platform is not tracking
+  it yet. A field that is copied but not tracked only ever lands on rows written
+  for some other reason.
+:::
+
+---
+
+## Idempotency, in practice
+
+Everything in the *Re-applied* class is safe to run repeatedly:
+
+| Action | On re-deploy |
+|---|---|
+| Store provisioning | the same store is re-used; a store you re-pointed by hand stays re-pointed |
+| Sidecar registration | the same image, unless the pinned version or checksum moved |
+| `requires` attachment | an existing link is kept; a stale one is replaced; one you added by hand is adopted |
+| `remoteMcp` binding | matched by URL and left byte-for-byte, which is what keeps an OAuth grant alive |
+| Member agents | re-deployed in place; the bindings do not churn |
+
+And one thing that is not idempotent, by nature: **renaming**. A renamed store
+is a new store; a renamed `slug` is a new agent. Nothing migrates the old one.
+
+## See also
+
+- [The declaration model](./index.md)
+- [Catalog metadata](./catalog-metadata.md) — release-notes rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/skills",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Built-in skill definitions for the Zibby agent-workflow framework",
   "type": "module",
   "main": "dist/index.js",
@@ -116,10 +116,10 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@resvg/resvg-js": "^2.6.2",
-    "@zibby/agent-workflow": "2.0.3",
+    "@zibby/agent-workflow": "2.0.5",
     "@zibby/bin-oxlint": "^1.73.0",
     "@zibby/bin-semgrep": "^1.169.0",
-    "@zibby/skill-ids": "2.0.3",
+    "@zibby/skill-ids": "2.0.5",
     "echarts": "^6.1.0",
     "mem0ai": "npm:@zibby/mem0ai@^3.0.5",
     "zod": "^3.23.0 || ^4.0.0"
@@ -134,7 +134,7 @@
     }
   },
   "optionalDependencies": {
-    "@zibby/mcp-browser": "2.0.3",
+    "@zibby/mcp-browser": "2.0.5",
     "@zibby/mcp-memory": "*"
   },
   "devDependencies": {

package/docs/recipes/bug-autofix.md

@@ -1,85 +0,0 @@
----
-sidebar_position: 4
-title: Bug-autofix agent
----
-
-# `bug-autofix` — ticket → fix PR → tracker writeback
-
-The flagship orchestrator agent. It polls a tracker for new bugs, classifies each one, opens a fix PR for the autofixable ones, and writes the result back to the tracker — chaining three reusable building-block agents via **sub-graph dispatch**.
-
-```
-poll (this graph)
-  ↓ found a ticket?
-triage     → sub-graph: ticket-triage      → { severity, shouldAutofix, summary }
-  ↓ severity ≥ AUTOFIX_MIN_SEVERITY AND shouldAutofix AND repo configured?
-  ├─ yes → code_fix → sub-graph: code-fix  → { pr_url, branch }
-  │            ↓
-  └─ no ───────────────────────────────────────────┐
-                                                     ↓
-writeback  → sub-graph: tracker-writeback   (runs on BOTH branches)
-  ↓
- END
-```
-
-High-severity, concrete, autofixable bugs get a fix PR opened and the Jira ticket moved to *In Review*. Everything else (noise, vague, too-big, below threshold, or no repo configured) is triaged and a human is notified — no PR.
-
-## The three building-block agents
-
-`bug-autofix` is an orchestrator: each step is a separate, independently deployable agent it dispatches as a sub-graph. Deploy all four in the same project.
-
-| Step | Building block | Input | Output |
-|---|---|---|---|
-| `triage` | `ticket-triage` | `{ ticket }` | severity (`CRITICAL…NOISE`), `shouldAutofix`, summary |
-| `code_fix` | `code-fix` | `{ ticket, repo }` | `{ pr_url, branch }` — clones, fixes with an inline test-gate, opens a PR |
-| `writeback` | `tracker-writeback` | `{ ticket, pr_url?, branch?, result }` | transitions the issue, comments the PR link, posts to Slack/Lark |
-
-Each block is usable on its own — `ticket-triage` is a fine standalone classifier; `code-fix` is a standalone clone→fix→PR agent.
-
-## Sub-graph dispatch
-
-A child step is declared with `{ workflow }` on the node:
-
-```js
-graph.addNode('triage', {
-  workflow: 'ticket-triage',                  // child deploy slug
-  input:  (state) => ({ ticket: state.poll.ticket }),
-  output: 'classify',                         // dot-path on the child's final state
-});
-```
-
-The engine spawns the child as a **separate execution** (its own run row + Fargate task, or in-process when runtime tags match), links it to the parent for the Activity-tab tree and cancellation cascade, polls until terminal, and extracts `output` back into the parent state under the node name.
-
-## Trigger
-
-Cron poll (default) or per-ticket webhook. Each run processes ONE ticket; the next tick/webhook handles the next.
-
-```json
-{ "jql": "issuetype = Bug AND statusCategory != Done ORDER BY updated DESC" }   // cron
-{ "ticketKey": "PROJ-123" }                                                      // webhook
-```
-
-## Config (ENV tab)
-
-| Var | Meaning |
-|---|---|
-| `REPO_URL` | Repo the fix targets. Unset → no autofix, notify-only. |
-| `REPO_NAME` | Short repo name (default: derived from `REPO_URL`). |
-| `REPO_BRANCH` | Base branch (default `main`). |
-| `AUTOFIX_MIN_SEVERITY` | Routing floor for code-fix (default `MEDIUM`). |
-
-Plus the children's own config: Jira connected (triage/poll/writeback), GitHub connected (code-fix), and `SLACK_CHANNEL` / `LARK_RECEIVE_ID` (writeback).
-
-## Scope (v1)
-
-- **In:** poll → triage → (autofix?) → code-fix → writeback, end-to-end to "PR opened + Jira written back".
-- **Out:** deploy / verify / rollback; an auto re-dispatch loop; in-engine approval. The open PR is the human gate.
-- **Tracker seam:** Jira is implemented; GitHub / Linear are extension points in the child templates.
-
-## Deploy
-
-```bash
-zibby agent templates                         # browse the marketplace
-zibby agent new bug-autofix -t bug-autofix    # scaffold the orchestrator
-# ...also scaffold + deploy ticket-triage, code-fix, tracker-writeback in the same project
-zibby agent deploy bug-autofix
-```