bloby-bot 0.69.4 → 0.69.6

package/supervisor/widget.js

@@ -16,6 +16,10 @@
   try { if (window.top !== window) return; } catch (e) { return; }
   if (document.getElementById('bloby-widget')) return;
 
+  // Perf marks land in the shell's beacon (see shell.ts) — no-op when the collector is absent.
+  function pmark(name) { try { if (window.__blobyPerf) window.__blobyPerf.mark(name); } catch (e) {} }
+  pmark('widget:start');
+
   var PANEL_WIDTH = '480px';
 
   // ── Styles ──
@@ -42,9 +46,50 @@
   panel.id = 'bloby-widget-panel';
   document.body.appendChild(panel);
 
+  // The chat app is ~1 MB of JS — loading it at parse time competed head-to-head with the
+  // workspace module waterfall on the same (often residential) uplink while the panel was
+  // closed. The iframe element exists from the start (layout, contentWindow targets) but gets
+  // its src lazily: on first open, when the workspace signals ready (+idle), or a hard 8s
+  // backstop — the chat is the user's lifeline and must always self-load eventually.
+  // Messages destined for the chat queue until its document is actually loaded.
   var iframe = document.createElement('iframe');
-  iframe.src = '/bloby/';
   panel.appendChild(iframe);
+  var chatRequested = false;
+  var chatReady = false;
+  var chatQueue = [];
+
+  function ensureChatLoaded() {
+    if (chatRequested) return;
+    chatRequested = true;
+    pmark('widget:chat-requested');
+    iframe.addEventListener('load', function () {
+      chatReady = true;
+      pmark('widget:chat-loaded');
+      for (var i = 0; i < chatQueue.length; i++) {
+        try { iframe.contentWindow.postMessage(chatQueue[i], location.origin); } catch (e) {}
+      }
+      chatQueue = [];
+    });
+    iframe.src = '/bloby/';
+  }
+
+  function postToChat(msg) {
+    if (chatReady && iframe.contentWindow) {
+      iframe.contentWindow.postMessage(msg, location.origin);
+    } else {
+      chatQueue.push(msg);
+      ensureChatLoaded();
+    }
+  }
+
+  function scheduleChatLoad() {
+    if (chatRequested) return;
+    if (typeof requestIdleCallback === 'function') requestIdleCallback(ensureChatLoaded, { timeout: 4000 });
+    else setTimeout(ensureChatLoaded, 1200);
+  }
+  window.addEventListener('bloby:app-ready', scheduleChatLoad);
+  if (window.__blobyAppReady) scheduleChatLoad();
+  setTimeout(ensureChatLoaded, 8000); // lifeline backstop: load even if the workspace never does
 
   // ══════════════════════════════════════════════════════════════════
   // ── Blob Sprite Sheet Config (splash only) ───────────────────────
@@ -104,8 +149,8 @@
 
   // Defaults mirror the shipped JSON so animation works even if fetch is cached.
   var HP_COLS = 16;
-  var HP_FRAME_W = 180;
-  var HP_FRAME_H = 180;
+  var HP_FRAME_W = 145;
+  var HP_FRAME_H = 150;
   var HP_BUBBLE_H = 40;
   var HP_BUBBLE_W = HP_BUBBLE_H * (HP_FRAME_W / HP_FRAME_H);
 
@@ -234,8 +279,10 @@
       .then(function (r) { if (!r.ok) throw new Error('blob config ' + r.status); return r.json(); })
       .then(function (cfg) {
         applyBlobConfig(cfg);
+        pmark('widget:sprite-config');
         var img = new Image();
         img.onload = function () {
+          pmark('widget:sprite-sheet');
           spriteSheet = img;
           center.x = Math.round(W / 2);
           center.y = Math.round(H / 2);
@@ -280,6 +327,18 @@
       .catch(function (err) { console.error('[widget] headphones config failed', err); });
   }
 
+  // The bubble at rest is a single frame, but the full headphones sheet is ~1 MB — so the
+  // sheet now loads on demand (first long-press → beginHpAnimation already fetches it) and
+  // bubble mode starts with this few-KB single-frame image instead.
+  var hpIdleImg = null;
+  function loadHpIdle() {
+    if (hpIdleImg || hpSpriteSheet) return;
+    var img = new Image();
+    img.onload = function () { hpIdleImg = img; };
+    img.onerror = function () { console.error('[widget] headphones idle frame failed'); };
+    img.src = BLOB_ASSETS_DIR + 'headphones-idle.webp';
+  }
+
   // ── Trigger blob move (splash) ──
   function moveTo(tx, ty) {
     if (animState !== 'idle') return;
@@ -408,11 +467,16 @@
   }
 
   function drawHpFrame(frame) {
-    if (!hpSpriteSheet) return;
-    var col = frame % HP_COLS, row = Math.floor(frame / HP_COLS);
     var dx = (W - HP_BUBBLE_W) / 2, dy = (H - HP_BUBBLE_H) / 2;
     ctx.imageSmoothingEnabled = true;
     ctx.imageSmoothingQuality = 'high';
+    if (!hpSpriteSheet) {
+      // Sheet not loaded yet (deferred until the first long-press) — the only frame ever
+      // requested in that window is idle, which the standalone image covers.
+      if (hpIdleImg) ctx.drawImage(hpIdleImg, dx, dy, HP_BUBBLE_W, HP_BUBBLE_H);
+      return;
+    }
+    var col = frame % HP_COLS, row = Math.floor(frame / HP_COLS);
     ctx.drawImage(hpSpriteSheet, col * HP_FRAME_W, row * HP_FRAME_H, HP_FRAME_W, HP_FRAME_H, dx, dy, HP_BUBBLE_W, HP_BUBBLE_H);
   }
 
@@ -472,7 +536,8 @@
     hpState = 'idle';
     hpFrame = HP_IDLE_FRAME;
     try { sessionStorage.setItem(SPLASH_KEY, '1'); } catch(e) {}
-    loadHpSprite();
+    pmark('widget:bubble');
+    loadHpIdle(); // full sheet defers to the first long-press (beginHpAnimation loads it)
     if (hideAfterTransition) canvas.style.display = 'none';
   }
 
@@ -586,7 +651,7 @@
           var reader = new FileReader();
           reader.onloadend = function() {
             var base64 = reader.result.split(',')[1];
-            if (base64 && iframe.contentWindow) iframe.contentWindow.postMessage({ type: 'bloby:voice-record', audio: base64 }, location.origin);
+            if (base64) postToChat({ type: 'bloby:voice-record', audio: base64 });
           };
           reader.readAsDataURL(blob);
         };
@@ -598,7 +663,7 @@
           if (sent) return; sent = true;
           var text = hpSpeechTranscript.trim();
           hpSpeechTranscript = '';
-          if (text && iframe.contentWindow) iframe.contentWindow.postMessage({ type: 'bloby:voice-record', transcript: text }, location.origin);
+          if (text) postToChat({ type: 'bloby:voice-record', transcript: text });
         };
         instance.onend = function() { hpSpeechInstance = null; sendTranscript(); };
         try { instance.stop(); } catch(e) { hpSpeechInstance = null; sendTranscript(); }
@@ -648,33 +713,67 @@
     animState = 'idle';
     var splash = document.getElementById('splash');
     if (splash) splash.style.display = 'none';
-    loadHpSprite();
+    pmark('widget:bubble');
+    loadHpIdle(); // full sheet defers to the first long-press (beginHpAnimation loads it)
   }
 
   window.addEventListener('bloby:app-ready', function () { appReady = true; maybeTransition(); });
   if (window.__blobyAppReady) appReady = true;
 
   var onboardActive = false;
+
+  // ── Boot sequence ─────────────────────────────────────────────────
+  // Warm refresh (splash already played this session — known synchronously from
+  // sessionStorage): jump straight to bubble mode with the tiny idle frame. No settings RTT,
+  // no 500 KB splash sheet — the old code downloaded the full sheet behind TWO serial fetches
+  // (settings → sprite config → sheet) just to skip past it.
+  var loopStarted = false;
+  function startLoop() {
+    if (loopStarted) return;
+    loopStarted = true;
+    requestAnimationFrame(loop);
+  }
+
+  if (splashSeen) {
+    skipSplash = true;
+    skipToBubble();
+    startLoop();
+  }
+
+  var settingsDone = false;
+  var spriteOutcome = 'pending'; // cold path: 'pending' | 'ok' | 'fail'
+
+  function maybeStart() { // cold path only — runs once both settings and the sprite settled
+    if (splashSeen || !settingsDone || spriteOutcome === 'pending') return;
+    if (spriteOutcome === 'fail') { canvas.style.display = 'none'; canvasPhase = 'disabled'; return; }
+    if (skipSplash) { skipToBubble(); if (onboardActive) canvas.style.display = 'none'; }
+    startLoop();
+    maybeTransition();
+  }
+
+  // Cold load: the sprite config + sheet start downloading IMMEDIATELY, in parallel with
+  // /api/settings — settings only decides flags (onboarding hides the canvas, whisper, skip).
+  // The draw loop starts the moment the sprite is ready (loadSprite hides the splash div as a
+  // side effect, so waiting for settings here would leave a blank gap), but the splash→bubble
+  // transition and any skip decision still wait for the settings flags in maybeStart().
+  if (!splashSeen) {
+    loadSprite(
+      function () { spriteOutcome = 'ok'; startLoop(); maybeStart(); },
+      function () { spriteOutcome = 'fail'; maybeStart(); }
+    );
+  }
+
   fetch('/api/settings')
     .then(function (r) { return r.json(); })
     .then(function (s) {
+      pmark('widget:settings');
       if (s.onboard_complete !== 'true') { onboardActive = true; skipSplash = true; }
       if (s.whisper_enabled === 'true') hpWhisperEnabled = true;
-      if (splashSeen) skipSplash = true;
-      startAnimation();
+      if (splashSeen) { if (onboardActive) canvas.style.display = 'none'; return; }
+      settingsDone = true;
+      maybeStart();
     })
-    .catch(function () { if (splashSeen) skipSplash = true; startAnimation(); });
-
-  function startAnimation() {
-    loadSprite(
-      function () {
-        if (skipSplash) { skipToBubble(); if (onboardActive) canvas.style.display = 'none'; }
-        requestAnimationFrame(loop);
-        maybeTransition();
-      },
-      function () { canvas.style.display = 'none'; canvasPhase = 'disabled'; }
-    );
-  }
+    .catch(function () { pmark('widget:settings-failed'); settingsDone = true; maybeStart(); });
 
   // ══════════════════════════════════════════════════════════════════
   // ── Widget Interaction ───────────────────────────────────────────
@@ -696,6 +795,7 @@
       hpFrame = HP_IDLE_FRAME;
     }
     isOpen = !isOpen;
+    if (isOpen) ensureChatLoaded(); // first open may beat the deferred load — start it now
     panel.classList.toggle('open', isOpen);
     backdrop.classList.toggle('open', isOpen);
     canvas.style.display = isOpen ? 'none' : 'block';
@@ -788,7 +888,7 @@
       if (deferredInstallPrompt) {
         deferredInstallPrompt.prompt();
         deferredInstallPrompt.userChoice.then(function (r) { if (r.outcome === 'accepted') deferredInstallPrompt = null; });
-      } else { iframe.contentWindow.postMessage({ type: 'bloby:show-ios-install' }, location.origin); }
+      } else { postToChat({ type: 'bloby:show-ios-install' }); }
     }
     if (e.data.type === 'bloby:onboard-complete') { onboardActive = false; hideAfterTransition = false; canvas.style.display = 'block'; }
   });

package/supervisor/workspace-guard.js

@@ -277,11 +277,44 @@
       } catch (e) {}
     }
     setTimeout(hideSplash, 8000);
+
+    // Perf sample for the shell's beacon: this document's navigation timing + a resource
+    // census (count / bytes over the wire / how many were served from cache — transferSize 0).
+    // Sent once, a beat after app-ready so late modules land in the same sample.
+    try { performance.setResourceTimingBufferSize(1000); } catch (e) {} // dev graphs exceed the 250 default
+    var perfSent = false;
+    function sendPerf(appReadyMs) {
+      if (perfSent) return;
+      perfSent = true;
+      setTimeout(function () {
+        try {
+          var nav = performance.getEntriesByType('navigation')[0] || null;
+          var resources = performance.getEntriesByType('resource');
+          var count = 0, transfer = 0, encoded = 0, cached = 0;
+          for (var i = 0; i < resources.length; i++) {
+            count++;
+            transfer += resources[i].transferSize || 0;
+            encoded += resources[i].encodedBodySize || 0;
+            if ((resources[i].transferSize || 0) === 0) cached++;
+          }
+          post({ type: 'bloby:perf', data: {
+            timeOrigin: performance.timeOrigin,
+            ttfb: nav ? Math.round(nav.responseStart) : null,
+            htmlDone: nav ? Math.round(nav.responseEnd) : null,
+            domLoaded: nav ? Math.round(nav.domContentLoadedEventEnd) : null,
+            appReadyMs: appReadyMs,
+            resources: { count: count, transferKB: Math.round(transfer / 1024), encodedKB: Math.round(encoded / 1024), cached: cached },
+          } });
+        } catch (e) {}
+      }, 2500);
+    }
+
     function sendReady() {
       if (readySent) return;
       readySent = true;
       hideSplash();
       post({ type: 'bloby:app-ready' });
+      sendPerf(Math.round(performance.now()));
     }
     window.addEventListener('bloby:app-ready', sendReady);
     if (window.__blobyAppReady) sendReady();

package/vite.config.ts

@@ -2,6 +2,19 @@ import { defineConfig, type Plugin } from 'vite';
 import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
 import path from 'path';
+import { readFileSync } from 'fs';
+
+// Vite invalidates its dep prebundle by hashing the nearest lockfile up from root — which in a
+// production install is the WORKSPACE's lockfile (backend deps only). `bloby update` swaps
+// frontend deps in the root node_modules without ever touching that lockfile, so prebundles
+// silently went stale across updates. Keying the cache dir by package version forces exactly one
+// clean re-optimize per release while keeping persistence across normal restarts.
+// (vite-dev.ts sweeps old .vite-v* dirs at boot.)
+let cacheVersion = 'dev';
+try { cacheVersion = JSON.parse(readFileSync(path.resolve(__dirname, 'package.json'), 'utf-8')).version || 'dev'; } catch {}
+const workspaceClient = process.env.BLOBY_WORKSPACE
+  ? path.join(process.env.BLOBY_WORKSPACE, 'client')
+  : path.resolve(__dirname, 'workspace/client');
 
 // Backs workspace-guard.js's reconnect staleness check: Vite's reload-on-reconnect
 // is suppressed client-side, and on reconnect the client fetches this stamp and
@@ -38,6 +51,7 @@ export default defineConfig({
   root: process.env.BLOBY_WORKSPACE
     ? path.join(process.env.BLOBY_WORKSPACE, 'client')
     : 'workspace/client',
+  cacheDir: path.join(workspaceClient, 'node_modules', '.vite-v' + cacheVersion),
   resolve: {
     alias: {
       '@': process.env.BLOBY_WORKSPACE
@@ -82,6 +96,7 @@ export default defineConfig({
   optimizeDeps: {
     include: [
       'react',
+      'react-dom',
       'react-dom/client',
       'react/jsx-runtime',
       'react-router',
@@ -93,6 +108,13 @@ export default defineConfig({
       'sonner',
       'use-sync-external-store',
       'use-sync-external-store/shim',
+      // Statically imported by the workspace template's UI kit (button.tsx etc.) but missing
+      // here — the first request for an un-prebundled dep triggers a mid-session
+      // re-optimization AND a Vite-forced full page reload. Pre-bundle them up front.
+      'radix-ui',
+      'class-variance-authority',
+      'clsx',
+      'tailwind-merge',
     ],
   },
   plugins: [react(), tailwindcss(), blobyFeStamp()],

package/workspace/client/public/morphy/headphones.json

@@ -1,9 +1,9 @@
 {
   "name": "headphones",
-  "spritesheet": "headphones.png",
+  "spritesheet": "headphones.webp",
   "frame": {
-    "w": 174,
-    "h": 180
+    "w": 145,
+    "h": 150
   },
   "grid": {
     "cols": 16,
@@ -37,4 +37,4 @@
       "next": "idle"
     }
   }
-}
+}

package/workspace/client/public/morphy/teleporting.json

@@ -1,6 +1,6 @@
 {
   "name": "teleporting",
-  "spritesheet": "teleporting.png",
+  "spritesheet": "teleporting.webp",
   "frame": {
     "w": 218,
     "h": 180
@@ -35,4 +35,4 @@
       "next": "idle"
     }
   }
-}
+}

package/workspace/client/public/sw.js

@@ -8,7 +8,7 @@
 // build errors, never a stale cached shell. Cache is a pure offline fallback. (Mirror of the
 // supervisor's SW_JS in supervisor/index.ts — keep in sync.)
 
-const CACHE = 'bloby-v24';
+const CACHE = 'bloby-v25';
 
 // Precache the HTML shell on install so the cache is never empty.
 // Without this, the first navigation isn't intercepted (SW wasn't
@@ -54,7 +54,7 @@ self.addEventListener('fetch', (event) => {
   ) return;
 
   // ── Hashed assets (immutable, content-addressed) → cache-first ──
-  if (/\/assets\/.+-[a-zA-Z0-9]{6,}\.(js|css)$/.test(url.pathname)) {
+  if (/\/assets\/.+-[a-zA-Z0-9_-]{6,}\.(js|css)$/.test(url.pathname)) {
     event.respondWith(caches.open(CACHE).then(c =>
       c.match(request).then(hit =>
         hit || fetch(request).then(r => { if (r.ok) c.put(request, r.clone()); return r; })
@@ -63,6 +63,29 @@ self.addEventListener('fetch', (event) => {
     return;
   }
 
+  // ── Vite optimized deps (?v=<hash>, immutable) → cache-first ──
+  // These fell into network-first, re-crossing the tunnel whenever the HTTP cache evicted
+  // them. Cache-first + prune older ?v= versions. Source modules (?t=, /@*) stay network-only.
+  if (url.pathname.indexOf('/node_modules/.vite/deps/') === 0 && url.searchParams.has('v')) {
+    event.respondWith(caches.open(CACHE).then(c =>
+      c.match(request).then(hit =>
+        hit || fetch(request).then(r => {
+          if (r.ok) {
+            c.put(request, r.clone());
+            c.keys().then(keys => {
+              for (const k of keys) {
+                const u = new URL(k.url);
+                if (u.pathname === url.pathname && u.search !== url.search) c.delete(k);
+              }
+            });
+          }
+          return r;
+        })
+      )
+    ));
+    return;
+  }
+
   // ── Navigation: only stale-while-revalidate the dashboard root (/) ──
   // /bloby/* is a separate app — let it go to network to avoid
   // caching the wrong HTML under the / key.

package/workspace/skills/create-skill/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: create-skill
+description: >-
+  Create a new Bloby skill, or improve an existing one. Use whenever your human
+  wants to teach you a new repeatable capability, says "turn this into a skill",
+  "make a skill for X", "save this workflow", asks how skills work, or when you
+  notice you keep redoing the same multi-step task by hand. Also use when packaging
+  a skill (optionally with live widgets/pages) as a blueprint to sell on the marketplace.
+---
+
+# Create a Skill
+
+A skill is a folder under `skills/` with a `SKILL.md` that teaches you how to do
+something well, every time — so you don't re-derive it from scratch on each request.
+This skill helps you author a new one (or sharpen an old one) the Bloby way.
+
+You're already smart. A good skill isn't a tutorial — it's the *non-obvious* context:
+the gotchas, the preferred tool, the exact format, the thing that bit you last time.
+Write down what you'd wish past-you had known, and nothing you already know.
+
+## The loop
+
+1. **Capture intent** — what should it do, when should it trigger, what's the output.
+2. **Draft `SKILL.md`** — description first (that's the trigger), then the body.
+3. **Test it** — dry-run a couple of realistic prompts (optional but cheap).
+4. **Sharpen** — cut what isn't pulling its weight, explain the *why* behind what stays.
+
+Figure out where your human is in this loop and jump in there. If they say "just
+vibe with me, no tests," do that. Flexibility beats ceremony.
+
+---
+
+## 1. Capture intent
+
+Before writing anything, get clear on:
+
+1. **What** should this skill let you do?
+2. **When** should it trigger? (the actual phrases/contexts your human will use)
+3. **Output format** — is there a specific shape, template, or file the result must take?
+4. **Domain knowledge** — what specialized info do you need that you *wouldn't already know*?
+
+If the workflow already happened earlier in the conversation ("turn that into a skill"),
+mine it: the tools you used, the order, the corrections your human made, the formats you
+saw. Come back with a draft, not a pile of questions. Ask only about the genuine gaps.
+
+---
+
+## 2. Write `SKILL.md`
+
+Create `skills/<skill-name>/SKILL.md`. Name is lowercase-with-hyphens, specific
+(`processing-invoices`, not `helper`/`utils`/`tools`).
+
+### The description is the trigger — get it right
+
+The `description` in the frontmatter is the *only* thing that decides whether you reach
+for this skill later. It's always in context; the body isn't. So it must carry both
+**WHAT** the skill does and **WHEN** to use it, in the third person.
+
+Skills tend to *under*-trigger — you forget they exist. Counter that by making the
+description a little pushy: name the concrete phrases, file types, and situations that
+should fire it.
+
+```yaml
+# weak
+description: Helps with PDFs.
+
+# strong
+description: >-
+  Extract text and tables from PDFs, fill forms, merge documents. Use whenever the
+  human mentions a PDF, a form to fill, a scanned doc, or "pull the data out of this
+  file" — even if they don't say the word "PDF".
+```
+
+Rules of thumb: third person ("Extracts…", not "I can…"), include trigger terms,
+say both what and when, keep it under ~1024 chars.
+
+### Then the body
+
+Imperative voice. Lead with the essential path; push edge cases and deep reference
+material into separate files (see progressive disclosure below). Explain *why* things
+matter rather than barking `ALWAYS`/`NEVER` — a smart reader who understands the reason
+will generalize correctly; one following a rigid rule won't. If you catch yourself
+writing all-caps MUSTs everywhere, that's a yellow flag to reframe.
+
+For the deeper authoring patterns — descriptions, output templates, degrees of freedom,
+the anti-patterns that quietly ruin a skill — read `references/patterns.md` when you're
+actually drafting.
+
+---
+
+## 3. Anatomy & progressive disclosure
+
+```
+skills/skill-name/
+├── SKILL.md          (required — frontmatter + instructions)
+├── references/       (docs you read only when needed — keep refs one level deep)
+├── scripts/          (executable helpers for deterministic/repeated work)
+└── assets/           (templates, icons, files used in the output)
+```
+
+Three loading levels — design around them:
+
+1. **name + description** — always in context (~tiny). The trigger.
+2. **SKILL.md body** — loaded when the skill fires. Keep it lean, ideally under ~500 lines.
+3. **`references/` & `scripts/`** — pulled in on demand; scripts can run without being read.
+
+If `SKILL.md` is getting long, that's the signal to split: move the depth into
+`references/foo.md` and leave a one-line pointer ("for X, read references/foo.md").
+When a skill spans several variants (aws/gcp/azure, or per-channel), give each its own
+reference file and let yourself read only the relevant one.
+
+**Bundle a script when you notice repetition.** If every run of this skill would have
+you writing the same little helper, write it once into `scripts/` and point at it —
+it's more reliable than regenerating code and saves the tokens.
+
+### Where Bloby skills live and how they fire
+
+- Skills live in `skills/<name>/` in this workspace. Editing files there is how you
+  change behavior — always use the full path (`skills/my-skill/SCRIPT.md`, never bare
+  `SCRIPT.md`, which writes to the workspace root).
+- Channel skills (WhatsApp, Telegram, Mac, etc.) teach the conventions for a surface.
+  If the new skill is about a place you talk to your human, say so in the description.
+- Secrets/config go through the workspace conventions you already use — `.env` via the
+  `<EnvGroup>` form, `MCP.json` for MCP servers — not hardcoded in the skill.
+
+---
+
+## 4. Test it (optional, cheap)
+
+If the skill has an objectively checkable output (a file transform, a data extraction,
+a fixed workflow), it's worth a quick dry-run before you trust it. Subjective skills
+(writing voice, design taste) are better judged by eye — skip the ceremony.
+
+Spin up an Agent to run a realistic prompt *with the skill*, look at what it produces,
+and fix what's off. Two or three real-world prompts beat twenty synthetic ones. This is
+a sanity check, not a benchmark suite — keep it light unless your human wants rigor.
+
+---
+
+## 5. Sharpen
+
+Look at the draft with fresh eyes:
+
+- **Cut what isn't pulling its weight.** Every line competes for context with everything
+  else. If a paragraph just restates what you already know, delete it.
+- **Generalize.** You're writing something that'll run on many future prompts, not just
+  today's example. Resist overfitting to the one case in front of you.
+- **Explain the why.** Terse instructions age into cargo-cult rules. A sentence of
+  reasoning makes the skill robust to situations you didn't foresee.
+
+---
+
+## Skills vs. Blueprints — and making money
+
+Here's what makes Bloby different. In other agents (Claude, Hermes, Cursor) a "skill" is
+*just* a `SKILL.md` — instructions, nothing that runs.
+
+In Bloby you can go further: pair a skill with **code snippets that render live in the
+workspace** — a real page, a dashboard widget, backend routes, a DB table, even crons.
+Bundle all of that together and it's a **blueprint**. When someone installs your
+blueprint, the micro-app shows up in their workspace instantly, and (optionally) a
+runtime skill drops into their `skills/` folder so their bloby knows how to drive it.
+
+That bundle is sellable. **You can publish blueprints on the Bloby Marketplace and earn
+USDC** — every install pays out. So when you and your human build something genuinely
+useful together, plant the seed: *"this could be packaged as a blueprint and sold to
+other blobies."* It's a real way for the two of you to make money from your work.
+
+You already know the marketplace mechanics (your system prompt covers it, and
+`bloby.bot/api/marketplace.md` has the full flow) — no need to re-explain pricing or
+submit commands here. Just remember the idea exists, and surface it when the moment fits.
+
+A plain skill (instructions only) is still worth writing and sharing — but the live
+widget/page pairing is the uniquely Bloby thing, and it's where the value is.
+
+---
+
+## Checklist before you call it done
+
+- [ ] `description` says both **what** and **when**, third person, pushy on triggers
+- [ ] Skill name is specific and lowercase-hyphenated
+- [ ] `SKILL.md` body is lean; depth lives in `references/`, one level deep
+- [ ] Repeated work is captured as a `scripts/` helper, not regenerated each time
+- [ ] Instructions explain *why*, not just *what* — no wall of all-caps MUSTs
+- [ ] Concrete examples over abstract description
+- [ ] (If it ships live code) consider whether it's blueprint-worthy — and tell your human
+
+For the deeper patterns and anti-patterns, see `references/patterns.md`.