@zibby/skills 0.2.0 → 0.2.2

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/skills",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Built-in skill definitions for the Zibby agent-workflow framework",
   "type": "module",
   "main": "dist/index.js",

package/docs/concepts/designing-agents.md

@@ -164,6 +164,52 @@ graph.addNode('build_report', {
   every agent, not a registry Store).
 :::
 
+### File-store size limit — and how to handle big files
+
+A `file` store's per-file cap is **4 MiB of raw bytes** (the content travels
+base64-inside-JSON through the API). Two ways past it:
+
+- **A relational/append-only shape? Use `sqlite`/`dataset`, not `file`.** Those
+  aren't whole-file uploads — they take rows/records, so the 4 MiB blob cap
+  doesn't apply. This is the right move for raw event data (commits, worklogs).
+- **A genuinely large blob** (a multi-MB `.jsonl` a script must read whole)?
+  **gzip it, transparently.** Text compresses well; store the compressed bytes
+  and decompress on read, so the generating script still sees the original file:
+
+  ```js
+  // write node: gzip + base64 → store as <name>.gz.b64
+  import { gzipSync } from 'node:zlib';
+  const packed = gzipSync(Buffer.from(rawText)).toString('base64'); // 5.6MB → ~0.8MB
+  await ds(fileStore, 'put', { path: 'big.jsonl.gz.b64', content: packed });
+
+  // read node: fetch → base64-decode → gunzip → original file on disk
+  import { gunzipSync } from 'node:zlib';
+  const got = await ds(fileStore, 'get', { path: 'big.jsonl.gz.b64' });
+  const raw = gunzipSync(Buffer.from(got.content, 'base64')).toString('utf8');
+  ```
+
+  Keep the list of "which files are compressed" as data (one array), so adding a
+  big file later is a one-line change — the read/write nodes stay generic.
+
+:::caution Check every dependency's SIZE up front
+When you list a store's inputs, don't glob one extension and assume — a single
+oversized dependency (e.g. a 5.6 MB `.jsonl` hiding among small `.json`s) is what
+trips the cap. Enumerate the real files + their bytes before wiring the store.
+File paths accept Unicode (`报告.html` is fine); only `/ \ : ? # [ ] " < > | *`
+and control characters are rejected.
+:::
+
+### Debugging a self-host run when logs look truncated
+
+Self-host truncates long per-node step logs, so a node can report `success`
+while a downstream step silently failed (you see all-green but empty output).
+The robust pattern: **have each node persist its own full result JSON into an
+output store** (e.g. `diag/<node>.json`) — best-effort, never throwing, never
+changing the node's return value. Then read the diagnostics back with
+`zibby_store_peek` to see exactly what each node saw (staged files + sizes,
+stderr, the real error). This turns a silent all-green failure into a precise
+root cause.
+
 ---
 
 ## Pattern 3 — event-driven agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/skills",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Built-in skill definitions for the Zibby agent-workflow framework",
   "type": "module",
   "main": "dist/index.js",