@zibby/skills 2.0.4 → 2.0.6

package/docs/templates/update-behavior.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/skills",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Built-in skill definitions for the Zibby agent-workflow framework",
   "type": "module",
   "main": "dist/index.js",
@@ -73,7 +73,8 @@
     "./review": {
       "types": "./dist/review.d.ts",
       "default": "./dist/review.js"
-    }
+    },
+    "./markup": {"types": "./dist/lib/markup.d.ts", "default": "./dist/lib/markup.js"}
   },
   "scripts": {
     "build": "node ../scripts/build.mjs && npm run build:types",
@@ -116,10 +117,10 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@resvg/resvg-js": "^2.6.2",
-    "@zibby/agent-workflow": "2.0.4",
+    "@zibby/agent-workflow": "2.0.6",
     "@zibby/bin-oxlint": "^1.73.0",
     "@zibby/bin-semgrep": "^1.169.0",
-    "@zibby/skill-ids": "2.0.4",
+    "@zibby/skill-ids": "2.0.6",
     "echarts": "^6.1.0",
     "mem0ai": "npm:@zibby/mem0ai@^3.0.5",
     "zod": "^3.23.0 || ^4.0.0"
@@ -134,7 +135,7 @@
     }
   },
   "optionalDependencies": {
-    "@zibby/mcp-browser": "2.0.4",
+    "@zibby/mcp-browser": "2.0.6",
     "@zibby/mcp-memory": "*"
   },
   "devDependencies": {