@zibby/skills 2.0.3 → 2.0.5

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 |

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)