@zibby/skills 2.0.4 → 2.0.5

package/docs/templates/models.md

@@ -0,0 +1,157 @@
+---
+sidebar_position: 2
+title: models
+---
+
+# `models`
+
+## What it is
+
+At deploy the platform has to decide two things: which model credentials to ask
+you for, and whether a missing one should block the install. `models` is the
+declaration those decisions are computed from.
+
+Each block says **what kind** of model, **which node** it belongs to, **where**
+the key is consumed, and **whether you supply it**. The deploy dialog and the
+model disc on the agent's graph are generic renderings of this array — there is
+no per-agent special case anywhere.
+
+## Syntax
+
+```js
+spec: {
+  models: [
+    {
+      kind: 'llm',                 // 'llm' | 'embedding'
+      target: 'agent',             // 'agent' | 'sidecar'
+      role: 'review',              // the graph NODE this block belongs to
+      label: 'Review',             // the row heading in the deploy dialog
+      byok: true,                  // true → a real picker; false → a read-only row
+      options: ['claude', 'codex', 'gemini'],
+      required: true,              // does a missing key block the deploy?
+      note: 'Reads the diff and writes the review.',
+    },
+    {
+      kind: 'llm', target: 'agent', role: 'triage', label: 'Triage',
+      byok: false, required: true,
+      followsVendorOf: 'review',                       // tracks another block's vendor
+      fixedModelByVendor: {                            // …and shows what it then runs
+        claude: 'haiku-4.5',
+        codex:  'gpt-4o-mini',
+        gemini: 'gemini-3-flash',
+      },
+      note: 'Fixed — a cheap fast-tier model decides how much review depth the change needs.',
+    },
+  ],
+}
+```
+
+## Properties
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `kind` | string | No | `llm`, `embedding` | `llm` | Re-applied on the next deploy |
+| `target` | string | No | `agent` (the run container), `sidecar` (a service reads it per request) | `agent` | Re-applied |
+| `role` | string | No | a node id in this agent's graph | none | Re-applied |
+| `label` | string | No | any | the vendor name | Card only |
+| `byok` | boolean | No | `true`, `false` | `true` | Re-applied |
+| `provider` | string | No | e.g. `openai` | none | Re-applied |
+| `options` | string[] | No | vendor ids for `kind: 'llm'`; **model ids** for `kind: 'embedding'` | `[]` | Re-applied |
+| `default` | string | No | one of `options` | none | Re-applied |
+| `required` | boolean | No | `true`, `false` | `true` | Re-applied — **this is the deploy gate** |
+| `followsVendorOf` | string | No | another block's `role` | none | Re-applied |
+| `fixedModelByVendor` | object | No | `{ vendor: modelId }` | none | Re-applied |
+| `note` | string | No | one honest sentence | none | Card only |
+
+## The three decisions
+
+**`target` — where the key is consumed.**
+`agent` puts it in the run container's environment. `sidecar` routes it to a
+service container that reads it **per request**, from the declaring agent's own
+encrypted Env bag. One shared service, many isolated tenants.
+
+**`byok` — what the dialog renders.**
+`true` gives you a real picker that collects a key. `false` gives you an honest,
+read-only line describing what actually runs. It is never a text box that does
+nothing.
+
+**`required` — whether a missing key blocks the install.**
+`required: false` is how an agent says "I need no AI key". Use it for a block
+that names an identity rather than adding a dependency — a deterministic node
+that never invokes a model.
+
+## Use cases
+
+| You want | Declare |
+|---|---|
+| An ordinary bring-your-own-key agent | nothing — it is synthesised for you |
+| An agent that runs no model at all | `models: []` |
+| A different model per node, chosen by the operator | one block per model-running node, each with its own `role` |
+| A cheap fixed tier behind an operator-chosen one | `byok: false` + `followsVendorOf` + `fixedModelByVendor` |
+| An embedding model used by a knowledge-base service | `kind: 'embedding', target: 'sidecar', provider: 'openai', options: [<model ids>]` |
+| A locked identity badge with no key | `byok: false, required: false` |
+
+### Example — one block per model-running node
+
+The shipped **Product Owner** agent runs three separate judgements, each on its
+own node, each with its own picker:
+
+```js
+models: [
+  { kind: 'llm', target: 'agent', role: 'plan',   label: 'Planner',
+    byok: true, options: ['claude','codex','gemini'], required: true,
+    note: 'Reads the PRD and the repository, then writes the tickets.' },
+  { kind: 'llm', target: 'agent', role: 'review', label: 'Plan reviewer',
+    byok: true, options: ['claude','codex','gemini'], required: true,
+    note: 'The second opinion that fails a weak plan back to the planner.' },
+  { kind: 'llm', target: 'agent', role: 'judge',  label: 'Acceptance judge',
+    byok: true, options: ['claude','codex','gemini'], required: true,
+    note: 'Judges a pull request against the ticket\'s acceptance criteria.' },
+]
+```
+
+### Example — an embedding model consumed by a service
+
+```js
+models: [{
+  kind: 'embedding',
+  role: 'kb',
+  target: 'sidecar',
+  byok: true,
+  provider: 'openai',
+  options: ['text-embedding-3-small', 'text-embedding-3-large'],
+  default: 'text-embedding-3-small',
+  required: true,
+}]
+```
+
+## Gotchas
+
+**`options` means different things per `kind`.** For `kind: 'llm'` they are
+vendor ids. For `kind: 'embedding'` they are model ids, and the picker offers
+them directly.
+
+**`role` must match a node id exactly.** A block whose `role` names no node
+binds to nothing: the pinned tier stops applying, and the node renders a free
+picker whose choice the node's own code then ignores. If your node ids live in
+a constant, import it — do not retype the string.
+
+**A composite agent collects its children's keys too.** If your agent dispatches
+another agent, that child's model blocks are appended to yours automatically,
+marked non-blocking and labelled with whose they are. You do not declare them.
+
+**Probe a model id before you declare it.** An id that does not exist makes the
+vendor's API reject the call, and the turn comes back empty rather than with an
+error.
+
+**Credentials are one per vendor.** The key in the "Codex · OpenAI" slot is the
+same key OpenAI embeddings use. At run time the order is: a key supplied for
+this agent, then the project's credential for that vendor, then (self-hosted
+only) the box's own environment. Nobody should ever paste the same key twice.
+
+## See also
+
+- [Node declarations](./node-declarations.md) — a node's `agent:` pin is what
+  *locks* a vendor; `models` describes it.
+- [Sidecars](./sidecars.md) — `target: 'sidecar'` needs a service container.
+- [Update behavior](./update-behavior.md)

package/docs/templates/node-declarations.md

@@ -0,0 +1,149 @@
+---
+sidebar_position: 10
+title: Node declarations
+---
+
+# Node declarations
+
+Some declarations live on a **graph node**, not in the `spec` block,
+because they are about what that node needs.
+
+| Field | Declares |
+|---|---|
+| `skills` | the tools this node gets, and the integrations the agent requires |
+| `optionalSkills` | integrations that improve the node but never block a deploy |
+| `agent` | a vendor this node is locked to |
+| `stores` | durable storage — see [`stores`](./stores.md) |
+| `dispatchesWorkflow` | a member agent — see [Composition](./composition.md) |
+
+---
+
+## `skills` and `optionalSkills`
+
+### What it is
+
+A node's single "what this node needs" list. It drives four things at once:
+
+1. the MCP tools the model gets **at that node**;
+2. the skill's prompt fragment, appended to the node's prompt;
+3. the required/optional integrations shown on the card and enforced at deploy;
+4. for a no-connection skill, the on/off switch in the agent's Settings.
+
+### Syntax
+
+```js
+import { SKILLS } from '@zibby/core';
+
+graph.addNode('review', {
+  prompt: …,
+  outputSchema: Review,
+  skills: [SKILLS.GITHUB, SKILLS.ARTIFACT],
+  optionalSkills: [SKILLS.SENTRY],
+});
+```
+
+### Required vs optional
+
+| Declared in | Surfaces as | Blocks Deploy? |
+|---|---|---|
+| `skills`, and the skill needs a connection | **required** | **Yes** — the Deploy button is blocked until it is connected |
+| `skills`, and the skill is marked optional | optional | No |
+| `optionalSkills` | optional | **Never** |
+| the same skill in **both** arrays on one node | optional **for that node only** | No |
+
+That last row is the useful one. A skill can be required by one node and merely
+nice-to-have on another; listing it in a node's `optionalSkills` demotes it for
+**that node** and cannot cancel a different node's requirement.
+
+The card shows required and optional in separate groups — "Connect" versus
+"Connect (optional)" — and only the required group can stop an install.
+
+### One-of groups
+
+Some entries in the array are not skills at all: they are markers that resolve
+to *any one of* a set of providers.
+
+| Marker | Satisfied by |
+|---|---|
+| `board_tracker` | Jira **or** Vikunja |
+| `doc_source` | Google Docs **or** Notion **or** Lark Docs |
+| `chat_notify` | Slack **or** Lark |
+
+Connect any member and the requirement is met. Entries the platform does not
+recognise are skipped with a warning, so an unknown id costs you nothing.
+
+### Toggleable skills
+
+A few skills need no connection at all — codebase memory, code scanning,
+artifacts. They render as a simple on/off switch, default on, and the operator
+can turn them off per agent.
+
+:::danger Bind a toggleable skill on `skills`, not `optionalSkills`
+The switch will appear either way — but **the tools will not**. Skills reach the
+model only through a node's `skills`; `optionalSkills` is an integration-surface
+declaration that the engine never reads. Put a toggleable skill in
+`optionalSkills` and you ship a switch that controls nothing.
+:::
+
+### Gotchas
+
+**`optionalSkills` is not part of the serialised graph.** It is read from your
+source when the catalog is built, so it is visible on the card — but anything
+that re-derives from a stored graph will not see it. Treat it as a card-level
+declaration, never as a runtime one.
+
+**A store skill is a precondition for [`stores`](./stores.md).** Without it, a
+`stores` block on that node provisions nothing, silently.
+
+---
+
+## `agent` — pinning a node to a vendor
+
+### What it is
+
+Locks one node to one coding-agent vendor, regardless of what the operator picks
+elsewhere.
+
+### Syntax
+
+```js
+graph.addNode('plan', { prompt, outputSchema: Plan, agent: 'claude' });
+```
+
+### Properties
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `agent` | string | No | `claude`, `codex`, `gemini` | unpinned — the operator's choice applies | Frozen into the published graph; the credential slots are re-applied |
+
+### What it does at deploy
+
+The distinct set of pins across your graph becomes the agent's vendor
+requirement:
+
+| Pins found | Deploy asks for |
+|---|---|
+| none | any vendor — the picker offers all of them |
+| one | that vendor only |
+| several | one credential per vendor |
+
+Children you dispatch contribute their pins too, so a parent on Claude that
+dispatches a Codex child collects both keys.
+
+### Gotchas
+
+**A pinned node is invisible to "apply this model to every node".** It is
+*locked* — that is the point — so it never receives an operator's model choice.
+If every model-running node is locked, there is nothing left for the operator to
+pick.
+
+**There is no node-level `model:` declaration.** A model comes from one of three
+places: the operator's per-node pick, a literal in your node's own code, or —
+best — [`models[].fixedModelByVendor`](./models.md) joined to the node by
+`role`. Only the third is visible on the card and the canvas. Prefer it.
+
+## See also
+
+- [`models`](./models.md), [`stores`](./stores.md),
+  [Composition](./composition.md)
+- [Skills](../concepts/skills.md)

package/docs/templates/remote-mcp.md

@@ -0,0 +1,105 @@
+---
+sidebar_position: 8
+title: remoteMcp
+---
+
+# `remoteMcp`
+
+## What it is
+
+The hosted, third-party MCP servers this agent is **for**. Declaring one means a
+customer who installs the card never has to know an API call exists: deploy
+binds the server onto the agent, the owner authorises it once from the agent's
+page, and the platform holds the grant encrypted from then on.
+
+The declaration is pure data — a name, the server's own public URL, and which
+authentication **the server** uses. It can never carry a credential.
+
+## Syntax
+
+```js
+spec: {
+  remoteMcp: [{
+    name: 'figma',
+    url:  'https://mcp.figma.com/mcp',
+    auth: 'oauth',
+  }],
+}
+```
+
+## Properties
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `name` | string | **Yes** | any — this is the handle `entryPoints.connect.server` refers to | — | Re-applied (matched by URL) |
+| `url` | string | **Yes** | must parse; credential-shaped query parameters are stripped | — | Re-applied |
+| `auth` | string | No | `oauth`, `bearer` — **anything else drops the whole entry** | absent | Re-applied |
+
+`bearer` and "no `auth`" produce the same stored entry, on purpose: a template
+carries no token, so there is nothing to distinguish.
+
+## What deploy does
+
+**Without `auth: 'oauth'`** — the server is bound onto the agent immediately.
+
+**With `auth: 'oauth'`** — deploy binds **nothing**. The agent carries the
+declaration; the server entry is created **when the sign-in completes**. A
+freshly deployed agent therefore shows no server under its custom MCP list,
+because nothing is connected yet — that list holds exactly what is connected.
+
+Binding is **idempotent by URL and additive**. Re-deploying keeps the existing
+entry byte-for-byte, which is what keeps the OAuth grant intact. Removing the
+declaration never removes a server somebody connected — that stays an explicit
+action.
+
+## Pairing it with a Connect card
+
+`remoteMcp` says *what the server is*. [`entryPoints.connect`](./surfaces.md)
+says *what the sign-in looks like*, and refers to the server by **name**:
+
+```js
+spec: {
+  remoteMcp: [{ name: 'figma', url: 'https://mcp.figma.com/mcp', auth: 'oauth' }],
+  surfaces: ['mcp', 'connect'],
+  entryPoints: {
+    connect: {
+      kind: 'oauth',
+      server: 'figma',
+      label: 'Connect your Figma account',
+      button: 'Connect',
+      buttonDisconnect: 'Disconnect',
+      connectedLine: 'Connected to Figma as {account}.',
+    },
+  },
+}
+```
+
+Because the card comes from the declaration rather than from a live server row,
+the Connect button is on the page from the moment you deploy and stays there
+whatever happens to the connection.
+
+## Gotchas
+
+:::warning The identity is the owner's
+An agent runs with its own role and resolves nothing about whoever is talking to
+it. Anyone who can reach an authorised agent's chat surface acts with the
+owner's third-party account. Say so in your card copy, and do not put an
+authorised agent in a shared channel.
+:::
+
+**Never give one agent two MCP addresses.** An agent that both declares a remote
+server *and* hosts its own MCP sidecar will have the sidecar win the address and
+answer every call with its own "missing token", while the OAuth grant sits
+unused on the other one. One card, one address, one sign-in.
+
+**Credential-shaped query parameters are stripped from the URL** before it is
+stored. A template must never carry a credential — and the strip is also what
+stops a duplicate server being attached on every re-deploy.
+
+**Servers are matched by URL, not by name**, because the owner may rename an
+entry on their own page.
+
+## See also
+
+- [`surfaces` and `entryPoints`](./surfaces.md)
+- [`requires`](./requires.md) — the same shape, for one of your own agents.

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.