@zibby/skills 2.0.4 → 2.0.6

package/docs/templates/index.md

@@ -0,0 +1,138 @@
+---
+sidebar_position: 1
+title: The declaration model
+---
+
+# Agent templates — the declaration model
+
+An **agent template** is the source of a reusable agent: its graph, its state
+schema, and a **declaration block** that says what the platform must do when
+somebody installs it.
+
+If you have written CloudFormation, you already know the shape:
+
+| CloudFormation | Zibby |
+|---|---|
+| stack template | the template |
+| `Resources` | the declaration blocks (`models`, `stores`, `requires`, …) |
+| `create-stack` | deploying the template from the catalog |
+| `Ref` / logical names | a declared **name** the platform binds at deploy |
+| *Update requires: Replacement* | fields frozen at deploy — see [Update behavior](./update-behavior.md) |
+
+The rule the whole system is built around:
+
+> **Adding a new agent means writing only a declaration.** No new UI branch, no
+> new gate, no code that knows this agent's name.
+
+Everything the platform does for your agent — which model keys it asks you for,
+which stores it provisions, which service containers it pulls, which endpoints
+it publishes, which other agents it installs alongside — is computed from the
+declaration. One renderer, one provisioner, one deploy path, for every agent
+that exists or ever will.
+
+## Where a declaration lives
+
+```
+my-agent/
+├── graph.mjs        ← the graph; NODES carry their own declarations
+├── state.js         ← the input schema; fields can carry deploy-time annotations
+├── workflow.json    ← optional: which events start a run
+├── package.json     ← the versions this agent will be FROZEN at
+└── icon.png         ← optional
+```
+
+plus the **`spec` block** that declares everything else:
+
+```js
+spec: {
+  slug: 'my-agent',
+  tagline: 'One clamped line that IS the card header.',
+  tags: ['Coding'],
+  capabilities: [
+    'Each bullet is one thing, starting with a verb',
+  ],
+  models: [ /* … */ ],
+  surfaces: ['cli', 'webhook', 'schedule', 'mcp'],
+  releaseNotes: 'What changed in THIS version.',
+}
+```
+
+A template with no `spec` block is not in the catalog at all. It is still
+usable as a local scaffold, but nothing syncs, nothing renders, nothing deploys.
+
+:::note `marketplace:` is the same block
+Older templates spell this block `marketplace:`. That spelling still works and
+always will — `spec:` is simply the neutral name for the same thing. You never
+need to rename an existing template.
+:::
+
+## What happens at deploy
+
+```
+        your declaration
+               │
+               ▼
+      ┌────────────────────┐
+      │  the catalog card  │   models → credential slots
+      └────────────────────┘   surfaces → which sections the page shows
+               │               requires → "installs a team of N"
+               ▼
+        you press Deploy
+               │
+   ┌───────────┼───────────┬──────────────┬─────────────┐
+   ▼           ▼           ▼              ▼             ▼
+ stores    sidecars     member         remote MCP    selections
+ created   pulled +     agents         servers       written to
+ + bound   verified     installed      bound         the Env bag
+           + started    + attached
+```
+
+Every step is idempotent. Deploying the same version twice changes nothing;
+deploying a newer version re-runs the steps and keeps what you configured by
+hand.
+
+## Backward compatibility by synthesis
+
+A block you do not declare is not "missing" — the platform **synthesises the
+equivalent**, so an old template behaves exactly as it always did:
+
+- no `models` → one ordinary bring-your-own-key model block;
+- no `surfaces` → the four standard channels (CLI, webhook, schedule, MCP);
+- no `entryPoints` → the platform serves each surface itself.
+
+:::tip Empty is not the same as absent
+`models: []` is a **real declaration**: "this agent runs no model at all". The
+deploy will not ask you for an AI key. Leaving `models` out entirely means
+something different — "give me the normal one".
+:::
+
+## Names, not addresses
+
+No template ever writes down a concrete id, host or URL. It declares a **name**;
+the platform binds that name to a real resource at deploy; and whatever consumes
+it resolves the name late — differently on the cloud and on your own box.
+
+That is why the same template works in both places, and why nothing breaks when
+a resource is re-created.
+
+:::danger Never put a credential in a declaration
+A declaration is public data that travels with the card. Tokens, keys and
+passwords reach an agent **only** through its encrypted Env bag — never through
+a template, a prompt, a trigger payload or a chat message.
+:::
+
+## The blocks
+
+| Block | What it declares |
+|---|---|
+| [`models`](./models.md) | which model(s) the agent runs, and who supplies the key |
+| [`stores`](./stores.md) | durable storage, provisioned at deploy and injected by name |
+| [`requires`](./requires.md) | an endpoint another agent publishes, installed and attached for you |
+| [`dispatchesWorkflow` / `kind`](./composition.md) | other agents this one runs as sub-graphs — a fleet |
+| [`surfaces` / `entryPoints`](./surfaces.md) | which channels the agent offers, and where each one lives |
+| [`sidecars` / `sidecarSpecs`](./sidecars.md) | a long-lived service container the agent needs |
+| [`remoteMcp`](./remote-mcp.md) | a hosted third-party MCP server the agent is for |
+| [deploy-time configuration](./deploy-time-config.md) | pickers, inputs, a default schedule, trigger events |
+| [node declarations](./node-declarations.md) | skills, integrations and vendor pins, per node |
+| [catalog metadata](./catalog-metadata.md) | slug, tagline, tags, release notes, availability |
+| [Update behavior](./update-behavior.md) | what changes on re-deploy, what is seeded once, what is frozen |

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.