@polderlabs/bizar 4.4.9 → 4.4.11

package/bizar-dash/src/server/mods-loader.mjs

@@ -178,6 +178,138 @@ export const modsLoader = {
     mkdirSync(MODS_DIR, { recursive: true });
   },
 
+  /**
+   * v4.4.11 — Validate an installed mod without mounting it.
+   *
+   * Runs after a copy (in `installFromPath` + `installFromRegistry`) and
+   * before the install is reported as successful. Returns a structured
+   * `{ ok, errors, warnings }` so callers (the API + the CLI + the
+   * provisioner) can surface failures consistently.
+   *
+   * Checks performed:
+   *   1. `mod.json` is valid JSON with required fields (id, name, version).
+   *   2. `entry.route` (if declared) is a file that exists and is readable.
+   *      We pre-parse it with `node --check` to catch syntax errors.
+   *   3. Permissions declared in mod.json are validated against the
+   *      allowed list (delegates to mod-security.mjs).
+   *   4. If `entry.validate` is declared, we dynamic-import that file
+   *      and call its `default` or named `validate` export. The hook can
+   *      throw to fail the install.
+   *
+   * Never throws — always returns a structured result.
+   */
+  async validateModInstallation(id) {
+    const errors = [];
+    const warnings = [];
+    const dir = join(MODS_DIR, id);
+    if (!existsSync(dir)) {
+      return { ok: false, errors: [`mod directory not found: ${dir}`], warnings };
+    }
+
+    // 1. mod.json valid + required fields
+    const manifest = safeReadJSON(join(dir, 'mod.json'), null);
+    if (!manifest || typeof manifest !== 'object') {
+      return {
+        ok: false,
+        errors: ['mod.json is missing or invalid JSON'],
+        warnings,
+      };
+    }
+    for (const field of ['id', 'name', 'version']) {
+      if (!manifest[field] || typeof manifest[field] !== 'string') {
+        errors.push(`mod.json is missing required field "${field}"`);
+      }
+    }
+    if (manifest.id && manifest.id !== id) {
+      errors.push(`mod.json "id" field ("${manifest.id}") does not match the directory name ("${id}")`);
+    }
+
+    // 2. entry.route exists + parses
+    const entry = manifest.entry || {};
+    if (entry.route) {
+      const routePath = join(dir, entry.route);
+      if (!existsSync(routePath)) {
+        errors.push(`entry.route "${entry.route}" does not exist at ${routePath}`);
+      } else {
+        // Pre-parse the route.mjs with `node --check` to catch syntax
+        // errors without executing it. Skipped if node is not available.
+        try {
+          const { spawnSync } = await import('node:child_process');
+          const probe = spawnSync(process.execPath, ['--check', routePath], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 5000,
+          });
+          if (probe.status !== 0) {
+            // Extract the first error line from the syntax checker
+            // output. `node --check` prints something like:
+            //   /path/to/route.mjs:5
+            //   syntax is wrong here
+            //   ^^^
+            //   SyntaxError: message
+            // We want the last "SyntaxError:" line.
+            const stderr = (probe.stderr || '').toString();
+            const lines = stderr.split('\n').map((l) => l.trim()).filter(Boolean);
+            const errLine = lines.reverse().find((l) => l.toLowerCase().includes('syntaxerror')) || lines[0] || 'unknown';
+            errors.push(`entry.route "${entry.route}" has a syntax error: ${errLine}`);
+          }
+        } catch {
+          // node --check unavailable — skip (not fatal)
+        }
+      }
+    }
+
+    // 3. Permissions valid
+    if (Array.isArray(manifest.permissions)) {
+      const { invalid } = parsePermissions(manifest.permissions);
+      for (const p of invalid) {
+        warnings.push(`mod declares unknown permission: ${p}`);
+      }
+    }
+
+    // 4. Optional entry.validate hook
+    if (entry.validate) {
+      const validatePath = join(dir, entry.validate);
+      if (!existsSync(validatePath)) {
+        errors.push(`entry.validate "${entry.validate}" does not exist at ${validatePath}`);
+      } else {
+        try {
+          // Dynamic import — the validate hook is opt-in. The mod may
+          // export `default` (function) or named export `validate`.
+          const mod = await import(/* @vite-ignore */ `file://${validatePath}`);
+          const fn = mod.default || mod.validate;
+          if (typeof fn !== 'function') {
+            warnings.push(
+              `entry.validate "${entry.validate}" does not export a function (got ${typeof fn})`,
+            );
+          } else {
+            // Run the validate hook with a 5s timeout. The hook is
+            // trusted (it's part of the mod) but we don't want a bad
+            // hook to hang the install.
+            const result = await Promise.race([
+              Promise.resolve()
+                .then(() => fn({ mod: manifest, dir }))
+                .catch((err) => ({ ok: false, error: err.message })),
+              new Promise((resolve) =>
+                setTimeout(() => resolve({ ok: false, error: 'validate hook timed out after 5s' }), 5000),
+              ),
+            ]);
+            if (result && result.ok === false) {
+              errors.push(`mod validate hook failed: ${result.error || 'unknown'}`);
+            }
+          }
+        } catch (err) {
+          errors.push(`failed to load entry.validate "${entry.validate}": ${err.message}`);
+        }
+      }
+    }
+
+    return {
+      ok: errors.length === 0,
+      errors,
+      warnings,
+    };
+  },
+
   /** List all installed mods. v3.3.1 — never throws. */
   list() {
     try {
@@ -211,7 +343,7 @@ export const modsLoader = {
    * Install a mod from a local path. Copies the folder into
    * `~/.config/bizar/mods/<id>/`. The id is the source folder's basename.
    */
-  installFromPath(sourcePath) {
+  async installFromPath(sourcePath) {
     if (!existsSync(sourcePath)) {
       throw new Error(`source path does not exist: ${sourcePath}`);
     }
@@ -243,6 +375,24 @@ export const modsLoader = {
     // (agents/, commands/, skills/). This makes the mod's rules binding
     // on every agent at session start.
     installModInstructions(id, target);
+    // v4.4.11 — Smoke-test the mod before reporting success. We
+    // uninstall on failure so a broken mod doesn't leave a half-
+    // copied directory the user has to clean up manually.
+    const validation = await this.validateModInstallation(id);
+    if (!validation.ok) {
+      uninstallModInstructions(id);
+      rmSync(target, { recursive: true, force: true });
+      const err = new Error(
+        `mod "${id}" failed post-install validation: ${validation.errors.join('; ')}`,
+      );
+      err.validation = validation;
+      throw err;
+    }
+    if (validation.warnings.length > 0) {
+      console.warn(
+        `[mods-loader] mod "${id}" installed with warnings: ${validation.warnings.join('; ')}`,
+      );
+    }
     return loadMod({ id, dir: target });
   },
 
@@ -494,6 +644,24 @@ export const modsLoader = {
     // v3.20 — install mod instructions into the user's opencode config
     // (agents/, commands/, skills/). Triggered on registry install too.
     installModInstructions(id, target);
+    // v4.4.11 — Smoke-test the mod before reporting success. We
+    // uninstall on failure so a broken mod doesn't leave a half-
+    // copied directory the user has to clean up manually.
+    const validation = await this.validateModInstallation(id);
+    if (!validation.ok) {
+      uninstallModInstructions(id);
+      rmSync(target, { recursive: true, force: true });
+      const err = new Error(
+        `mod "${id}" failed post-install validation: ${validation.errors.join('; ')}`,
+      );
+      err.validation = validation;
+      throw err;
+    }
+    if (validation.warnings.length > 0) {
+      console.warn(
+        `[mods-loader] mod "${id}" installed with warnings: ${validation.warnings.join('; ')}`,
+      );
+    }
     return loadMod({ id, dir: target });
   },
 

package/cli/bin.mjs

@@ -156,10 +156,11 @@ function showInstallHelp() {
   bizar install — Run the unified BizarHarness installer
 
   Usage:
-    bizar install                 Install (or refresh) every component
-    bizar install --dry-run       Print what would happen, change nothing
-    bizar install --force         Overwrite existing files
-    bizar install --help          Show this help
+    bizar install                       Install (or refresh) every component
+    bizar install --dry-run             Print what would happen, change nothing
+    bizar install --force               Overwrite existing files
+    bizar install --with-mods a,b,c     Opt-in: install specific mods as part of the run
+    bizar install --help                Show this help
 
   Description:
     v4.4.7+ — unified installer. Same code path as 'bizar update'; the
@@ -194,6 +195,7 @@ function showUpdateHelp() {
     bizar update --dry-run             Print what would happen, change nothing
     bizar update --force               Override .bizar/PRE_PUSH_NOTES.md blockers
     bizar update --yes                 Same as --force, but named for one-line scripts
+    bizar update --with-mods a,b,c     Opt-in: install specific mods as part of the run
     bizar update --help                Show this help
 
   Components updated:
@@ -580,6 +582,22 @@ function parseFlag(name) {
   return args[idx + 1] || null;
 }
 
+/**
+ * v4.4.11 — Parse `--with-mods <csv>` from the given subargs slice.
+ * Returns `null` if the flag isn't present (the provisioner's
+ * "don't touch mods" default), or a string[] of mod ids if it is.
+ */
+function parseWithModsFlag(subargs) {
+  const idx = subargs.indexOf('--with-mods');
+  if (idx === -1) return null;
+  const raw = subargs[idx + 1];
+  if (!raw || raw.startsWith('--')) return [];
+  return raw
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
 async function readAutoLaunchWeb() {
   try {
     const fs = await import('node:fs');
@@ -677,7 +695,19 @@ async function main() {
     else await runTestGate();
   } else if (args[0] === 'update') {
     if (isHelpRequest) showUpdateHelp();
-    else await runUpdate(args.slice(1));
+    else {
+      // v4.4.11 — Same --with-mods opt-in for update.
+      const withMods = parseWithModsFlag(args.slice(1));
+      // runUpdate expects (subargs: string[], opts?: object). Splice
+      // --with-mods <csv> out of subargs since the provisioner now
+      // takes it via opts, not as a positional arg.
+      const subargs = args.slice(1).filter((a, i, arr) => {
+        if (a === '--with-mods') return false;
+        if (arr[i - 1] === '--with-mods') return false;
+        return true;
+      });
+      await runUpdate(subargs, { withMods });
+    }
   } else if (args[0] === 'dev-link') {
     if (isHelpRequest) showDevLinkHelp();
     else {
@@ -741,7 +771,10 @@ async function main() {
   } else if (args[0] === 'install') {
     if (isHelpRequest) showInstallHelp();
     else {
-      await runInstaller();
+      // v4.4.11 — Parse --with-mods <csv> to opt into mod installs
+      // during the run. Default: mods are NEVER touched.
+      const withMods = parseWithModsFlag(args.slice(1));
+      await runInstaller({ withMods });
       // v4.4.3 — After install, repair any stale bin symlinks so the
       // user picks up the new code (the installer itself may have
       // been running from a stale install path).

package/cli/provision.mjs

@@ -38,7 +38,7 @@
 
 import chalk from 'chalk';
 import { execSync, spawn, spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, rmSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -272,6 +272,13 @@ export function detectState({ cwd = process.cwd() } = {}) {
   // ── Git checkout? ─────────────────────────────────────────────────
   const gitRepo = existsSync(join(REPO_ROOT, '.git'));
 
+  // ── Installed mods ─────────────────────────────────────────────────
+  // v4.4.11 — `bizar install` and `bizar update` never install or
+  // upgrade mods. The list below is informational only. Use
+  // `bizar mod install <id>` to add a mod explicitly.
+  const MODS_DIR = join(BIZAR_HOME, 'mods');
+  const installedMods = listInstalledMods(MODS_DIR);
+
   return {
     pkgRoot,
     pkgVersion,
@@ -302,9 +309,52 @@ export function detectState({ cwd = process.cwd() } = {}) {
     opencodeCli,
     headsUpState,
     gitRepo,
+    installedMods,
   };
 }
 
+/**
+ * v4.4.11 — Lightweight read-only scan of `~/.config/bizar/mods/`.
+ * Returns one entry per mod folder with the id + enabled flag parsed
+ * from mod.json. Never throws; mods with a missing or invalid mod.json
+ * are reported as `{id, error}` so the provisioner can surface them.
+ */
+function listInstalledMods(modsDir) {
+  const out = [];
+  if (!existsSync(modsDir)) return out;
+  let entries;
+  try {
+    entries = readdirSync(modsDir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = join(modsDir, entry.name);
+    const manifestPath = join(dir, 'mod.json');
+    if (!existsSync(manifestPath)) {
+      out.push({ id: entry.name, error: 'missing mod.json' });
+      continue;
+    }
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch {
+      out.push({ id: entry.name, error: 'invalid mod.json' });
+      continue;
+    }
+    out.push({
+      id: manifest.id || entry.name,
+      name: manifest.name || entry.name,
+      version: manifest.version || '?',
+      enabled: manifest.enabled !== false,
+      installedAt: manifest.installedAt || null,
+      path: dir,
+    });
+  }
+  return out;
+}
+
 /**
  * Lightweight CommonJS-ish require for ESM contexts. Used to detect the
  * service-controller + heads-up modules without paying the static-import
@@ -681,6 +731,125 @@ export async function runDoctor({ silent = false } = {}) {
   }
 }
 
+/**
+ * v4.4.11 — The mods step. By default, NEVER install or upgrade mods
+ * during `bizar install` or `bizar update`. The step just reports the
+ * current mod list so the user can see what's installed.
+ *
+ * To install a mod as part of the run, the user must opt in by:
+ *   - passing `--with-mods <id1,id2>` to `bizar install` / `bizar update`
+ *   - or setting the env var `BIZAR_MODS_AUTO_INSTALL=allow`
+ *
+ * When opted in, we shell to the running dashboard's `/api/mods`
+ * endpoint (which already validates the mod) — we don't duplicate the
+ * install logic here.
+ */
+export async function runModsStep({ mode, dryRun, force, withMods, state }) {
+  // List the current mods (from the state we already detected).
+  const installed = state?.installedMods ?? [];
+  if (installed.length === 0) {
+    console.log(chalk.dim('  Mods: 0 installed.'));
+    return { ok: true, message: 'no mods installed', touched: false };
+  }
+
+  const enabled = installed.filter((m) => m.enabled).length;
+  const disabled = installed.length - enabled;
+  const summary = `${installed.length} installed (${enabled} enabled${disabled ? `, ${disabled} disabled` : ''})`;
+
+  // Resolve which mods the user asked us to install. The CLI parses
+  // `--with-mods a,b,c` into a string array; the provisioner accepts
+  // the same. We also accept a single env var as a comma-separated list.
+  const envList = (process.env.BIZAR_MODS_AUTO_INSTALL || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const wantedMods = Array.isArray(withMods) && withMods.length > 0
+    ? withMods
+    : (process.env.BIZAR_MODS_AUTO_INSTALL === 'allow' ? [] : envList);
+
+  // Default behavior: no install. Just print the list.
+  if (!wantedMods || wantedMods.length === 0) {
+    console.log(chalk.dim(`  Mods: ${summary}. Not modified (use \`bizar mod install <id>\` to add one).`));
+    // Surface mods with errors so the user knows they need attention.
+    const broken = installed.filter((m) => m.error);
+    for (const m of broken) {
+      console.log(chalk.yellow(`    ⚠ ${m.id}: ${m.error}`));
+    }
+    return { ok: true, message: `${summary}, not modified`, touched: false };
+  }
+
+  // Opt-in install path. Talk to the dashboard over HTTP — the
+  // dashboard's `POST /api/mods` endpoint already does the actual
+  // install + validation. If the dashboard isn't reachable, the
+  // install fails loudly.
+  console.log(chalk.cyan(`  Installing ${wantedMods.length} mod(s) via dashboard API: ${wantedMods.join(', ')}`));
+  const errors = [];
+  for (const id of wantedMods) {
+    try {
+      const result = await installModViaDashboard(id, { dryRun });
+      if (result.ok) {
+        console.log(chalk.green(`    ✓ ${id}: ${result.message}`));
+      } else {
+        console.log(chalk.red(`    ✗ ${id}: ${result.message}`));
+        errors.push(`${id}: ${result.message}`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.log(chalk.red(`    ✗ ${id}: ${msg}`));
+      errors.push(`${id}: ${msg}`);
+    }
+  }
+  if (errors.length > 0) {
+    return {
+      ok: false,
+      message: `mod install failed for ${errors.length} mod(s): ${errors.join('; ')}`,
+      touched: true,
+    };
+  }
+  return { ok: true, message: `${wantedMods.length} mod(s) installed`, touched: true };
+}
+
+/**
+ * v4.4.11 — POST to the dashboard's /api/mods endpoint to install a mod.
+ * We re-use the dashboard's own validation pipeline (mod-loader.mjs
+ * runs the same manifest + route.mjs + permissions checks) so we
+ * don't have to duplicate them here.
+ */
+async function installModViaDashboard(id, { dryRun }) {
+  if (dryRun) {
+    return { ok: true, message: '[dry-run] would install via dashboard' };
+  }
+  // Find the dashboard's port from BIZAR_HOME/dashboard.port.
+  const portFile = join(BIZAR_HOME, 'dashboard.port');
+  let port = 4321;
+  try {
+    if (existsSync(portFile)) {
+      const parsed = parseInt(readTextSafe(portFile, '4321').trim(), 10);
+      if (Number.isFinite(parsed) && parsed > 0) port = parsed;
+    }
+  } catch { /* ignore */ }
+  // We need an auth token. The dashboard's install endpoint is under
+  // /api/* which is auth-gated. Fetch the auth status + token via
+  // /api/auth/status (skipped from auth via the skipPaths list in
+  // server.mjs). If the dashboard has auth enabled, the user needs to
+  // supply a token via BIZAR_DASHBOARD_TOKEN.
+  const headers = { 'content-type': 'application/json' };
+  const token = process.env.BIZAR_DASHBOARD_TOKEN;
+  if (token) headers['authorization'] = `Basic ${Buffer.from(`opencode:${token}`).toString('base64')}`;
+  const url = `http://127.0.0.1:${port}/api/mods`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ id }),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    return { ok: false, message: `dashboard returned ${res.status}: ${text.slice(0, 200) || '(no body)'}` };
+  }
+  const data = await res.json().catch(() => ({}));
+  return { ok: true, message: data?.name ? `installed ${data.name}@${data.version}` : 'installed' };
+}
+
 // ─── Top-level orchestration ──────────────────────────────────────────────────
 
 /**
@@ -785,6 +954,7 @@ export async function runProvision(opts = {}) {
     skipSystemDeps = false,
     skipHeadsUps = false,
     yes = false,
+    withMods = null,  // string[] — opt-in mod install. Default null = don't touch mods.
   } = opts;
 
   const banner = mode === 'update'
@@ -897,7 +1067,17 @@ export async function runProvision(opts = {}) {
     stepResults.push({ label: 'dashboard-restart', ...r });
   }
 
-  // ── 11. Doctor health check ────────────────────────────────────────
+  // ── 11. Mods (opt-in only) ─────────────────────────────────────────
+  // v4.4.11 — `bizar install` and `bizar update` never install or
+  // upgrade mods by default. The provisioner reports the current mod
+  // list so the user can see what's installed, then exits the mod step
+  // without touching anything. To install a mod, pass
+  // `--with-mods <id1,id2>` or set `BIZAR_MODS_AUTO_INSTALL=allow`.
+  console.log('');
+  const modsStep = await runModsStep({ mode, dryRun, force, withMods, state });
+  stepResults.push({ label: 'mods', ...modsStep });
+
+  // ── 12. Doctor health check ───────────────────────────────────────
   console.log('');
   const doctor = await runDoctor({ silent: true });
   if (doctor.failed > 0) {

package/config/skills/glyph/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: glyph
-description: Create and consume Bizar glyphs — visual artifacts at `artifacts/<slug>/`. Use for plans, recaps, design proposals, postmortems, handoffs. Quick reference for the block vocabulary and the 5 things that actually break a glyph.
-version: 3
+description: Create visual glyphs at `artifacts/<slug>/` for plans, recaps, design proposals, postmortems, handoffs. Glyphs should be compact and visual — one screen, dense info, no walls of text. This skill enforces that.
+version: 4
 ---
 
 # Glyphs
@@ -15,7 +15,7 @@ artifacts/<slug>/
 └── comments.json      ← free-placed pins (mutable)
 ```
 
-Two locations are scanned: `<projectRoot>/.bizar/artifacts/` (preferred) and `~/.config/opencode/artifacts/` (global).
+Two locations: `<projectRoot>/.bizar/artifacts/` (preferred) and `~/.config/opencode/artifacts/` (global).
 
 ## Frontmatter
 
@@ -28,104 +28,121 @@ kind: plan | postmortem | recap | design
 ---
 ```
 
-## The blocks at a glance
+## The 6 rules — read this first, every time
+
+These are non-negotiable. The existing 357-line v3-to-v4-consolidation glyph is a cautionary tale — don't write that one.
+
+### Rule 1 — One screen
+
+A glyph MUST fit on one screen of the dashboard (≈ 1000px tall at desktop width). Long glyphs are skimmed and abandoned. If you can't fit the work in 5-10 blocks, you're covering too much. Break the work into multiple glyphs, one per phase.
+
+### Rule 2 — One idea per block
+
+If a block covers two ideas, split it. Each block is a single visual unit. The dashboard groups blocks into sections by id prefix — use that.
+
+### Rule 3 — RichText is glue, not body
+
+RichText is for 1-3 sentence transitions between visual blocks. NEVER use RichText for the actual content. If you find yourself writing 4+ sentences in a RichText, switch to:
+
+- **A table** if you're listing things with attributes
+- **A decision** if you're explaining why one option won
+- **A file tree** if you're listing changes
+- **A stat** if you're highlighting a number
+- **A workflow** if you're describing a sequence
+
+### Rule 4 — Lead with visuals
+
+The first block after the title/headline should be a visual: a Stat, a Callout, or a Table. Never open with a long RichText. The user decides in 5 seconds whether to keep scrolling based on the visual.
+
+### Rule 5 — One headline callout
+
+Use `<Callout tone="success|danger">` once, near the top, as the TL;DR. Everything else supports it.
+
+### Rule 6 — Truncate hints, not bodies
+
+Stat `hint` props should be 1 short clause. Long hints mean the value needs to be a different block.
+
+## The block vocabulary — minimal reference
 
 | Block | What it shows | Required `data` |
 | --- | --- | --- |
-| `<RichText>` | Prose, lists, code blocks | none — body is markdown |
-| `<Callout tone="info\|warn\|success\|danger">` | Boxed callout | none (tone defaults to info) |
-| `<Stat label value trend hint />` | Big number with trend | `label`, `value` |
-| `<Checklist items={[...]} />` | Checkbox list | `items: [{id,label,checked}]` |
+| `<RichText>` | 1-3 sentences of glue | none |
+| `<Callout tone>` | Boxed TL;DR | none (tone defaults to info) |
+| `<Stat label value trend hint />` | Big number + label | `label`, `value` |
+| `<Checklist items />` | Checkbox list | `items: [{id,label,checked}]` |
 | `<Table columns rows />` | Tabular data | `columns: []`, `rows: [[]]` |
-| `<CodeTabs tabs />` | Tabbed code blocks | `tabs: [{id,label,language,code}]` |
+| `<CodeTabs tabs />` | Tabbed code | `tabs: [{id,label,language,code}]` |
 | `<Decision title question options />` | Multi-option choice | `options: [{id,label,detail,recommended?}]` |
 | `<OpenQuestions questions />` | Unanswered questions | `questions: [{id,label,kind,options?}]` |
-| `<FileTree title entries />` | File-by-file change list | `entries: [{path,change,note?}]` |
-| `<Diff before after filename language mode />` | Before/after diff | `before`, `after` |
+| `<FileTree title entries />` | File-by-file changes | `entries: [{path,change,note?}]` |
+| `<Diff before after filename language mode />` | Before/after | `before`, `after` |
 | `<Workflow steps connections />` | Node graph | `steps: [{id,label,type}]` |
 | `<Mockup title x y w h html />` | Inline UI mockup | `html` |
 | `<Diagram title dataHtml dataCss />` | Inline SVG | `dataHtml` |
 
-Every block needs a unique `id`. `RichText` and `Callout` use open/close tags with markdown children; everything else is self-closing.
+Every block needs a unique `id`. RichText + Callout use open/close tags (markdown body); everything else is self-closing.
 
 ## Skeleton
 
 ```mdx
 <RichText id="overview">
-## What this covers
+## What this is
 
-A one-paragraph summary.
+One sentence the reader can't miss.
 </RichText>
 
-<Stat id="headline" label="X" value="7" trend="flat" />
+<Stat id="headline" label="X shipped" value="7" trend="flat" hint="across v3.22 → v4.4.7" />
 
-<Callout id="warning" tone="warn">
-One important thing.
+<Callout id="tldr" tone="success">
+One-sentence TL;DR.
 </Callout>
 
+<Table
+  id="releases"
+  columns={["v", "what", "fix"]}
+  rows={[
+    ["3.22", "unified", "—"],
+    ["4.4.1", "bg fix", "process exit crash"],
+  ]}
+/>
+
 <FileTree
   id="files"
   title="Files changed"
   entries={[
-    { path: "src/foo.ts", change: "modified", note: "why" },
-    { path: "src/bar.ts", change: "added" },
-  ]}
-/>
-
-<Workflow
-  id="flow"
-  steps={[
-    { id: "s1", label: "Step 1", type: "task" },
-    { id: "s2", label: "Step 2", type: "task" },
-  ]}
-  connections={[
-    { from: "s1", to: "s2" },
+    { path: "cli/provision.mjs", change: "added", note: "unified provisioner" },
   ]}
 />
 ```
 
 ## The 5 things that break a glyph
 
-Read this BEFORE writing. Each one is a real bug we've shipped.
+These shipped as bugs. Read before writing.
 
 ### 1. Backticks inside attribute strings
 
-The parser scans for `` ` `` to delimit template literals. A literal backtick inside a string — even inside double-quotes — closes the surrounding context and breaks parsing.
+The parser scans for `` ` `` and breaks. Use straight quotes or rephrase:
 
 ```
 WRONG: Run `bizar install` to bootstrap.
 RIGHT: Run 'bizar install' to bootstrap.
-RIGHT: Run the installer to bootstrap.
 ```
 
-### 2. The parser doesn't track strings when counting braces
+### 2. Braces inside string values
 
-`{` and `}` inside string values still increment the brace depth walker. With brace-laden strings the walker terminates at the wrong closing brace and the value gets truncated.
+The brace counter doesn't know about strings. `{` / `}` in notes still bump depth. Keep note strings brace-free.
 
-**Rule:** keep string values brace-free. If you must use `{...}` in a note, escape or rephrase.
+### 3. `FileTree` `change` must be exact
 
-### 3. `FileTree` `change` field must be exact
+`added | modified | removed | renamed`. Empty string or `null` crashes on `t.bg`. Default to `modified` with a `note` when unclear.
 
-`change` must be `added` | `modified` | `removed` | `renamed`. Anything else (empty string, `null`, typo) makes the renderer crash on `t.bg`.
+### 4. Duplicate block ids
 
-```
-WRONG: change: null, change: "", change: "Modified"
-RIGHT: change: "modified"
-```
-
-When in doubt, use `modified` with a `note` that explains why.
-
-### 4. Two blocks with the same id
+Comment pins and error reporting key off ids. Two blocks with the same id collide.
 
-Comment pins and error reporting are keyed by block id. Duplicates collide. Each `id` must be unique within a glyph.
+### 5. `## Heading <768px`
 
-### 5. MDX heading with `<N`
-
-```
-WRONG: ## Mobile <768px         ← <7 looks like a malformed tag
-RIGHT: ## Mobile (under 768px)
-RIGHT: ## Mobile: under 768px
-```
+The parser sees `<7` as a malformed JSX tag. Use parentheses or colons.
 
 ## Validate before shipping
 
@@ -134,14 +151,13 @@ node -e "import('./bizar-dash/src/server/glyphs/mdx-compiler.mjs').then(m => { \
   const fs = require('node:fs'); \
   const out = m.compileGlyphMdxSync(fs.readFileSync('artifacts/<slug>/artifact.mdx','utf8')); \
   console.log('blocks:', out.blocks.length, 'errors:', out.errors.length); \
-  out.errors.forEach(e => console.error('  line', e.line, ':', e.message)); \
 })"
 ```
 
-If errors > 0, fix the MDX before opening the glyph in the browser. When a block DOES fail in the browser, v4.4.8+ shows a red banner with block id + error message — no more blank screen.
+Also check yourself: does it fit on one screen? Are there any 4-sentence RichText blocks? Are the stats/tables/file trees doing the heavy lifting? If not, rewrite.
 
 ## See also
 
 - `bizar-dash/src/server/glyphs/mdx-compiler.mjs` — parser
-- `bizar-dash/src/web/views/glyphs/GlyphRenderer.tsx` — React renderer (has the error banner)
-- `bizar-dash/src/web/views/glyphs/components.tsx` — block component implementations
+- `bizar-dash/src/web/views/glyphs/GlyphRenderer.tsx` — React renderer (has error banner)
+- `bizar-dash/src/web/views/glyphs/components.tsx` — block implementations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "4.4.9",
+  "version": "4.4.11",
   "description": "Norse-pantheon multi-agent system for opencode — 13 agents across 4 cost tiers with cost-aware routing, plans, and a configurable agent harness. v4 ships as a single npm package bundling the dashboard server, opencode plugin, and typed SDK.",
   "type": "module",
   "bin": {