@zibby/skills 2.0.4 → 2.0.5

package/docs/templates/catalog-metadata.md

@@ -0,0 +1,101 @@
+---
+sidebar_position: 11
+title: Catalog metadata
+---
+
+# Catalog metadata
+
+Everything here reaches the **card**. Most of it is presentation, and most of it
+is deliberately excluded from the update signal, so improving your copy never
+pops an "Update available" badge on somebody's deployed agent for nothing.
+
+## Identity and presentation
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `slug` | string | **Yes** | the agent's identity — the folder name, the deploy route, the row of everybody who already installed it | — | **Never change it** |
+| `tagline` | string | No | one clamped line — on the detail card this *is* the header | `''` | Card only |
+| `tags` | string[] | No | catalog sections; the card is grouped by the first one in section order | `[]` | Card only |
+| `browseRank` | number | No | lower sorts first; no rank sorts last | none | Card only |
+| `capabilities` | string[] | No | around five bullets, each one thing, each starting with a verb | `[]` | Card only |
+| `conversationStarters` | string[] | No | example prompts | `[]` | Card only |
+| `icon` | string | No | `./icon.png` beside your graph, or an `https://` URL | the Zibby mark | Card only |
+| `iconPrompt` / `iconBackground` | string | No | inputs to the offline icon generator | none | Card only |
+| `releaseNotes` | string | No | markdown — see below | `''` | Card only |
+| `defaultSlug` | string | No | pre-fills the "Deploy as" field | the slug | Seeded once |
+
+:::tip Tagline vs description
+The detail card reads **tagline first**; the browse cards and the featured hero
+read **description first**. So keep the tagline to a few words and let the
+description be two real sentences. They are not interchangeable.
+:::
+
+## Behaviour and availability
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `maxRuntimeMinutes` | number | No | clamped to the platform window; the default is 25 and the ceiling 60 | none | **Seeded once** — a number you set on the Settings tab survives every Update |
+| `selfHostOnly` | boolean | No | `true` when the agent needs a service container | `false` | Re-applied |
+| `hidden` | boolean | No | `true` keeps the card out of browse while remaining installable by slug | `false` | Re-applied |
+| `kind` | string | No | `fleet`, `app` — see [Composition](./composition.md) | none | Re-applied |
+| `deps` | object | No | extra runtime dependencies the agent needs beyond `@zibby/core` | `{}` | **Frozen at deploy** |
+
+### `maxRuntimeMinutes` — measure it, don't guess
+
+Declare it when you actually know your agent's cost. One shipped agent measured
+a first pass at 24 minutes 53 seconds against a 25-minute default, which made
+its repair pass unreachable on every fresh install — so it declares 60. Another
+declares 30 because a cap that is too *low* gets the container killed between
+two steps and strands work.
+
+A cap that is too low is worse than one that is too high.
+
+### `selfHostOnly` means exactly one thing
+
+**"This agent needs a service container."** It does not mean "absent from the
+cloud": the card still ships to the cloud catalog so its documentation stays
+readable everywhere. Only the deploy is refused, and the refusal says why.
+
+## Release notes
+
+`releaseNotes` is what the "Update available" dialog shows somebody who already
+runs your agent. It is **mandatory for any user-visible change**, and it is
+short.
+
+1. **This version only.** One line per change.
+2. **The outcome, not the mechanism.** What is different for them, in their
+   words — not what you refactored.
+3. **Do not accumulate history.** Drop the previous version's notes rather than
+   prepending to them.
+4. **Ten short lines at most.**
+
+Good:
+
+```
+Answering the team's question is now just replying, once, like a person.
+• Reply in your own words — any wording, any language.
+• Answer on one ticket of a plan and it counts for the whole plan.
+• You no longer touch labels.
+```
+
+Bad: a changelog going back to the initial release, or a paragraph about which
+module was rewritten.
+
+No notes at all gives the user *"No release notes provided by the author"*.
+
+## Gotchas
+
+**`hidden` and `selfHostOnly` are different axes.** `hidden` is visibility;
+`selfHostOnly` is a real constraint. A card can be one, the other, or both.
+
+**A `kind` the platform does not recognise is dropped.** The section you meant
+to appear in simply never appears — check the allowed values.
+
+**Your `spec` block lives outside your template directory**, so a
+metadata-only change moves no source file. The platform tracks it separately, so
+your edit still reaches the card — see [Update behavior](./update-behavior.md).
+
+## See also
+
+- [Update behavior](./update-behavior.md)
+- [The declaration model](./index.md)

package/docs/templates/composition.md

@@ -0,0 +1,97 @@
+---
+sidebar_position: 5
+title: Composition & fleets
+---
+
+# Composition — `dispatchesWorkflow` and `kind`
+
+## What it is
+
+An agent can run **another** catalog agent as a sub-graph. Deploying the parent
+cascades: every declared member is installed as the parent's own child, bound to
+it, and recorded on its row — so one Deploy gives you a whole team.
+
+## Syntax — three forms
+
+**1. The declarative sub-graph node.** The engine records the member for you:
+
+```js
+graph.addNode('build', {
+  workflow: 'frontend-specialist',
+  input:  (state) => ({ ticket: state.ticket }),
+  output: (result) => ({ pr: result.prUrl }),
+});
+```
+
+**2. A single member on a custom node:**
+
+```js
+export const poPlanNode = {
+  name: 'plan',
+  dispatchesWorkflow: 'product-owner',
+  execute: async (state, ctx) => { /* … */ },
+};
+```
+
+**3. A roster — one node fanning out over many members:**
+
+```js
+export const dispatchNode = {
+  name: 'dispatch',
+  dispatchesWorkflow: ['ticket-triage', 'developer', 'frontend-specialist',
+                       'gitlab-code-review', 'generate-test-cases', 'product-owner'],
+  execute: async (state, ctx) => { /* dispatches whichever the manager chose */ },
+};
+```
+
+## Properties
+
+| Name | Where | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|---|
+| `dispatchesWorkflow` | node | string \| string[] | No | catalog slugs | absent | Re-applied — a new member is installed on the next deploy |
+| `kind` | `spec` | string | No | `fleet`, `app` | none | `fleet` is card-only; `app` changes the deploy path |
+| `composedOf` | — | — | **derived, never declared** | — | — | Re-applied |
+
+`kind: 'fleet'` moves the card into the Fleet section of the catalog and lets it
+say "installs a team of N" *before* you install it. It does **not** change how
+the agent deploys.
+
+`kind: 'app'` is different in kind: the card is a hosted application you open in
+a browser, not an agent, and it deploys down a different path.
+
+## What deploy does
+
+1. Builds one ordered member list — sub-graph children first, then anything
+   named by [`requires`](./requires.md).
+2. Installs each member (recursively), in parallel.
+3. Records the bindings on the parent, so a dispatch at run time resolves to the
+   right instance.
+4. Records the member names on the parent's row for the Agents list.
+
+If any member fails, **the whole deploy fails** and the rows this deploy created
+are rolled back. You never end up with half a fleet.
+
+## Gotchas
+
+**A member can be a string or an array — always handle both.** A roster node
+declares many members on one node; reading only the string form installs one and
+leaves every other dispatch failing at run time.
+
+**An agent cannot dispatch an ancestor.** A cycle is refused at deploy.
+
+**A dispatch node runs no model of its own** and is excluded from "apply this
+model to every node".
+
+**A parent collects its children's model keys.** If your child runs a different
+vendor, the deploy asks for that key too — and marks it non-blocking, so a
+branch you will not use never stops the install.
+
+**A member that subscribes to events is suppressed while it is a member.**
+Otherwise one pull request would fire both the fleet (which runs the member
+in-process) and the standalone member — a double review. Deploy the member
+on its own and it starts responding to events again.
+
+## See also
+
+- [`requires`](./requires.md) — the other kind of member.
+- [Deploy-time configuration](./deploy-time-config.md) — event subscriptions.

package/docs/templates/deploy-time-config.md

@@ -0,0 +1,228 @@
+---
+sidebar_position: 9
+title: Deploy-time configuration
+---
+
+# Deploy-time configuration
+
+Four declarations that shape what happens **when somebody installs your agent**:
+what they are asked, what is seeded for them, and what starts a run.
+
+| Block | Writes to | Asked at |
+|---|---|---|
+| [`selections`](#selections) | the agent's Env bag — **configuration** | deploy |
+| [`deployInput`](#deployinput) | the agent's default trigger payload | deploy |
+| [`defaultSchedule`](#defaultschedule) | the agent's schedules | deploy (once) |
+| [`workflow.json` → `triggers`](#triggers) | the agent's trigger settings | every deploy |
+
+---
+
+## `selections`
+
+### What it is
+
+A value the operator must **pick from a live list some integration owns** —
+which board this agent works, which space it writes to — rather than dig an id
+out of a URL and type it into an environment variable.
+
+One declaration renders a dropdown of the real options the connected system
+returns, and the answer lands in the agent's encrypted Env bag.
+
+### Syntax
+
+```js
+spec: {
+  selections: [{
+    id: 'board',
+    label: 'Board',
+    from: 'board_tracker',                  // a provider, or a one-of group
+    providerKey: 'BOARD_TRACKER',           // records WHICH provider was chosen
+    keys: {
+      vikunja: 'BOARD_VIKUNJA_PROJECT_ID',
+      jira:    'BOARD_JIRA_PROJECT_KEY',
+    },
+    required: true,
+    help: 'The board this agent polls for tickets marked ready.',
+  }],
+}
+```
+
+### Properties
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `id` | string | **Yes** | lowercase, starts with a letter, ≤ 41 chars, unique in the array | — | Seeded once |
+| `label` | string | **Yes** | non-empty — it is what the picker is called | — | Card only |
+| `from` | string | **Yes** | a provider id, or a one-of group the platform already knows | — | Seeded once |
+| `keys` | object | **Yes** | `{ provider: 'ENV_KEY' }` — every provider must belong to `from` | — | Seeded once |
+| `providerKey` | string | **Yes** when the group offers more than one provider | a writable Env key | none | Seeded once |
+| `required` | boolean | No | | `true` | Seeded once |
+| `help` | string | No | | none | Card only |
+
+### Why `keys` is a map
+
+The value written is a different *kind* of thing per provider: Vikunja addresses
+a board by a numeric project id, Jira by a project key (`"PROJ"`). One
+environment variable cannot express that, and collapsing them would leave the
+reader guessing which system's id it holds.
+
+### Gotchas
+
+**A one-of group with more than one option needs a `providerKey`.** A choice
+that records nothing deploys an agent that cannot tell which system it was
+pointed at — so the declaration is refused.
+
+**A provider with no key in `keys` is simply not offered.** That is legitimate:
+some systems are reached another way and have no list to show.
+
+**It is seeded once.** A value you have already set survives every Update, and
+the deploy tells you what it kept.
+
+---
+
+## `deployInput`
+
+### What it is
+
+A field of your agent's input schema, annotated so the deploy asks for it once
+and stores it as the agent's default trigger payload.
+
+### Syntax
+
+```js
+// state.js
+repoUrl: z.string().url()
+  .meta({ deployInput: {
+    required: true,
+    source: 'github-repo',
+    label: 'GitHub repo',
+    help: 'Pick the repository whose flaky tests this agent should fix.',
+  }}),
+
+circleProjectSlug: z.string().optional()
+  .meta({ deployInput: {
+    source: 'circleci-project',
+    deriveFrom: 'repoUrl',                 // resolved automatically, never typed
+    label: 'CircleCI project',
+  }}),
+```
+
+### Properties
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `required` | boolean | No | gates the deploy in the dashboard, the CLI **and** over MCP | `false` | Seeded once |
+| `source` | string | No | which control renders it, or which resolver fills it | none | Seeded once |
+| `deriveFrom` | string | No | another field's name — auto-resolved, never user-entered, never required of the user | none | Seeded once |
+| `label` / `help` | string | No | | the field name | Card only |
+
+### Gotchas
+
+`deployInput.required` is the **deploy gate**, which is separate from whether
+the field is optional in your schema.
+
+Use `selections` instead when the value is agent *configuration* your code reads
+from the environment — not part of a run's input.
+
+---
+
+## `defaultSchedule`
+
+### What it is
+
+A cron-driven agent does nothing until something wakes it. `defaultSchedule` is
+the floor: deploy installs it as the agent's ordinary schedule **when the agent
+has no schedule at all**.
+
+### Syntax
+
+```js
+spec: {
+  defaultSchedule: { cron: '*/15 * * * *', name: 'Board tick' },
+}
+```
+
+### Properties
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `cron` | string | **Yes** | a **5-field** Unix cron (`m h dom mon dow`) | — | Seeded once |
+| `timezone` | string | No | an IANA zone | `UTC` | Seeded once |
+| `name` | string | No | | none | Seeded once |
+| `input` | object | No | the trigger body | `{}` | Seeded once |
+
+A one-shot date is refused — a template cannot know a date.
+
+### Gotchas
+
+**Any existing entry blocks the seed.** One you created, the seeded one after
+you edited it, a paused one (pausing is a disable, not a delete), even a
+one-shot that already fired. So an Update can never resurrect a schedule you
+paused, and never re-points one you changed.
+
+**One entry, not an array.** The declaration is a floor, and a floor is one
+cadence. An agent that needs several schedules has an operator who set them, and
+seed-once means those are never touched.
+
+---
+
+## `triggers`
+
+### What it is
+
+An optional `workflow.json` beside your graph, declaring how runs start. It is
+re-applied on **every** deploy, including an Update.
+
+### Syntax
+
+```json
+{ "triggers": { "events": ["github.pr.opened", "github.pr.updated"] } }
+```
+
+```json
+{ "triggers": { "api": true } }
+```
+
+### Properties
+
+| Name | Type | Required | Allowed values | Default | Update behavior |
+|---|---|---|---|---|---|
+| `api` | boolean | No | `true` ships the inbound webhook on by default | off (opt-in) | Re-applied |
+| `events` | string[] | No | `github.pr.opened`, `github.pr.updated`, `github.pr.commented`, `github.pr.mentioned`, and the `gitlab.mr.*` equivalents | `[]` | Re-applied |
+
+Inbound webhooks are routed **by subscription, not by agent name**: a delivery is
+normalised to an event, the repository is resolved to a project, and every
+subscribed agent gets its own independent run.
+
+### Gotchas
+
+**A member of a fleet is suppressed from event routing while it is a member.**
+Otherwise one pull request fires both the fleet — which runs the member itself —
+and the standalone member, giving you two reviews. Deploy the member on its own
+and it starts responding again.
+
+---
+
+## Sample trigger bodies
+
+Two card-only fields that make the Trigger dialog usable:
+
+```js
+spec: {
+  triggerExample:  { ticketKey: 'PROJ-123' },
+  triggerExamples: [
+    { label: 'board tick', body: '{}' },
+    { label: 'one ticket', body: '{"ticketKey":"PROJ-123"}' },
+    { label: 'plan from a PRD', body: '{"prd":"# Feature\\n\\nAs a user I want …"}' },
+  ],
+}
+```
+
+`triggerExample` pre-fills the editable body. `triggerExamples` renders one
+click-to-use reference per source below it. Both must be **valid JSON** — JSON
+has no comments.
+
+## See also
+
+- [Update behavior](./update-behavior.md)
+- [Composition](./composition.md)

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 |