zframes 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 
 // ../core/src/catalogue.ts
 import { z } from "zod";
@@ -9,6 +9,7 @@ function catalogueForAI(input) {
   const metas = input instanceof Map ? [...input.values()] : [...input];
   return metas.map((meta) => ({
     name: meta.name,
+    category: meta.category,
     description: meta.description,
     iconUrl: meta.iconUrl,
     capabilities: meta.capabilities,
@@ -17,6 +18,30 @@ function catalogueForAI(input) {
     configSchema: z.toJSONSchema(meta.schema, { io: "input" })
   }));
 }
+function catalogueSummary(input) {
+  const metas = input instanceof Map ? [...input.values()] : [...input];
+  const order = [];
+  const byCategory = /* @__PURE__ */ new Map();
+  for (const meta of metas) {
+    let group = byCategory.get(meta.category);
+    if (!group) {
+      group = [];
+      byCategory.set(meta.category, group);
+      order.push(meta.category);
+    }
+    group.push(meta);
+  }
+  const lines = [];
+  for (const category of order) {
+    const items = (byCategory.get(category) ?? []).map((meta) => {
+      const desc = meta.description.replace(/\s+/g, " ").trim();
+      const short = desc.length > 110 ? `${desc.slice(0, 109)}\u2026` : desc;
+      return `${meta.name} \u2014 ${short}`;
+    }).join("; ");
+    lines.push(`${category}: ${items}`);
+  }
+  return lines.join("\n");
+}
 
 // ../core/src/spec.ts
 import { z as z2 } from "zod";
@@ -33,13 +58,24 @@ var FrameInstanceSchema = z2.object({
     `Card title shown in the frame's chrome. Overrides the default (the frame type name) \u2014 set a meaningful per-instance label, e.g. the ticker on a price-chart ("TSLA"). Ignored by chrome-less frames like heading.`
   ),
   position: GridPositionSchema,
+  layouts: z2.record(z2.string(), GridPositionSchema).optional().describe(
+    'Per-mode layout overrides keyed by grid.mode (e.g. "flow-horizontal"). `position` is the canonical flow-vertical layout; this holds the other modes\' placements so each layout mode keeps its own independent arrangement. Editor-managed \u2014 agents only need to set `position`.'
+  ),
   config: z2.record(z2.string(), z2.unknown()).default({}).describe(
     "Frame config; validated against the frame's own schema at render time"
   )
 });
 var BackgroundSchema = z2.object({
-  type: z2.enum(["none", "gradient", "unicorn"]).default("gradient").describe(
-    "Background style: 'gradient' (built-in dark glow), 'unicorn' (animated Unicorn Studio scene), or 'none'."
+  type: z2.enum(["none", "color", "gradient", "unicorn"]).default("none").describe(
+    "Background style: 'none' (the signature dark indigo glow \u2014 the default), 'color' (a solid colour), 'gradient' (a custom two-colour linear gradient), or 'unicorn' (an animated Unicorn Studio scene)."
+  ),
+  color: z2.string().default("#0a0a12").describe(
+    "Solid background colour (any CSS colour). Used when type is 'color'."
+  ),
+  gradientFrom: z2.string().default("#1b1e4d").describe("Gradient start colour. Used when type is 'gradient'."),
+  gradientTo: z2.string().default("#07070c").describe("Gradient end colour. Used when type is 'gradient'."),
+  gradientAngle: z2.number().min(0).max(360).default(160).describe(
+    "Gradient angle in degrees (0 = upward, 90 = rightward, 180 = downward). Used when type is 'gradient'."
   ),
   projectId: z2.string().optional().describe(
     "Unicorn Studio public project id \u2014 required when type is 'unicorn'."
@@ -56,8 +92,35 @@ var ThemeSchema = z2.object({
   ),
   accentSat: z2.number().min(0).max(100).default(90).describe(
     "Accent saturation as an HSL percentage (0\u2013100). 90 is the default vivid zframes accent; lower it for muted/pastel rims and dots, 0 for a near-grayscale monochrome accent. Pairs with accentHue \u2014 hue picks the color, saturation picks how vivid it is."
+  ),
+  baseHue: z2.number().int().min(0).max(360).default(233).describe(
+    "Hue of the dark card surface itself, in degrees (0\u2013360). 233 is the default near-black indigo-navy; rotate it to re-temperature every card \u2014 e.g. 30 warms toward charcoal-brown, 150 toward deep forest, 210 toward cool slate. The surface stays dark (lightness is fixed); only its tint moves. Independent of accentHue, which only colours rims/highlights."
+  ),
+  baseSat: z2.number().min(0).max(100).default(20).describe(
+    "Saturation of the dark card surface as an HSL percentage (0\u2013100). 20 is the default subtle navy tint; raise it for a richer coloured-black surface, drop it toward 0 for a neutral graphite/black with no colour cast. Pairs with baseHue."
+  ),
+  upColor: z2.string().regex(/^#[0-9a-fA-F]{6}$/, "must be a 6-digit hex colour like #3fd08f").default("#3fd08f").describe(
+    "Semantic colour for gains / positive change / bullish (up). 6-digit hex; default #3fd08f (green). Tints every gain delta, mover row, up-candle, and 'long'/'call' marker. Set this and downColor to a non-green/red pair (e.g. blue/orange) for a colourblind-friendly dashboard. Distinct from the accent (which is brand colour, not meaning) and from the error red."
+  ),
+  downColor: z2.string().regex(/^#[0-9a-fA-F]{6}$/, "must be a 6-digit hex colour like #ff6b81").default("#ff6b81").describe(
+    "Semantic colour for losses / negative change / bearish (down). 6-digit hex; default #ff6b81 (red). The counterpart to upColor \u2014 tints every loss delta, mover row, down-candle, and 'short'/'put' marker."
   )
-}).describe("Dashboard-wide color identity (accent hue + saturation).");
+}).describe(
+  "Dashboard-wide colour identity \u2014 accent (rims/highlights), the dark card-surface tint (base), and the semantic up/down (gain/loss) colours."
+);
+var TypographySchema = z2.object({
+  fontFamily: z2.enum(["sans", "mono", "serif"]).default("sans").describe(
+    "Type family for all dashboard text. 'sans' is the default DM Sans (clean, modern); 'mono' switches to a monospaced system stack (a Bloomberg/terminal feel, numbers in fixed columns); 'serif' uses a system serif (editorial). Affects card titles, labels, and readouts alike."
+  ),
+  numericStyle: z2.enum(["proportional", "tabular"]).default("proportional").describe(
+    "How digits are spaced everywhere on the dashboard. 'proportional' is the default (natural widths); 'tabular' forces fixed-width figures (font-variant-numeric: tabular-nums) so live prices and tickers stop shifting sideways as digits change \u2014 recommended for number-dense dashboards. Hero stat numerals are always tabular regardless."
+  ),
+  scale: z2.number().min(0.85).max(1.25).default(1).describe(
+    "Global text-size multiplier (0.85\u20131.25). 1 is the default. Scales all dashboard text together by setting the root font size, so chart labels, readouts, and titles grow or shrink as one \u2014 raise it for legibility on a large display, lower it to pack more in. Distinct from appearance.density, which scales card padding, not text. Grid cell heights are in pixels and stay fixed, so text can overflow a small card at high scale."
+  )
+}).describe(
+  "Dashboard-wide typography \u2014 font family, numeric digit style, and global text scale."
+);
 var AppearanceSchema = z2.object({
   radius: z2.number().min(0).default(18).describe(
     "Frame corner radius in pixels, applied to every card via --zf-frame-radius. 0 squares the corners; the editor's Appearance rail exposes this as a slider."
@@ -80,11 +143,11 @@ var AppearanceSchema = z2.object({
 var DashboardSpecSchema = z2.preprocess(
   (raw) => {
     if (!raw || typeof raw !== "object") return raw;
-    const r = raw;
+    let r = raw;
     const grid = r.grid;
     if (grid && typeof grid === "object" && "radius" in grid) {
       const { radius, ...restGrid } = grid;
-      return {
+      r = {
         ...r,
         grid: restGrid,
         appearance: {
@@ -93,7 +156,14 @@ var DashboardSpecSchema = z2.preprocess(
         }
       };
     }
-    return raw;
+    const bg = r.background;
+    if (bg && typeof bg === "object" && bg.type === "gradient" && !("gradientFrom" in bg)) {
+      r = {
+        ...r,
+        background: { ...bg, type: "none" }
+      };
+    }
+    return r;
   },
   z2.object({
     version: z2.coerce.string().default("1.0.0").describe(
@@ -104,19 +174,51 @@ var DashboardSpecSchema = z2.preprocess(
       `Who made this dashboard \u2014 a free-form credit, like package.json's author ("You" or "You <you@example.com>"). Optional.`
     ),
     grid: z2.object({
-      columns: z2.number().int().min(1).default(12),
-      rowHeight: z2.number().min(8).default(96),
+      mode: z2.enum(["flow-vertical", "flow-horizontal", "canvas"]).default("flow-vertical").describe(
+        "Layout model. 'flow-vertical' (default): a fixed number of columns fill the viewport width; the board grows downward and scrolls vertically \u2014 the classic dashboard. 'flow-horizontal': a fixed number of rows fill the viewport height; the board grows rightward and scrolls horizontally \u2014 suited to ultrawide and wall displays. 'canvas': an unbounded pan/zoom plane (not yet implemented; rendered as flow-vertical for now)."
+      ),
+      columns: z2.number().int().min(1).default(12).describe(
+        "Number of columns the grid is divided into across the viewport width (flow-vertical). A frame's `position` x/w are in these column units."
+      ),
+      rowHeight: z2.number().min(8).default(96).describe(
+        "Pixel height of each grid row (flow-vertical). A frame's `position` y/h are in these row units."
+      ),
+      rows: z2.number().int().min(1).default(6).describe(
+        'Number of height-bounded rows the horizontal board (flow-horizontal) fills before it scrolls sideways. A frame\'s `layouts["flow-horizontal"]` y/h are in these row units. Ignored in flow-vertical.'
+      ),
       gap: z2.number().min(0).default(12).describe(
         "Pixels of space between frames (the grid gutter). 0 makes the cards flush; the editor's Layout rail exposes this as a slider."
       )
-    }).default({ columns: 12, rowHeight: 96, gap: 12 }),
+    }).default({
+      mode: "flow-vertical",
+      columns: 12,
+      rowHeight: 96,
+      rows: 6,
+      gap: 12
+    }),
     background: BackgroundSchema.default({
-      type: "gradient",
+      type: "none",
+      color: "#0a0a12",
+      gradientFrom: "#1b1e4d",
+      gradientTo: "#07070c",
+      gradientAngle: 160,
       scale: 1,
       dpi: 1.5,
       opacity: 0.16
     }),
-    theme: ThemeSchema.default({ accentHue: 242, accentSat: 90 }),
+    theme: ThemeSchema.default({
+      accentHue: 242,
+      accentSat: 90,
+      baseHue: 233,
+      baseSat: 20,
+      upColor: "#3fd08f",
+      downColor: "#ff6b81"
+    }),
+    typography: TypographySchema.default({
+      fontFamily: "sans",
+      numericStyle: "proportional",
+      scale: 1
+    }),
     appearance: AppearanceSchema.default({
       radius: 18,
       borderStrength: 0.22,
@@ -128,6 +230,164 @@ var DashboardSpecSchema = z2.preprocess(
   })
 );
 
+// ../core/src/store.ts
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync
+} from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+var NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
+function isValidName(name) {
+  return name.length <= 64 && NAME_RE.test(name);
+}
+function storeHome() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.trim() ? xdg.trim() : join(homedir(), ".config");
+  return join(base, "zframes");
+}
+function dashboardsDir() {
+  return join(storeHome(), "dashboards");
+}
+function configPath() {
+  return join(storeHome(), "config.json");
+}
+function credentialsFile() {
+  return join(storeHome(), "credentials.json");
+}
+function dashboardPath(name) {
+  return join(dashboardsDir(), name, "dashboard.json");
+}
+function findDashboardFile(name) {
+  const folder = dashboardPath(name);
+  if (isFile(folder)) return folder;
+  const flat = join(dashboardsDir(), `${name}.json`);
+  if (isFile(flat)) return flat;
+  return null;
+}
+function ensureHome() {
+  mkdirSync(storeHome(), { recursive: true, mode: 448 });
+  mkdirSync(dashboardsDir(), { recursive: true });
+}
+function isFile(file) {
+  try {
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+function expandTilde(p) {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+  return p;
+}
+function looksLikePath(arg) {
+  return arg.includes("/") || arg.includes("\\") || arg.startsWith(".") || arg.startsWith("~") || arg.toLowerCase().endsWith(".json");
+}
+function classifyTarget(arg, cwd) {
+  if (looksLikePath(arg)) {
+    return { kind: "path", file: resolve(cwd, expandTilde(arg)) };
+  }
+  if (!isValidName(arg)) {
+    return {
+      error: `"${arg}" is not a valid dashboard name (lowercase letters, digits, "-", "_") or a path to a .json file`
+    };
+  }
+  return { kind: "store", name: arg, file: dashboardPath(arg) };
+}
+function readConfig() {
+  try {
+    const json2 = JSON.parse(readFileSync(configPath(), "utf8"));
+    return json2 && typeof json2 === "object" ? json2 : {};
+  } catch {
+    return {};
+  }
+}
+function getDefault() {
+  const d = readConfig().default;
+  return typeof d === "string" && d ? d : null;
+}
+function setDefault(name) {
+  ensureHome();
+  const cfg = readConfig();
+  cfg.default = name;
+  writeFileSync(configPath(), `${JSON.stringify(cfg, null, 2)}
+`, "utf8");
+}
+function listDashboards() {
+  const dir = dashboardsDir();
+  const names = /* @__PURE__ */ new Set();
+  try {
+    for (const ent of readdirSync(dir, { withFileTypes: true })) {
+      if (ent.isDirectory()) {
+        if (isValidName(ent.name) && isFile(join(dir, ent.name, "dashboard.json")))
+          names.add(ent.name);
+      } else if (ent.isFile() && ent.name.toLowerCase().endsWith(".json")) {
+        const stem = ent.name.slice(0, -5);
+        if (isValidName(stem)) names.add(stem);
+      }
+    }
+  } catch {
+    return [];
+  }
+  const def = getDefault();
+  return [...names].sort().map((name) => {
+    const file = findDashboardFile(name) ?? dashboardPath(name);
+    let title = null;
+    try {
+      const json2 = JSON.parse(readFileSync(file, "utf8"));
+      if (typeof json2.title === "string") title = json2.title;
+    } catch {
+    }
+    return { name, file, title, isDefault: name === def };
+  });
+}
+function resolveServeTarget(arg, cwd) {
+  if (arg !== void 0) {
+    const c = classifyTarget(arg, cwd);
+    if ("error" in c) return c;
+    if (c.kind === "store") {
+      const file = findDashboardFile(c.name);
+      if (!file) {
+        return {
+          error: `no dashboard named "${c.name}" in the store (${dashboardsDir()})
+  create it with \`zframes init ${c.name}\`, or run \`zframes list\` to see what's there.`
+        };
+      }
+      return { kind: "store", name: c.name, file };
+    }
+    if (!isFile(c.file)) {
+      return {
+        error: `no dashboard.json at ${arg}
+  pass a path, a store name, or run from a directory that has one.`
+      };
+    }
+    return c;
+  }
+  const def = getDefault();
+  if (def) {
+    const file = findDashboardFile(def);
+    if (file) return { kind: "store", name: def, file };
+  }
+  const cwdFile = join(cwd, "dashboard.json");
+  if (isFile(cwdFile)) return { kind: "path", file: cwdFile };
+  const entries = listDashboards();
+  if (entries.length === 1) {
+    return { kind: "store", name: entries[0].name, file: entries[0].file };
+  }
+  if (entries.length > 1) {
+    return {
+      error: `no default dashboard set, and ${entries.length} in the store \u2014 pass a name (\`zframes serve <name>\`), set a default (\`zframes use <name>\`), or list them (\`zframes list\`).`
+    };
+  }
+  return {
+    error: "no dashboard found \u2014 create one with `zframes init <name>`, or pass a path to a dashboard.json."
+  };
+}
+
 // ../core/src/frame.ts
 function defineFrameMeta(meta) {
   return meta;
@@ -161,10 +421,12 @@ var SOURCES = {
   },
   mempool: { name: "mempool.space", url: "https://mempool.space" },
   deribit: { name: "Deribit", url: "https://www.deribit.com" },
-  coinpaprika: { name: "Coinpaprika", url: "https://coinpaprika.com" }
+  coinpaprika: { name: "Coinpaprika", url: "https://coinpaprika.com" },
+  frankfurter: { name: "Frankfurter (ECB)", url: "https://frankfurter.dev" }
 };
 var clockMeta = defineFrameMeta({
   name: "clock",
+  category: "tools",
   iconUrl: widgetIcon("clock"),
   layout: { w: 3, h: 2, minW: 2, minH: 1 },
   description: "Digital clock showing the current time, ticking every second. Configurable IANA timezone (defaults to the viewer's local zone), 12/24-hour format, optional seconds and date, the timezone abbreviation, and a caption label. Drop several with different timezones for a trading-desk world clock. Needs no data provider.",
@@ -189,6 +451,7 @@ var clockMeta = defineFrameMeta({
 });
 var marketHoursMeta = defineFrameMeta({
   name: "market-hours",
+  category: "tools",
   iconUrl: widgetIcon("market-hours"),
   layout: { w: 4, h: 4, minW: 3, minH: 3 },
   description: "Which world stock exchanges are open right now \u2014 each row shows an open / closed / holiday status dot and a live countdown to the next open or close. Computed entirely client-side from each exchange's timezone and regular trading hours (no API); a bundled 2026 holiday list keeps the major Western exchanges accurate on market holidays. Intraday lunch breaks and half-day early closes are not modelled. Needs no data provider.",
@@ -204,6 +467,7 @@ var marketHoursMeta = defineFrameMeta({
 });
 var fearGreedMeta = defineFrameMeta({
   name: "fear-greed",
+  category: "sentiment",
   iconUrl: widgetIcon("fear-greed"),
   layout: { w: 3, h: 3, minW: 2, minH: 2 },
   description: "Crypto Fear & Greed index (0 = extreme fear, 100 = extreme greed) with a recent-history sparkline. A one-number market mood gauge from alternative.me.",
@@ -215,6 +479,7 @@ var fearGreedMeta = defineFrameMeta({
 });
 var fundingRateChartMeta = defineFrameMeta({
   name: "funding-rate-chart",
+  category: "derivatives",
   iconUrl: widgetIcon("funding-rate-chart"),
   layout: { w: 6, h: 3, minW: 3, minH: 2 },
   description: "Multi-series line chart comparing hourly perp funding rates across symbols over a configurable lookback window. Positive funding = longs pay shorts. Useful for spotting crowded trades.",
@@ -229,6 +494,7 @@ var fundingRateChartMeta = defineFrameMeta({
 });
 var noteMeta = defineFrameMeta({
   name: "note",
+  category: "layout",
   iconUrl: widgetIcon("note"),
   layout: { w: 4, h: 3, minW: 2, minH: 2 },
   description: "Free-form text note pinned to the dashboard \u2014 trading plans, reminders, watch levels. Needs no data provider.",
@@ -240,14 +506,15 @@ var noteMeta = defineFrameMeta({
 });
 var priceChartMeta = defineFrameMeta({
   name: "price-chart",
+  category: "markets",
   iconUrl: widgetIcon("price-chart"),
   layout: { w: 6, h: 3, minW: 3, minH: 2 },
-  description: "Live animated price chart (candlestick or line) for one symbol \u2014 canvas-rendered at 60fps via liveline, streaming live off the Hyperliquid WebSocket. Works for HIP-3 stock perps (xyz:TSLA) and crypto (BTC). The centerpiece frame.",
+  description: "Live animated price chart (candlestick or line) for one symbol \u2014 canvas-rendered at 60fps via liveline, streaming live off the Hyperliquid WebSocket. Works for any HIP-3 perp \u2014 stocks (xyz:TSLA), indices (xyz:SP500), commodities (xyz:GOLD) \u2014 and crypto (BTC). The centerpiece frame.",
   capabilities: ["ohlcv", "quote-stream"],
   source: SOURCES.hyperliquid,
   schema: z3.object({
     symbol: z3.string().min(1).describe(
-      'Hyperliquid symbol to chart. Stocks/HIP-3: "xyz:TSLA", "xyz:NVDA", "xyz:AAPL". Crypto: "BTC", "ETH".'
+      'Hyperliquid symbol to chart. HIP-3 cross-asset: stocks "xyz:TSLA"/"xyz:NVDA", indices "xyz:SP500"/"xyz:XYZ100", commodities "xyz:GOLD"/"xyz:CL", FX "xyz:EUR". Crypto: "BTC", "ETH".'
     ),
     interval: z3.enum(["1m", "5m", "15m", "1h", "4h", "1d"]).default("1h").describe("Candle interval."),
     mode: z3.enum(["candle", "line"]).default("candle").describe("Candlestick or smooth line rendering."),
@@ -256,6 +523,7 @@ var priceChartMeta = defineFrameMeta({
 });
 var priceLivelineMeta = defineFrameMeta({
   name: "price-liveline",
+  category: "markets",
   iconUrl: widgetIcon("price-liveline"),
   layout: { w: 6, h: 3, minW: 4, minH: 2 },
   description: "Multi-asset live price liveline \u2014 several Hyperliquid symbols streaming in one canvas chart. Defaults to normalized % movement so stocks and crypto can share one axis, while the legend still shows each asset's live raw price. Use when the dashboard needs one compact live race view instead of several single-symbol charts.",
@@ -263,7 +531,7 @@ var priceLivelineMeta = defineFrameMeta({
   source: SOURCES.hyperliquid,
   schema: z3.object({
     symbols: z3.array(z3.string()).min(2).max(8).describe(
-      'Hyperliquid symbols to stream together, e.g. ["xyz:TSLA", "xyz:NVDA", "xyz:AAPL"] or ["BTC", "ETH", "SOL"]. 2 to 8.'
+      'Hyperliquid symbols to stream together \u2014 great cross-asset (the normalized view races a stock vs the index vs gold vs crude), e.g. ["xyz:NVDA", "xyz:SP500", "xyz:GOLD", "xyz:CL"], or all-equity ["xyz:TSLA", "xyz:NVDA", "xyz:AAPL"], or crypto ["BTC", "ETH", "SOL"]. 2 to 8.'
     ),
     windowSec: z3.number().int().min(10).max(300).default(30).describe(
       "Rolling live window in seconds. 30 mirrors the zhive liveline view; use 60\u2013300 for slower dashboards."
@@ -275,6 +543,7 @@ var priceLivelineMeta = defineFrameMeta({
 });
 var priceTickerMeta = defineFrameMeta({
   name: "price-ticker",
+  category: "markets",
   iconUrl: widgetIcon("price-ticker"),
   layout: { w: 3, h: 3, minW: 2, minH: 2 },
   description: "Live watchlist streaming mid prices over the Hyperliquid WebSocket with 24h change per symbol. The bread-and-butter frame for any dashboard.",
@@ -282,12 +551,13 @@ var priceTickerMeta = defineFrameMeta({
   source: SOURCES.hyperliquid,
   schema: z3.object({
     symbols: z3.array(z3.string()).min(1).describe(
-      'Hyperliquid symbols to track, e.g. ["xyz:TSLA", "xyz:NVDA", "xyz:AAPL"]. Crypto works too: "BTC", "ETH".'
+      'Hyperliquid symbols to track \u2014 mix asset classes, e.g. ["xyz:NVDA", "xyz:SP500", "xyz:GOLD", "xyz:EUR"] or all-equity ["xyz:TSLA", "xyz:NVDA", "xyz:AAPL"]. Crypto works too: "BTC", "ETH".'
     )
   })
 });
 var topMoversMeta = defineFrameMeta({
   name: "top-movers",
+  category: "markets",
   iconUrl: widgetIcon("top-movers"),
   layout: { w: 5, h: 3, minW: 3, minH: 3 },
   description: "Today's biggest stock and commodity HIP-3 gainers and losers (no bare crypto), side by side with current price and 24h change.",
@@ -299,6 +569,7 @@ var topMoversMeta = defineFrameMeta({
 });
 var tvlTreemapMeta = defineFrameMeta({
   name: "tvl-treemap",
+  category: "crypto",
   iconUrl: widgetIcon("tvl-treemap"),
   layout: { w: 6, h: 4, minW: 3, minH: 3 },
   description: "Treemap of total value locked (TVL) across the largest blockchain ecosystems, sized by TVL. Data from DeFiLlama. Good single-glance answer to 'where does on-chain capital live right now'.",
@@ -310,6 +581,7 @@ var tvlTreemapMeta = defineFrameMeta({
 });
 var bitcoinDominanceMeta = defineFrameMeta({
   name: "bitcoin-dominance",
+  category: "crypto",
   iconUrl: widgetIcon("bitcoin-dominance"),
   layout: { w: 4, h: 2, minW: 3, minH: 2 },
   description: "BTC / ETH / Others market-cap dominance as a segmented bar, with optional total marketcap line. Shifts in BTC dominance hint at where the market rotates next.",
@@ -323,6 +595,7 @@ var bitcoinDominanceMeta = defineFrameMeta({
 });
 var ratesBoardMeta = defineFrameMeta({
   name: "rates-board",
+  category: "macro",
   iconUrl: widgetIcon("rates-board"),
   layout: { w: 4, h: 4, minW: 3, minH: 3 },
   description: "Official US rates board from free public APIs: New York Fed reference rates (SOFR, effective fed funds, repo rates) plus Treasury average interest rates by security class. Daily/reference data, not a real-time stock quote feed.",
@@ -336,8 +609,27 @@ var ratesBoardMeta = defineFrameMeta({
     maxTreasuryRates: z3.number().int().min(1).max(8).default(4).describe("How many Treasury average-rate rows to show.")
   })
 });
+var fxBoardMeta = defineFrameMeta({
+  name: "fx-board",
+  category: "macro",
+  iconUrl: widgetIcon("fx-board"),
+  layout: { w: 4, h: 4, minW: 3, minH: 3 },
+  description: "Foreign-exchange board from the ECB's free daily reference rates (via Frankfurter, no key): each currency's latest rate vs a base, its day-over-day change, and a short trend sparkline. Daily reference data with broader currency coverage than the handful of FX perps \u2014 not a live intraday quote feed.",
+  capabilities: ["fx-rates"],
+  source: SOURCES.frankfurter,
+  schema: z3.object({
+    base: z3.string().length(3).default("USD").describe(
+      'Base currency (ISO 4217 code) each rate is quoted against, e.g. "USD". One unit of the base buys the shown amount of each listed currency.'
+    ),
+    symbols: z3.array(z3.string().length(3)).min(1).max(12).default(["EUR", "GBP", "JPY", "CHF", "CAD", "AUD"]).describe(
+      'Currencies to show (ISO 4217 codes), e.g. ["EUR","GBP","JPY"]. The ECB publishes ~30; a code equal to the base is skipped.'
+    ),
+    showSparkline: z3.boolean().default(true).describe("Show a small ~30-day trend sparkline next to each rate.")
+  })
+});
 var inflationPulseMeta = defineFrameMeta({
   name: "inflation-pulse",
+  category: "macro",
   iconUrl: widgetIcon("inflation-pulse"),
   layout: { w: 4, h: 3, minW: 3, minH: 2 },
   description: "BLS CPI pulse from the public no-key API: latest CPI-U all-items index with month-over-month and year-over-year changes plus a small trend sparkline. Monthly macro context for stock dashboards; not a live price feed.",
@@ -349,6 +641,7 @@ var inflationPulseMeta = defineFrameMeta({
 });
 var financialStressMeta = defineFrameMeta({
   name: "financial-stress",
+  category: "macro",
   iconUrl: widgetIcon("financial-stress"),
   layout: { w: 4, h: 3, minW: 3, minH: 2 },
   description: "The OFR Financial Stress Index \u2014 a daily, market-based gauge of systemic financial stress from the U.S. Office of Financial Research. One headline value where 0 is the long-run average (positive = elevated stress, negative = calmer than normal), an optional breakdown of the five contributing categories (credit, equity valuation, safe assets, funding, volatility), and a trend line. Keyless official data, updated each business day; needs the zframes runtime's data proxy (ships with `zframes serve` / `vite dev`). Not a price feed.",
@@ -363,6 +656,7 @@ var financialStressMeta = defineFrameMeta({
 });
 var nationalDebtMeta = defineFrameMeta({
   name: "national-debt",
+  category: "macro",
   iconUrl: widgetIcon("national-debt"),
   layout: { w: 4, h: 3, minW: 3, minH: 2 },
   description: "U.S. total public debt outstanding from the Treasury's keyless 'Debt to the Penny' dataset \u2014 the headline total in trillions, the change over the chosen window, an optional split into debt held by the public vs intragovernmental holdings, and a trend line. Official data updated each business day; CORS-safe (no proxy needed). Macro context, not a live price feed.",
@@ -379,6 +673,7 @@ var nationalDebtMeta = defineFrameMeta({
 });
 var laborMarketMeta = defineFrameMeta({
   name: "labor-market",
+  category: "macro",
   iconUrl: widgetIcon("labor-market"),
   layout: { w: 4, h: 3, minW: 3, minH: 2 },
   description: "U.S. labor-market snapshot from the BLS keyless public API: the headline unemployment rate, the latest monthly change in nonfarm payrolls (jobs added or lost), the total payroll level, and an unemployment-rate trend line. Monthly macro context for stock dashboards; updates on the BLS jobs-report schedule, not a live feed.",
@@ -390,6 +685,7 @@ var laborMarketMeta = defineFrameMeta({
 });
 var treasuryAuctionsMeta = defineFrameMeta({
   name: "treasury-auctions",
+  category: "macro",
   iconUrl: widgetIcon("treasury-auctions"),
   layout: { w: 5, h: 4, minW: 3, minH: 3 },
   description: "Recent completed U.S. Treasury auctions from the keyless Fiscal Data API \u2014 each row shows the security (bill/note/bond + term), the high awarded yield, and the bid-to-cover ratio (demand: total bids \xF7 amount accepted; higher = stronger). Newest first. Official market-plumbing data, CORS-safe; updates as auctions settle, not a live price feed.",
@@ -401,6 +697,7 @@ var treasuryAuctionsMeta = defineFrameMeta({
 });
 var filingsFeedMeta = defineFrameMeta({
   name: "filings-feed",
+  category: "equities",
   iconUrl: widgetIcon("filings-feed"),
   layout: { w: 5, h: 4, minW: 3, minH: 3 },
   description: "Recent SEC EDGAR filings for one US-listed company \u2014 each row shows the form type (10-K, 10-Q, 8-K, Form 4\u2026), a plain-English label, the filing date, and a click-through to the document on sec.gov, under a header with the company name, exchange, and filer category. Official data from SEC's free, CORS-safe submissions endpoint; event-driven (updates when the company files), not a price feed. Resolve by ticker (a bundled snapshot of the ~500 largest US issuers) or by raw SEC CIK for anything else.",
@@ -418,6 +715,7 @@ var filingsFeedMeta = defineFrameMeta({
 });
 var yieldCurveMeta = defineFrameMeta({
   name: "yield-curve",
+  category: "macro",
   iconUrl: widgetIcon("yield-curve"),
   layout: { w: 4, h: 3, minW: 3, minH: 3 },
   description: "The U.S. Treasury daily par yield curve \u2014 a line from 1-month to 30-year yields, the headline 2s10s spread (10Y minus 2Y; negative = inverted, the classic recession signal), and a configurable row of key maturities. Keyless official data from the U.S. Treasury, updated each business day; not a live intraday feed.",
@@ -447,6 +745,7 @@ var yieldCurveMeta = defineFrameMeta({
 });
 var fundamentalsMeta = defineFrameMeta({
   name: "fundamentals",
+  category: "equities",
   iconUrl: widgetIcon("fundamentals"),
   layout: { w: 4, h: 3, minW: 3, minH: 3 },
   description: "Headline financials for one US-listed company from SEC EDGAR XBRL company facts \u2014 revenue, net income, total assets, shareholders' equity, diluted EPS, and shares outstanding, each labelled with its fiscal period. Income-statement figures are the latest full fiscal year; balance-sheet figures are the latest reported quarter. Keyless official data that updates only when the company files (annual/quarterly), not a live feed. Requires the zframes runtime's data proxy (it ships with `zframes serve` / `vite dev`); resolve by ticker (bundled top-500 map) or raw SEC CIK.",
@@ -460,6 +759,7 @@ var fundamentalsMeta = defineFrameMeta({
 });
 var shortVolumeMeta = defineFrameMeta({
   name: "short-volume",
+  category: "equities",
   iconUrl: widgetIcon("short-volume"),
   layout: { w: 5, h: 4, minW: 3, minH: 3 },
   description: "Daily reported short-sale volume for a watchlist of US-listed stocks, from FINRA's free consolidated file \u2014 each row shows the % of the day's reported volume that was sold short, with a bar and the raw short/total share counts. IMPORTANT: this is reported short volume (sell-side short flow, which includes market-maker hedging), NOT short interest (outstanding short positions), and is not a directional signal on its own. Daily data published the next business day; not a live feed. US equities only.",
@@ -476,6 +776,7 @@ var shortVolumeMeta = defineFrameMeta({
 });
 var fundingHeatmapMeta = defineFrameMeta({
   name: "funding-heatmap",
+  category: "derivatives",
   iconUrl: widgetIcon("funding-heatmap"),
   layout: { w: 6, h: 3, minW: 4, minH: 3 },
   description: "Heatmap of perp funding rates \u2014 symbols as rows, daily average over the last 7 days as columns, green positive / red negative. Spots persistent funding regimes at a glance.",
@@ -489,6 +790,7 @@ var fundingHeatmapMeta = defineFrameMeta({
 });
 var dinoGameMeta = defineFrameMeta({
   name: "dino-game",
+  category: "games",
   iconUrl: widgetIcon("dino-game"),
   layout: { w: 4, h: 3, minW: 3, minH: 3 },
   description: "Chrome-dino style runner game on canvas \u2014 jump cacti with SPACE or tap. High score persists locally. For when the market is boring. Needs no data provider.",
@@ -497,6 +799,7 @@ var dinoGameMeta = defineFrameMeta({
 });
 var imageMeta = defineFrameMeta({
   name: "image",
+  category: "layout",
   iconUrl: widgetIcon("image"),
   layout: { w: 3, h: 3, minW: 1, minH: 1 },
   description: "Displays an image from a URL \u2014 logos, memes, chart screenshots, banners. Needs no data provider.",
@@ -511,6 +814,7 @@ var imageMeta = defineFrameMeta({
 });
 var headingMeta = defineFrameMeta({
   name: "heading",
+  category: "layout",
   iconUrl: widgetIcon("heading"),
   layout: { w: 12, h: 1, minW: 2, minH: 1, maxH: 1 },
   description: "Section divider that titles a region of the dashboard ('Markets', 'On-chain', 'Desk'). Renders as a label with a hairline rule \u2014 no card. Use to group frames into zones: place full-width (w: 12) and 1 row tall (h: 1) above each group. Needs no data provider.",
@@ -523,6 +827,7 @@ var headingMeta = defineFrameMeta({
 });
 var dailyAnalysisMeta = defineFrameMeta({
   name: "daily-analysis",
+  category: "tools",
   iconUrl: widgetIcon("daily-analysis"),
   layout: { w: 6, h: 3, minW: 3, minH: 2 },
   description: "Daily market brief written by the /zframes-brief loop \u2014 a dated analysis of the symbols on your dashboard, the calls it is making today, and how yesterday's calls scored (with a running hit-rate). Reads a local log file the loop appends to; needs no market data provider. Add one per dashboard.",
@@ -539,8 +844,51 @@ var dailyAnalysisMeta = defineFrameMeta({
     )
   })
 });
+var journalLogMeta = defineFrameMeta({
+  name: "journal-log",
+  category: "journal",
+  iconUrl: widgetIcon("journal-log"),
+  layout: { w: 4, h: 5, minW: 3, minH: 4 },
+  source: SOURCES.hyperliquid,
+  description: "Log a market read in seconds: pick a supported ticker (with its live Hyperliquid price), Long or Short, the reason (a quick pick + optional note), and how sure you are (a slider). That's it \u2014 a falsifiable call, captured at the live price, that the Open/Results frames then track and grade. The simple front door to your decision journal; pairs with the zAI orb for conversational capture. Add one alongside Journal \xB7 Open and Journal \xB7 Results.",
+  capabilities: ["quote-stream", "day-stats"],
+  schema: z3.object({})
+});
+var journalOpenMeta = defineFrameMeta({
+  name: "journal-open",
+  category: "journal",
+  iconUrl: widgetIcon("journal-open"),
+  layout: { w: 4, h: 4, minW: 3, minH: 3 },
+  description: "Your open calls from the decision journal, each marking to the live Hyperliquid price \u2014 direction, confidence, unrealized % return, a live entry\u2192target track, and a countdown. Calls auto-grade at their horizon (or close one early). The 'watch it play out' frame. Reads the journal you write with Journal \xB7 Log.",
+  source: SOURCES.hyperliquid,
+  capabilities: ["quote-stream"],
+  schema: z3.object({
+    max: z3.number().int().min(1).max(20).default(8).describe("How many open calls to show (newest first).")
+  })
+});
+var journalResultsMeta = defineFrameMeta({
+  name: "journal-results",
+  category: "journal",
+  iconUrl: widgetIcon("journal-results"),
+  layout: { w: 4, h: 4, minW: 3, minH: 3 },
+  description: "Your resolved calls from the decision journal, graded on TWO axes: did it hit, AND did the thesis actually play out \u2014 so a lucky hit reads differently from earned skill, and a near-miss from a clean miss. The reflection frame. Reads the journal you write with Journal \xB7 Log.",
+  capabilities: [],
+  schema: z3.object({
+    max: z3.number().int().min(1).max(20).default(8).describe("How many resolved calls to show (newest first).")
+  })
+});
+var journalScoreMeta = defineFrameMeta({
+  name: "journal-score",
+  category: "journal",
+  iconUrl: widgetIcon("journal-score"),
+  layout: { w: 4, h: 2, minW: 3, minH: 2 },
+  description: "The decision-journal scoreboard \u2014 a story, not a spreadsheet: where your judgment has an edge, where it leaks, and how calibrated your confidence is, plus a one-line read from zAI. Aggregates the calls logged via Journal \xB7 Log.",
+  capabilities: [],
+  schema: z3.object({})
+});
 var priceCompareMeta = defineFrameMeta({
   name: "price-compare",
+  category: "markets",
   iconUrl: widgetIcon("price-compare"),
   layout: { w: 6, h: 3, minW: 3, minH: 2 },
   description: "Multi-series line chart overlaying the price history of several symbols over a lookback window \u2014 see how TSLA, NVDA and BTC moved against each other. Normalized by default to % change from the window start so symbols at very different price levels (BTC vs a $20 stock) stay comparable on one axis. Candles from Hyperliquid.",
@@ -556,26 +904,53 @@ var priceCompareMeta = defineFrameMeta({
     )
   })
 });
-var allocationMeta = defineFrameMeta({
-  name: "allocation",
-  iconUrl: widgetIcon("allocation"),
-  layout: { w: 4, h: 4, minW: 3, minH: 3 },
-  description: "Donut of a portfolio's live allocation \u2014 list holdings (symbol + amount) and each slice is sized by current USD value off the Hyperliquid mid stream, with total portfolio value in the center. A live 'where is my money right now' view.",
-  capabilities: ["quote-stream"],
-  source: SOURCES.hyperliquid,
+var portfolioConfigShape = {
+  source: z3.enum(["binance", "wallet"]).default("binance").describe(
+    'Where the holdings come from: "binance" (a connected Binance account \u2014 a read-only API key is entered in-app and stored locally, never in this file) or "wallet" (a public on-chain address, keyless).'
+  ),
+  address: z3.string().default("").describe(
+    'For source "wallet": the public Ethereum address (0x\u2026) or ENS name to track. Public on-chain data, no keys. Ignored for "binance".'
+  )
+};
+var portfolioValueMeta = defineFrameMeta({
+  name: "portfolio-value",
+  category: "portfolio",
+  iconUrl: widgetIcon("portfolio-value"),
+  layout: { w: 5, h: 4, minW: 3, minH: 3 },
+  description: "Your connected portfolio's total USD value as a live equity line, ticking with the market. Source is a connected Binance account (read-only key, entered in-app) or a public on-chain wallet address. Shows total value + session change. Renders a connect prompt until a source is set.",
+  capabilities: ["portfolio", "quote-stream"],
+  account: true,
   schema: z3.object({
-    holdings: z3.array(
-      z3.object({
-        symbol: z3.string().min(1).describe('Hyperliquid symbol, e.g. "BTC", "ETH", "xyz:TSLA".'),
-        amount: z3.number().positive().describe(
-          "Units held (e.g. 0.5 BTC, 10 shares). Weights the slice by USD value = amount \xD7 live price."
-        )
-      })
-    ).min(2).max(8).describe("The holdings to chart. 2 to 8 positions.")
+    ...portfolioConfigShape,
+    windowSec: z3.number().int().positive().default(300).describe(
+      "Seconds of live history the equity line shows; it accumulates from when the dashboard opens."
+    )
   })
 });
+var portfolioAllocationMeta = defineFrameMeta({
+  name: "portfolio-allocation",
+  category: "portfolio",
+  iconUrl: widgetIcon("portfolio-allocation"),
+  layout: { w: 4, h: 4, minW: 3, minH: 3 },
+  description: "Donut of your connected portfolio's allocation \u2014 each slice sized by live USD value, total in the center. Source is a connected Binance account (read-only key, in-app) or a public on-chain wallet address. Renders a connect prompt until a source is set.",
+  capabilities: ["portfolio", "quote-stream"],
+  account: true,
+  schema: z3.object({ ...portfolioConfigShape })
+});
+var portfolioHoldingsMeta = defineFrameMeta({
+  name: "portfolio-holdings",
+  category: "portfolio",
+  iconUrl: widgetIcon("portfolio-holdings"),
+  layout: { w: 4, h: 4, minW: 3, minH: 3 },
+  description: "Table of your connected portfolio's positions \u2014 asset, amount, live USD value, share of total, 24h change. Source is a connected Binance account (read-only key, in-app) or a public on-chain wallet address. Renders a connect prompt until a source is set.",
+  capabilities: ["portfolio", "quote-stream"],
+  account: true,
+  schema: z3.object({ ...portfolioConfigShape })
+});
 var newsFeedMeta = defineFrameMeta({
   name: "news-feed",
+  category: "sentiment",
+  iconUrl: widgetIcon("news-feed"),
   layout: { w: 4, h: 4, minW: 3, minH: 3 },
   description: 'Scrolling feed of the latest news headlines from a chosen outlet \u2014 each row is a clickable headline with its publish time, newest first. Free, keyless RSS sources: crypto press (CoinDesk, Cointelegraph, Decrypt), broad markets/macro (CNBC, Nasdaq), or \u2014 source "stocks" \u2014 per-company headlines (via Google News) scoped to the specific tickers in `symbols`. IMPORTANT: news feeds are CORS-blocked, so this frame reads them through the zframes runtime\'s data proxy (it ships with `zframes serve` / `vite dev`); on a fully static host with no runtime it shows an empty state.',
   capabilities: ["news"],
@@ -598,6 +973,8 @@ var newsFeedMeta = defineFrameMeta({
 });
 var dexVolumeTreemapMeta = defineFrameMeta({
   name: "dex-volume-treemap",
+  category: "crypto",
+  iconUrl: widgetIcon("dex-volume-treemap"),
   layout: { w: 6, h: 4, minW: 3, minH: 3 },
   description: "Treemap of decentralized-exchange (DEX) protocols sized by trailing-24h trading volume, tiles colored green/red by 1-day change. Data from DeFiLlama. One-glance read on where on-chain trading flow is concentrated right now.",
   capabilities: ["dex-volume"],
@@ -608,6 +985,8 @@ var dexVolumeTreemapMeta = defineFrameMeta({
 });
 var dexVolumeChartMeta = defineFrameMeta({
   name: "dex-volume-chart",
+  category: "crypto",
+  iconUrl: widgetIcon("dex-volume-chart"),
   layout: { w: 6, h: 3, minW: 3, minH: 2 },
   description: "Multi-series line chart of daily DEX trading volume for several protocols over a lookback window \u2014 compare how Uniswap, PancakeSwap, Aerodrome etc. trend against each other. Data from DeFiLlama (daily granularity).",
   capabilities: ["dex-volume"],
@@ -621,6 +1000,8 @@ var dexVolumeChartMeta = defineFrameMeta({
 });
 var protocolTvlTreemapMeta = defineFrameMeta({
   name: "protocol-tvl-treemap",
+  category: "crypto",
+  iconUrl: widgetIcon("protocol-tvl-treemap"),
   layout: { w: 6, h: 4, minW: 3, minH: 3 },
   description: "Treemap of DeFi protocols sized by current total value locked (TVL), tiles colored green/red by 1-day change. Data from DeFiLlama. Unlike tvl-treemap (which groups by blockchain), this ranks individual protocols (Lido, Aave, EigenLayer\u2026).",
   capabilities: ["protocol-tvl"],
@@ -631,6 +1012,8 @@ var protocolTvlTreemapMeta = defineFrameMeta({
 });
 var protocolTvlChartMeta = defineFrameMeta({
   name: "protocol-tvl-chart",
+  category: "crypto",
+  iconUrl: widgetIcon("protocol-tvl-chart"),
   layout: { w: 6, h: 3, minW: 3, minH: 2 },
   description: "Multi-series line chart of total value locked (TVL) for several DeFi protocols over a lookback window. Data from DeFiLlama (daily granularity).",
   capabilities: ["protocol-tvl"],
@@ -644,6 +1027,8 @@ var protocolTvlChartMeta = defineFrameMeta({
 });
 var protocolFeesTreemapMeta = defineFrameMeta({
   name: "protocol-fees-treemap",
+  category: "crypto",
+  iconUrl: widgetIcon("protocol-fees-treemap"),
   layout: { w: 6, h: 4, minW: 3, minH: 3 },
   description: "Treemap of protocols sized by the fees they generated in the last 24h, tiles colored green/red by 1-day change. Data from DeFiLlama. Shows where on-chain users are actually paying for blockspace and services right now.",
   capabilities: ["protocol-fees"],
@@ -654,18 +1039,22 @@ var protocolFeesTreemapMeta = defineFrameMeta({
 });
 var marketCapTreemapMeta = defineFrameMeta({
   name: "market-cap-treemap",
+  category: "crypto",
+  iconUrl: widgetIcon("market-cap-treemap"),
   layout: { w: 6, h: 4, minW: 3, minH: 3 },
   description: "Treemap of the largest cryptocurrencies sized by market capitalisation, tiles colored green/red by 24h price change. Data from CoinGecko (free tier). A heat-map of the whole crypto market at a glance.",
   capabilities: ["coin-markets"],
   source: SOURCES.coingecko,
   schema: z3.object({
-    topN: z3.number().int().min(5).max(50).default(20).describe(
+    topN: z3.number().int().min(5).max(50).default(12).describe(
       "How many of the largest coins by market cap to show (up to 50)."
     )
   })
 });
 var openInterestMeta = defineFrameMeta({
   name: "open-interest",
+  category: "derivatives",
+  iconUrl: widgetIcon("open-interest"),
   layout: { w: 4, h: 3, minW: 3, minH: 2 },
   description: 'Live open interest across a watchlist of Hyperliquid perps \u2014 each symbol is a horizontal bar sized by USD notional, largest first, refreshed on a ~30s poll. Single-venue (Hyperliquid only), so read it as a relative gauge across your symbols, not a market-wide total. Stocks (HIP-3, e.g. "xyz:TSLA") and crypto both work.',
   capabilities: ["open-interest"],
@@ -678,6 +1067,8 @@ var openInterestMeta = defineFrameMeta({
 });
 var snakeMeta = defineFrameMeta({
   name: "snake",
+  category: "games",
+  iconUrl: widgetIcon("snake"),
   layout: { w: 4, h: 4, minW: 3, minH: 3 },
   description: "Classic snake game on canvas \u2014 steer with the arrow keys (or swipe), eat dots to grow, avoid the walls and your own tail. High score persists locally. For when the market is flat. Needs no data provider.",
   capabilities: [],
@@ -685,6 +1076,8 @@ var snakeMeta = defineFrameMeta({
 });
 var flappyBirdMeta = defineFrameMeta({
   name: "flappy-bird",
+  category: "games",
+  iconUrl: widgetIcon("flappy-bird"),
   layout: { w: 4, h: 4, minW: 3, minH: 3 },
   description: "Flappy-bird style game on canvas \u2014 tap or press SPACE to flap through the gaps between pipes. High score persists locally. Needs no data provider.",
   capabilities: [],
@@ -692,6 +1085,8 @@ var flappyBirdMeta = defineFrameMeta({
 });
 var videoMeta = defineFrameMeta({
   name: "video",
+  category: "layout",
+  iconUrl: widgetIcon("video"),
   layout: { w: 4, h: 3, minW: 2, minH: 2 },
   description: "Embeds a video from a YouTube or Vimeo link (or any direct embed URL) as an iframe \u2014 a livestream, a market-news clip, a focus playlist. Needs no data provider.",
   capabilities: [],
@@ -704,6 +1099,8 @@ var videoMeta = defineFrameMeta({
 });
 var drawdyMeta = defineFrameMeta({
   name: "drawdy",
+  category: "layout",
+  iconUrl: widgetIcon("drawdy"),
   layout: { w: 8, h: 6, minW: 2, minH: 2 },
   description: "Embeds drawdy.io as an interactive whiteboard canvas. No configuration needed.",
   capabilities: [],
@@ -711,6 +1108,8 @@ var drawdyMeta = defineFrameMeta({
 });
 var countdownMeta = defineFrameMeta({
   name: "countdown",
+  category: "tools",
+  iconUrl: widgetIcon("countdown"),
   layout: { w: 3, h: 2, minW: 2, minH: 1 },
   description: "Live countdown to a target date and time \u2014 FOMC decisions, CPI prints, options expiry, earnings, a token unlock, the next market open. Counts down in days / hours / minutes / seconds, ticking every second, and flips to a 'reached' state once the moment passes. Needs no data provider.",
   capabilities: [],
@@ -726,6 +1125,8 @@ var countdownMeta = defineFrameMeta({
 });
 var linkGridMeta = defineFrameMeta({
   name: "link-grid",
+  category: "tools",
+  iconUrl: widgetIcon("link-grid"),
   layout: { w: 3, h: 2, minW: 2, minH: 1 },
   description: "A grid of quick-launch tiles linking to your favourite sites \u2014 TradingView, exchanges, news, docs, your own dashboards. Each tile opens in a new tab and shows the destination site's favicon by default (fetched keyless from a public favicon service), with an optional per-link icon override and a first-letter fallback. Needs no data provider.",
   capabilities: [],
@@ -755,6 +1156,8 @@ var linkGridMeta = defineFrameMeta({
 });
 var calculatorMeta = defineFrameMeta({
   name: "calculator",
+  category: "tools",
+  iconUrl: widgetIcon("calculator"),
   layout: { w: 3, h: 3, minW: 2, minH: 2 },
   description: "Position-size & risk calculator. Enter account size, risk-per-trade %, entry and stop price; it computes the dollars at risk, the per-unit risk, the position size (units) that respects that risk budget, the resulting position value, and whether the setup is long or short. All math runs client-side \u2014 no data provider. Inputs are editable live; the configured values are the starting point.",
   capabilities: [],
@@ -770,6 +1173,8 @@ var calculatorMeta = defineFrameMeta({
 });
 var quoteMeta = defineFrameMeta({
   name: "quote",
+  category: "layout",
+  iconUrl: widgetIcon("quote"),
   layout: { w: 4, h: 2, minW: 2, minH: 1 },
   description: 'Displays a market or trading quote, centered \u2014 set one or rotate through several. A calm bit of wall-art for the dashboard: trading maxims, reminders of your own rules, mantras. Write any attribution into the text itself (e.g. "\u2026 \u2014 Buffett"). Needs no data provider.',
   capabilities: [],
@@ -788,6 +1193,8 @@ var quoteMeta = defineFrameMeta({
 });
 var dividerMeta = defineFrameMeta({
   name: "divider",
+  category: "layout",
+  iconUrl: widgetIcon("divider"),
   layout: { w: 12, h: 1, minW: 1, minH: 1 },
   description: "A plain rule that separates regions of the dashboard, with an optional centered label. Renders chrome-less (no card) \u2014 lighter than a heading. Use a horizontal divider full-width between stacked zones, or set orientation to vertical for a 1-column-wide column separator. Needs no data provider.",
   capabilities: [],
@@ -802,8 +1209,228 @@ var dividerMeta = defineFrameMeta({
     style: z3.enum(["solid", "dashed", "dotted"]).default("solid").describe("Line style.")
   })
 });
+var diceMeta = defineFrameMeta({
+  name: "dice",
+  category: "tools",
+  iconUrl: widgetIcon("dice"),
+  layout: { w: 2, h: 2, minW: 1, minH: 1 },
+  description: "A click-to-decide widget \u2014 a random decision-maker with no data provider. Flip a coin (heads/tails), roll a die (1\u20136), or pick at random from your own list of options. Click the surface to re-roll. Use it to break a tie, pick what to trade, or settle any small decision.",
+  capabilities: [],
+  schema: z3.object({
+    mode: z3.enum(["coin", "dice", "list"]).default("coin").describe(
+      "coin = heads/tails, dice = 1\u20136, list = random pick from options."
+    ),
+    options: z3.array(z3.string()).default(["Yes", "No"]).describe("Choices used in list mode."),
+    label: z3.string().default("").describe("Optional caption, e.g. the question being decided.")
+  })
+});
+var riskRewardMeta = defineFrameMeta({
+  name: "risk-reward",
+  category: "tools",
+  iconUrl: widgetIcon("risk-reward"),
+  layout: { w: 3, h: 3, minW: 2, minH: 2 },
+  description: "Risk:reward planner. Enter entry, stop-loss and profit-target prices; it computes the per-unit risk and reward, their percentages of entry, and the resulting R:R ratio, shown large above a two-segment bar (red risk leg vs green reward leg, sized to scale). Pure client-side math \u2014 no data provider. Complements the calculator frame by adding the target/reward leg the position sizer leaves out.",
+  capabilities: [],
+  schema: z3.object({
+    entry: z3.number().default(100).describe("Planned entry price."),
+    stop: z3.number().default(95).describe("Stop-loss price."),
+    target: z3.number().default(115).describe("Profit target price."),
+    direction: z3.enum(["long", "short"]).default("long").describe(
+      "Trade direction. Long expects stop < entry < target; short expects target < entry < stop \u2014 used for labels and to flag a mismatched setup."
+    ),
+    label: z3.string().default("").describe("Optional caption.")
+  })
+});
+var marqueeMeta = defineFrameMeta({
+  name: "marquee",
+  category: "layout",
+  iconUrl: widgetIcon("marquee"),
+  layout: { w: 6, h: 1, minW: 2, minH: 1 },
+  description: "A chrome-less scrolling banner that glides custom text continuously right-to-left across the frame (think stadium ticker / news crawl). Renders with no card \u2014 it fills the whole frame. Use for a slogan, a reminder, or a hype line. Needs no data provider.",
+  capabilities: [],
+  chrome: "bare",
+  schema: z3.object({
+    text: z3.string().default("LFG").describe("The text that scrolls across the banner."),
+    speed: z3.enum(["slow", "normal", "fast"]).default("normal").describe("Scroll speed."),
+    accent: z3.boolean().default(true).describe("Tint the text with the dashboard accent color.")
+  })
+});
+var stopwatchMeta = defineFrameMeta({
+  name: "stopwatch",
+  layout: { w: 3, h: 2, minW: 2, minH: 1 },
+  category: "tools",
+  iconUrl: widgetIcon("stopwatch"),
+  description: "A count-up stopwatch \u2014 time-in-trade, a focus session, how long a setup has been live. Start / Pause / Reset, ticking up in H:MM:SS, and it persists across reloads (the running state is saved into the dashboard, so it keeps counting where it left off). Runs entirely client-side \u2014 needs no data provider.",
+  capabilities: [],
+  schema: z3.object({
+    label: z3.string().default("Session").describe("Caption above the timer."),
+    startedAt: z3.number().default(0).describe(
+      "Epoch ms when the timer was last started; 0 = paused. Persisted automatically by the frame."
+    ),
+    accumulatedMs: z3.number().default(0).describe(
+      "Milliseconds banked before the current run. Persisted automatically by the frame."
+    )
+  })
+});
+var sessionProgressMeta = defineFrameMeta({
+  name: "session-progress",
+  category: "tools",
+  iconUrl: widgetIcon("session-progress"),
+  layout: { w: 3, h: 2, minW: 2, minH: 1 },
+  description: "A horizontal progress bar showing how far through today's trading session an exchange is \u2014 fills from open to close with a percent readout, and a 'closes in \u2026' / 'opens in \u2026' countdown. Pick any exchange code (NYSE, NASDAQ, LSE, TSX, B3, \u2026); sessions are computed client-side from the exchange's timezone and hours, so it needs no data provider.",
+  capabilities: [],
+  schema: z3.object({
+    exchange: z3.string().default("NYSE").describe("Exchange code: NYSE, NASDAQ, LSE, TSX, B3, \u2026"),
+    label: z3.string().default("").describe("Optional caption shown by the exchange code."),
+    showCountdown: z3.boolean().default(true).describe("Show the time-to-open / time-to-close countdown.")
+  })
+});
+var holidayCalendarMeta = defineFrameMeta({
+  name: "holiday-calendar",
+  category: "tools",
+  iconUrl: widgetIcon("holiday-calendar"),
+  layout: { w: 3, h: 4, minW: 2, minH: 2 },
+  description: "Upcoming market holidays (full closures) for a chosen exchange \u2014 the next few dates with their weekday and a countdown ('in 9d'). Pick any exchange code (NYSE, NASDAQ, LSE, TSX, B3, \u2026); dates come from a bundled holiday table and are computed client-side, so it needs no data provider. Note: the bundled table currently covers 2026.",
+  capabilities: [],
+  schema: z3.object({
+    exchange: z3.string().default("NYSE").describe("Exchange code: NYSE, NASDAQ, LSE, TSX, B3, \u2026"),
+    count: z3.number().int().min(1).max(20).default(5).describe("How many upcoming holidays to list."),
+    label: z3.string().default("").describe("Optional caption shown above the list.")
+  })
+});
+var dayMeterMeta = defineFrameMeta({
+  name: "day-meter",
+  category: "tools",
+  iconUrl: widgetIcon("day-meter"),
+  layout: { w: 4, h: 2, minW: 2, minH: 1 },
+  description: "A strip of the current week's days for a chosen exchange \u2014 today highlighted, market holidays flagged in amber, and (optionally) non-trading days greyed. Computed client-side from the exchange's trading days + a bundled holiday table; needs no data provider.",
+  capabilities: [],
+  schema: z3.object({
+    exchange: z3.string().default("NYSE").describe("Exchange code: NYSE, NASDAQ, LSE, TSX, B3, \u2026"),
+    weekdaysOnly: z3.boolean().default(true).describe(
+      "Show only the exchange's trading days; off shows the full 7-day week with weekends greyed."
+    ),
+    label: z3.string().default("").describe("Optional caption shown by the strip.")
+  })
+});
+var returnsProjectorMeta = defineFrameMeta({
+  name: "returns-projector",
+  category: "tools",
+  iconUrl: widgetIcon("returns-projector"),
+  layout: { w: 3, h: 4, minW: 2, minH: 3 },
+  description: "A compound-growth projector \u2014 enter a starting principal, a percent return per period, the number of periods, and an optional per-period contribution; it charts the projected balance curve and shows the ending value and total gain. Pure client-side math, no data provider; complements the position-size/risk `calculator`.",
+  capabilities: [],
+  schema: z3.object({
+    principal: z3.number().default(1e3).describe("Starting balance."),
+    ratePct: z3.number().default(5).describe("Return per period, in percent (e.g. 5 = 5%)."),
+    periods: z3.number().int().min(1).max(600).default(12).describe("Number of compounding periods to project."),
+    contribution: z3.number().default(0).describe("Amount added at the end of each period."),
+    label: z3.string().default("").describe("Optional caption.")
+  })
+});
+var breakevenMeta = defineFrameMeta({
+  name: "breakeven",
+  category: "tools",
+  iconUrl: widgetIcon("breakeven"),
+  layout: { w: 3, h: 4, minW: 2, minH: 2 },
+  description: "A break-even / average-cost calculator \u2014 add your fills (price + size) and it computes the size-weighted average entry; set an optional current price to see the unrealized P&L %. Pure client-side math, no data provider.",
+  capabilities: [],
+  schema: z3.object({
+    fills: z3.array(
+      z3.object({
+        price: z3.number().describe("Fill price."),
+        size: z3.number().describe("Fill size, in units.")
+      })
+    ).default([{ price: 100, size: 1 }]).describe(
+      "Your entry fills; their size-weighted average is the break-even."
+    ),
+    currentPrice: z3.number().default(0).describe(
+      "Optional current price; greater than 0 shows the unrealized P&L %."
+    ),
+    label: z3.string().default("").describe("Optional caption.")
+  })
+});
+var checklistMeta = defineFrameMeta({
+  name: "checklist",
+  category: "tools",
+  iconUrl: widgetIcon("checklist"),
+  layout: { w: 3, h: 3, minW: 2, minH: 2 },
+  description: "A tickable checklist \u2014 a pre-trade routine, a daily ritual, anything. Tap items to check them off; the checked state persists across reloads (saved into the dashboard). Client-side only, no data provider.",
+  capabilities: [],
+  schema: z3.object({
+    title: z3.string().default("Pre-trade checklist").describe("Heading shown above the list."),
+    items: z3.array(z3.string()).default([
+      "Trend & bias aligned",
+      "Stop level set",
+      "Risk sized correctly"
+    ]).describe("The checklist items, top to bottom."),
+    checked: z3.array(z3.boolean()).default([]).describe(
+      "Per-item checked state (by index); persisted automatically by the frame."
+    )
+  })
+});
+var pomodoroMeta = defineFrameMeta({
+  name: "pomodoro",
+  category: "tools",
+  iconUrl: widgetIcon("pomodoro"),
+  layout: { w: 3, h: 3, minW: 2, minH: 2 },
+  description: "A Pomodoro focus timer \u2014 alternating work and break intervals with Start / Pause / Reset and a cycle counter, counting down in MM:SS. Runs entirely client-side with no data provider; timer state is in-session (not persisted).",
+  capabilities: [],
+  schema: z3.object({
+    workMin: z3.number().min(1).max(180).default(25).describe("Work interval length, in minutes."),
+    breakMin: z3.number().min(1).max(120).default(5).describe("Break interval length, in minutes."),
+    cycles: z3.number().int().min(1).max(20).default(4).describe("Work/break cycles before the counter loops."),
+    label: z3.string().default("").describe("Optional caption.")
+  })
+});
+var rulesCardMeta = defineFrameMeta({
+  name: "rules-card",
+  category: "layout",
+  iconUrl: widgetIcon("rules-card"),
+  layout: { w: 3, h: 3, minW: 2, minH: 2 },
+  description: "A pinned, auto-numbered list of your trading rules (or any principles) \u2014 always fully visible, unlike the rotating `quote` frame. Static text, client-side, no data provider.",
+  capabilities: [],
+  schema: z3.object({
+    title: z3.string().default("My rules").describe("Heading shown above the list."),
+    rules: z3.array(z3.string()).default([
+      "Cut losers fast, let winners run",
+      "No trade without a stop",
+      "One setup at a time"
+    ]).describe("The rules, in order; rendered as a numbered list.")
+  })
+});
+var breathingMeta = defineFrameMeta({
+  name: "breathing",
+  category: "layout",
+  iconUrl: widgetIcon("breathing"),
+  chrome: "bare",
+  layout: { w: 2, h: 2, minW: 1, minH: 1 },
+  description: "A chrome-less breathing pacer \u2014 a circle that expands and contracts through configurable inhale / hold / exhale / hold phases to steady your breathing between trades. Renders with no card; client-side only, no data provider.",
+  capabilities: [],
+  schema: z3.object({
+    inhale: z3.number().min(1).max(60).default(4).describe("Inhale seconds."),
+    hold: z3.number().min(0).max(60).default(4).describe("Hold-after-inhale seconds."),
+    exhale: z3.number().min(1).max(60).default(4).describe("Exhale seconds."),
+    holdAfter: z3.number().min(0).max(60).default(4).describe("Hold-after-exhale seconds.")
+  })
+});
+var spotifyEmbedMeta = defineFrameMeta({
+  name: "spotify-embed",
+  category: "layout",
+  iconUrl: widgetIcon("spotify-embed"),
+  layout: { w: 3, h: 4, minW: 2, minH: 2 },
+  description: "Embeds a Spotify track, album, playlist, artist, or show from its public open.spotify.com share link (same embed approach as the `video` frame), using Spotify's official keyless iframe player. Needs an internet connection to play.",
+  capabilities: [],
+  schema: z3.object({
+    url: z3.string().default("https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M").describe(
+      "A Spotify share URL (open.spotify.com/track|album|playlist|artist/\u2026)."
+    ),
+    compact: z3.boolean().default(false).describe("Use Spotify's compact (single-row) player height.")
+  })
+});
 var btcFeesMeta = defineFrameMeta({
   name: "btc-fees",
+  category: "bitcoin",
   iconUrl: widgetIcon("btc-fees"),
   layout: { w: 3, h: 2, minW: 2, minH: 2 },
   description: "Recommended Bitcoin on-chain fee rates (sat/vB) from mempool.space \u2014 the next-block ('fastest'), ~30-minute, ~1-hour, economy, and minimum tiers, as a compact gauge. Live mempool data, keyless; updates every ~30s.",
@@ -817,6 +1444,7 @@ var btcFeesMeta = defineFrameMeta({
 });
 var btcMempoolMeta = defineFrameMeta({
   name: "btc-mempool",
+  category: "bitcoin",
   iconUrl: widgetIcon("btc-mempool"),
   layout: { w: 5, h: 3, minW: 3, minH: 2 },
   description: "Bitcoin mempool congestion at a glance \u2014 unconfirmed transaction count, total pending vsize, and a row of projected ('template') blocks the network will likely mine next, each labelled with its median fee rate (sat/vB) and tx count. Live mempool data from mempool.space, keyless.",
@@ -830,6 +1458,7 @@ var btcMempoolMeta = defineFrameMeta({
 });
 var btcBlocksMeta = defineFrameMeta({
   name: "btc-blocks",
+  category: "bitcoin",
   iconUrl: widgetIcon("btc-blocks"),
   layout: { w: 5, h: 4, minW: 3, minH: 3 },
   description: "Feed of the most recently mined Bitcoin blocks \u2014 each row shows the height, how long ago it was mined, transaction count, the mining pool that found it, total fees (BTC), and size. Live data from mempool.space, keyless; newest first.",
@@ -841,6 +1470,7 @@ var btcBlocksMeta = defineFrameMeta({
 });
 var btcHashrateMeta = defineFrameMeta({
   name: "btc-hashrate",
+  category: "bitcoin",
   iconUrl: widgetIcon("btc-hashrate"),
   layout: { w: 6, h: 3, minW: 3, minH: 2 },
   description: "Bitcoin network hashrate over time as a line chart, with the current hashrate (EH/s) and difficulty as headline figures. Shows the long-run security trend of the network. Data from mempool.space (daily granularity), keyless.",
@@ -852,6 +1482,7 @@ var btcHashrateMeta = defineFrameMeta({
 });
 var btcDifficultyMeta = defineFrameMeta({
   name: "btc-difficulty",
+  category: "bitcoin",
   iconUrl: widgetIcon("btc-difficulty"),
   layout: { w: 4, h: 3, minW: 3, minH: 2 },
   description: "Countdown to the next Bitcoin difficulty adjustment \u2014 a progress bar through the current 2016-block epoch, the estimated change (+ = mining gets harder), blocks remaining, and the estimated retarget date. Also shows the previous adjustment. Data from mempool.space, keyless.",
@@ -865,6 +1496,7 @@ var btcDifficultyMeta = defineFrameMeta({
 });
 var miningPoolsMeta = defineFrameMeta({
   name: "mining-pools",
+  category: "bitcoin",
   iconUrl: widgetIcon("mining-pools"),
   layout: { w: 6, h: 4, minW: 3, minH: 3 },
   description: "Treemap of Bitcoin mining-pool dominance over a window \u2014 each tile is a pool sized by the share of blocks it mined, so you can see how concentrated hashpower is right now (Foundry, AntPool, ViaBTC\u2026). Data from mempool.space, keyless.",
@@ -879,6 +1511,7 @@ var miningPoolsMeta = defineFrameMeta({
 });
 var lightningStatsMeta = defineFrameMeta({
   name: "lightning-stats",
+  category: "bitcoin",
   iconUrl: widgetIcon("lightning-stats"),
   layout: { w: 4, h: 3, minW: 3, minH: 2 },
   description: "Bitcoin Lightning Network snapshot \u2014 public node count, channel count, and total network capacity (BTC), with a day-over-day delta and the Tor/clearnet node split. Data from mempool.space, keyless; updates roughly daily.",
@@ -892,6 +1525,7 @@ var lightningStatsMeta = defineFrameMeta({
 });
 var optionsPutCallMeta = defineFrameMeta({
   name: "options-put-call",
+  category: "derivatives",
   iconUrl: widgetIcon("options-put-call"),
   layout: { w: 4, h: 3, minW: 3, minH: 2 },
   description: "Deribit options put/call ratio for BTC or ETH \u2014 the headline ratio (by open interest or 24h volume), a call-vs-put open-interest split bar, and the open-interest-weighted average implied volatility. A ratio above 1 means puts outweigh calls (defensive positioning). Keyless Deribit market data.",
@@ -908,6 +1542,7 @@ var optionsPutCallMeta = defineFrameMeta({
 });
 var optionsIvMeta = defineFrameMeta({
   name: "options-iv",
+  category: "derivatives",
   iconUrl: widgetIcon("options-iv"),
   layout: { w: 6, h: 3, minW: 3, minH: 2 },
   description: "Deribit DVOL implied-volatility index for BTC or ETH over time \u2014 the crypto equivalent of the VIX, as a line chart with the current reading and its change over the window. Rising DVOL = the market is pricing bigger expected swings. Keyless Deribit market data.",
@@ -920,6 +1555,7 @@ var optionsIvMeta = defineFrameMeta({
 });
 var optionsOiStrikeMeta = defineFrameMeta({
   name: "options-oi-strike",
+  category: "derivatives",
   iconUrl: widgetIcon("options-oi-strike"),
   layout: { w: 6, h: 4, minW: 4, minH: 3 },
   description: "Open interest by strike for the nearest Deribit options expiry (BTC or ETH) \u2014 a grouped histogram of call vs put open interest across strikes, with the current spot marked. Surfaces the strike 'walls' where positioning is concentrated. Keyless Deribit market data.",
@@ -934,6 +1570,7 @@ var optionsOiStrikeMeta = defineFrameMeta({
 });
 var coinMoversMeta = defineFrameMeta({
   name: "coin-movers",
+  category: "markets",
   iconUrl: widgetIcon("coin-movers"),
   layout: { w: 5, h: 4, minW: 3, minH: 3 },
   description: "Broad-market crypto gainers and losers across the top ~300 coins by market cap, over a selectable window (1h / 24h / 7d / 30d) \u2014 the biggest movers side by side with price and % change. Unlike a top-coins heatmap, this surfaces mid- and small-caps that ripped or dumped, not just the megacaps. Keyless data from Coinpaprika. Crypto only.",
@@ -951,7 +1588,9 @@ var coinMoversMeta = defineFrameMeta({
 });
 var frameMetas = [
   newsFeedMeta,
-  allocationMeta,
+  portfolioValueMeta,
+  portfolioAllocationMeta,
+  portfolioHoldingsMeta,
   bitcoinDominanceMeta,
   clockMeta,
   dailyAnalysisMeta,
@@ -975,6 +1614,7 @@ var frameMetas = [
   priceLivelineMeta,
   priceTickerMeta,
   ratesBoardMeta,
+  fxBoardMeta,
   shortVolumeMeta,
   topMoversMeta,
   tvlTreemapMeta,
@@ -1007,15 +1647,87 @@ var frameMetas = [
   optionsOiStrikeMeta,
   coinMoversMeta
 ];
+var allFrameMetas = [
+  ...frameMetas,
+  breakevenMeta,
+  breathingMeta,
+  checklistMeta,
+  dayMeterMeta,
+  diceMeta,
+  holidayCalendarMeta,
+  journalLogMeta,
+  journalOpenMeta,
+  journalResultsMeta,
+  journalScoreMeta,
+  marqueeMeta,
+  pomodoroMeta,
+  returnsProjectorMeta,
+  riskRewardMeta,
+  rulesCardMeta,
+  sessionProgressMeta,
+  spotifyEmbedMeta,
+  stopwatchMeta
+];
+
+// src/dashboards.ts
+import { existsSync } from "fs";
+function list() {
+  const entries = listDashboards();
+  if (entries.length === 0) {
+    console.log(`no dashboards in your store yet (${dashboardsDir()})`);
+    console.log("  create one: npx --yes zframes@latest init <name>");
+    return 0;
+  }
+  console.log(`dashboards in ${dashboardsDir()}:`);
+  for (const e of entries) {
+    const mark = e.isDefault ? "*" : " ";
+    const title = e.title ? `  \u2014 ${e.title}` : "";
+    console.log(`  ${mark} ${e.name}${title}`);
+  }
+  if (entries.some((e) => e.isDefault)) {
+    console.log(
+      "\n  * = default (served when you run `zframes serve` with no name)"
+    );
+  } else {
+    console.log("\n  no default set \u2014 `zframes use <name>` to pick one.");
+  }
+  return 0;
+}
+function use(args) {
+  const name = args.find((a) => !a.startsWith("-"));
+  if (!name) {
+    console.error("usage: zframes use <name>");
+    return 1;
+  }
+  if (!isValidName(name)) {
+    console.error(
+      `\u2717 "${name}" is not a valid dashboard name (lowercase letters, digits, "-", "_")`
+    );
+    return 1;
+  }
+  if (!existsSync(dashboardPath(name))) {
+    console.error(
+      `\u2717 no dashboard named "${name}" in your store (${dashboardsDir()})`
+    );
+    console.error(
+      `  create it with \`zframes init ${name}\`, or run \`zframes list\` to see what's there.`
+    );
+    return 1;
+  }
+  setDefault(name);
+  console.log(`\u2713 default dashboard is now "${name}"`);
+  return 0;
+}
 
 // src/init.ts
-import { existsSync, mkdirSync, statSync, writeFileSync } from "fs";
-import { dirname, join, resolve } from "path";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, statSync as statSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname, resolve as resolve2 } from "path";
 function parseArgs(args) {
   let target = "dashboard.json";
   let title = "my dashboard";
   let author = "";
   let force = false;
+  let makeDefault = false;
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === "--title" || a === "-t") {
@@ -1028,6 +1740,8 @@ function parseArgs(args) {
       author = a.slice("--author=".length);
     } else if (a === "--force" || a === "-f") {
       force = true;
+    } else if (a === "--default") {
+      makeDefault = true;
     } else if (!a.startsWith("-")) {
       target = a;
     } else {
@@ -1035,12 +1749,14 @@ function parseArgs(args) {
     }
   }
   if (!title.trim()) return { error: "--title cannot be empty" };
-  return { target, title, author, force };
+  return { target, title, author, force, makeDefault };
 }
 function resolveDest(target) {
-  const abs = resolve(process.cwd(), target);
-  if (abs.toLowerCase().endsWith(".json")) return abs;
-  return resolve(abs, "dashboard.json");
+  const c = classifyTarget(target, process.cwd());
+  if ("error" in c) return c;
+  if (c.kind === "store") return { dest: c.file, name: c.name };
+  if (c.file.toLowerCase().endsWith(".json")) return { dest: c.file };
+  return { dest: resolve2(c.file, "dashboard.json") };
 }
 function skeleton(title, author) {
   return {
@@ -1053,7 +1769,19 @@ function skeleton(title, author) {
       projectId: "YrTzGatwjK7EoFpCSfgZ",
       opacity: 1
     },
-    theme: { accentHue: 242, accentSat: 90 },
+    theme: {
+      accentHue: 242,
+      accentSat: 90,
+      baseHue: 233,
+      baseSat: 20,
+      upColor: "#3fd08f",
+      downColor: "#ff6b81"
+    },
+    typography: {
+      fontFamily: "sans",
+      numericStyle: "proportional",
+      scale: 1
+    },
     appearance: {
       radius: 18,
       borderStrength: 0.22,
@@ -1069,12 +1797,17 @@ function init(args) {
   if ("error" in parsed) {
     console.error(`\u2717 ${parsed.error}`);
     console.error(
-      "usage: zframes init [dir|file.json] [--title <t>] [--author <a>] [--force]"
+      "usage: zframes init [name|dir|file.json] [--title <t>] [--author <a>] [--default] [--force]"
     );
     return 1;
   }
-  const dest = resolveDest(parsed.target);
-  if (existsSync(dest)) {
+  const resolved = resolveDest(parsed.target);
+  if ("error" in resolved) {
+    console.error(`\u2717 ${resolved.error}`);
+    return 1;
+  }
+  const { dest, name } = resolved;
+  if (existsSync2(dest)) {
     if (!parsed.force) {
       console.error(`\u2717 ${dest} already exists`);
       console.error(
@@ -1082,7 +1815,7 @@ function init(args) {
       );
       return 1;
     }
-    if (!statSync(dest).isFile()) {
+    if (!statSync2(dest).isFile()) {
       console.error(`\u2717 ${dest} exists but is not a file`);
       return 1;
     }
@@ -1096,15 +1829,26 @@ function init(args) {
     return 1;
   }
   try {
-    mkdirSync(dirname(dest), { recursive: true });
-    writeFileSync(dest, `${JSON.stringify(spec, null, 2)}
+    if (name) ensureHome();
+    mkdirSync2(dirname(dest), { recursive: true });
+    writeFileSync2(dest, `${JSON.stringify(spec, null, 2)}
 `);
   } catch (error) {
     console.error(`\u2717 could not write ${dest}: ${error.message}`);
     return 1;
   }
-  const hint = parsed.target.toLowerCase().endsWith(".json") ? parsed.target : join(parsed.target, "dashboard.json");
+  let madeDefault = false;
+  if (name && (parsed.makeDefault || getDefault() === null)) {
+    setDefault(name);
+    madeDefault = true;
+  }
+  const hint = name ?? dest;
   console.log(`\u2713 wrote a bare dashboard to ${dest}`);
+  if (name) {
+    console.log(
+      `  it's in your store (${dashboardsDir()})${madeDefault ? " and is now your default" : ""}.`
+    );
+  }
   console.log("  next: read the catalogue, add frames, then lint + serve:");
   console.log("    npx --yes zframes@latest catalogue");
   console.log(`    npx --yes zframes@latest lint ${hint}`);
@@ -1148,6 +1892,12 @@ function lintSpec(spec) {
         frameId: instance.id,
         message: `overflows the grid: x(${instance.position.x}) + w(${instance.position.w}) > ${spec.grid.columns} columns`
       });
+    const horizontal = instance.layouts?.["flow-horizontal"];
+    if (horizontal && horizontal.y + horizontal.h > spec.grid.rows)
+      issues.push({
+        frameId: instance.id,
+        message: `horizontal layout overflows: y(${horizontal.y}) + h(${horizontal.h}) > ${spec.grid.rows} rows`
+      });
   }
   for (let i = 0; i < spec.frames.length; i++) {
     for (let j = i + 1; j < spec.frames.length; j++) {
@@ -1165,9 +1915,11 @@ function lintSpec(spec) {
 }
 
 // src/serve.ts
-import { existsSync as existsSync2, statSync as statSync2 } from "fs";
-import { createServer } from "http";
-import { join as join3, resolve as resolve2 } from "path";
+import { existsSync as existsSync3 } from "fs";
+import {
+  createServer
+} from "http";
+import { join as join3, resolve as resolve3 } from "path";
 import { fileURLToPath } from "url";
 import sirv from "sirv";
 
@@ -1177,7 +1929,11 @@ import { readFile, writeFile } from "fs/promises";
 // ../core/src/routes.ts
 var DASHBOARD_READ_ROUTE = "/__zframes/dashboard.json";
 var DASHBOARD_WRITE_ROUTE = "/__zframes/dashboard";
+var DASHBOARD_LIST_ROUTE = "/__zframes/dashboards";
+var DASHBOARD_SWITCH_ROUTE = "/__zframes/switch";
 var DASHBOARD_PROXY_ROUTE = "/__zframes/proxy";
+var ACCOUNT_PORTFOLIO_ROUTE = "/__zframes/account/portfolio";
+var ACCOUNT_CREDENTIALS_ROUTE = "/__zframes/account/credentials";
 var AGENTS_LIST_ROUTE = "/__zframes/agents";
 var ASK_ROUTE = "/__zframes/ask";
 
@@ -1193,6 +1949,7 @@ var PROXY_ALLOW_HOSTS = /* @__PURE__ */ new Set([
   "www.nyse.com",
   "markets.newyorkfed.org",
   "api.fiscaldata.treasury.gov",
+  "home.treasury.gov",
   "api.bls.gov",
   "cdn.finra.org",
   // News-outlet RSS feeds (CORS-blocked, so the news-feed frame reads them
@@ -1244,8 +2001,8 @@ function handleSpecWrite(req, res, absFile) {
   req.on("end", async () => {
     if (aborted) return;
     try {
-      const json = JSON.parse(body);
-      await writeFile(absFile, `${JSON.stringify(json, null, 2)}
+      const json2 = JSON.parse(body);
+      await writeFile(absFile, `${JSON.stringify(json2, null, 2)}
 `, "utf8");
       res.statusCode = 200;
       res.setHeader("content-type", "application/json");
@@ -1318,14 +2075,59 @@ import { tmpdir } from "os";
 import { dirname as dirname2, join as join2 } from "path";
 var MAX_BODY_BYTES2 = 64e3;
 var RUN_TIMEOUT_MS = 12e4;
+var MAX_CONTEXT_CHARS = 12e3;
+var MAX_HISTORY_TURNS = 6;
+var MAX_HISTORY_CHARS = 600;
+function tryParse(line) {
+  const s = line.trim();
+  if (!s) return null;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}
+function claudeDelta(line) {
+  const o = tryParse(line);
+  if (o?.type !== "stream_event") return null;
+  const delta = o.event?.type === "content_block_delta" ? o.event.delta : void 0;
+  return delta?.type === "text_delta" && typeof delta.text === "string" ? delta.text : null;
+}
+function claudeResult(stdout) {
+  let result = null;
+  let deltas = "";
+  for (const line of stdout.split("\n")) {
+    const o = tryParse(line);
+    if (!o) continue;
+    if (o.type === "result" && typeof o.result === "string") {
+      result = o.result;
+      continue;
+    }
+    if (o.type === "stream_event" && o.event?.type === "content_block_delta" && o.event.delta?.type === "text_delta" && typeof o.event.delta.text === "string") {
+      deltas += o.event.delta.text;
+    }
+  }
+  return (result ?? deltas).trim();
+}
 var RUNNERS = [
   {
     id: "claude",
     label: "Claude",
     bin: "claude",
-    // -p/--print is non-interactive; text format prints just the answer.
-    buildArgs: (prompt) => ["-p", prompt, "--output-format", "text"],
-    readResult: async (stdout) => stdout.trim()
+    // -p/--print is non-interactive. stream-json emits NDJSON events as the
+    // answer is generated; --verbose is required alongside it under -p, and
+    // --include-partial-messages adds the token-level `content_block_delta`
+    // events we relay live. The canonical answer is the closing `result` event.
+    buildArgs: (prompt) => [
+      "-p",
+      prompt,
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      "--include-partial-messages"
+    ],
+    parseDelta: claudeDelta,
+    readResult: async (stdout) => claudeResult(stdout)
   },
   {
     id: "codex",
@@ -1382,7 +2184,7 @@ function detectAgents() {
   }
   return detected;
 }
-async function buildPrompt(specFile, question) {
+async function buildPrompt(specFile, question, clientContext, catalogue, history) {
   let title = "a live market dashboard";
   const symbols = /* @__PURE__ */ new Set();
   try {
@@ -1397,45 +2199,93 @@ async function buildPrompt(specFile, question) {
     }
   } catch {
   }
-  const universe = symbols.size ? [...symbols].join(", ") : "no specific symbols";
-  return `You are zAI, a market assistant embedded in a live dashboard titled "${title}". The symbols on screen right now are: ${universe}. Answer the user's question in 2\u20134 sentences of plain text \u2014 no markdown headings, no preamble, no tool use, just the answer.
+  const trimmed = clientContext?.trim();
+  const grounding = trimmed ? `Here is what the user is looking at on their dashboard "${title}" right now (live values captured from the screen):
+
+${trimmed.slice(
+    0,
+    MAX_CONTEXT_CHARS
+  )}` : `The user's dashboard is titled "${title}". The symbols on screen right now are: ${symbols.size ? [...symbols].join(", ") : "no specific symbols"}.`;
+  const trimmedCatalogue = catalogue?.trim();
+  const frameCatalogue = trimmedCatalogue ? `The frames a user can add in zframes (name \u2014 what it shows), by family:
+${trimmedCatalogue}
+
+` : "";
+  const recent = (history ?? []).filter((m) => m.text.trim()).slice(-MAX_HISTORY_TURNS);
+  const transcript = recent.length ? `Conversation so far (most recent last):
+${recent.map(
+    (m) => `${m.role === "user" ? "User" : "zAI"}: ${m.text.replace(/\s+/g, " ").trim().slice(0, MAX_HISTORY_CHARS)}`
+  ).join("\n")}
+
+` : "";
+  return (
+    // Primer: brief the runner on what zframes is and how it works, so a
+    // general-purpose agent answers as the embedded assistant rather than from
+    // cold. Kept tight — the catalogue + live digest below carry the specifics.
+    `You are zAI, the assistant built into zframes \u2014 a keyless, AI-personalizable live market dashboard for crypto and stocks. Users assemble their own dashboard from "frames": self-contained widgets for live prices, funding, open interest, fear & greed, TVL and on-chain activity, macro rates, news, even games. They arrange frames on a grid in "customise" mode \u2014 drag, resize, add, remove, and configure each \u2014 and edits save to a dashboard.json the runtime renders from. All data comes from free public APIs (no keys, no accounts); stocks are Hyperliquid HIP-3 perps \u2014 equities (xyz:TSLA), indices (xyz:SP500), commodities (xyz:GOLD), FX (xyz:EUR) \u2014 shown alongside crypto. Help the user read what's on their screen and the markets it tracks.
 
-Question: ${question}`;
+${frameCatalogue}${grounding}
+
+${transcript}Stay strictly on topic. Only answer questions about zframes itself (its frames, data, dashboard, and how to use it) and about markets and finance \u2014 stocks, crypto, prices, funding, market caps, on-chain and macro data, and the symbols on screen. If the question is about anything else (general knowledge, coding, personal advice, writing, other software, etc.), do not answer it: reply in one sentence that you only cover zframes and the markets it tracks, and invite a market or dashboard question instead.
+
+Answer the user's question in 2\u20134 sentences of plain text \u2014 no markdown headings, no preamble, no tool use, just the answer.
+
+Question: ${question}`
+  );
 }
 var askCounter = 0;
-function runAgent(runner, prompt, cwd) {
+function runAgent(runner, prompt, cwd, onDelta) {
   const outFile = join2(
     tmpdir(),
     `zframes-ask-${process.pid}-${++askCounter}.txt`
   );
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     let child;
     try {
-      child = spawn(runner.bin, runner.buildArgs(prompt, outFile), { cwd });
+      child = spawn(runner.bin, runner.buildArgs(prompt, outFile), {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
     } catch (error) {
-      resolve4({ ok: false, error: String(error) });
+      resolve5({ ok: false, error: String(error) });
       return;
     }
     let stdout = "";
     let stderr = "";
+    let lineBuf = "";
     let settled = false;
     const finish = (r) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
-      resolve4(r);
+      resolve5(r);
     };
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
       finish({ ok: false, error: `${runner.label} timed out` });
     }, RUN_TIMEOUT_MS);
-    child.stdout?.on("data", (d) => stdout += d);
+    const streaming = Boolean(onDelta && runner.parseDelta);
+    const emit = (line) => {
+      const delta = runner.parseDelta?.(line);
+      if (delta) onDelta?.(delta);
+    };
+    child.stdout?.on("data", (d) => {
+      stdout += d;
+      if (!streaming) return;
+      lineBuf += d;
+      let nl;
+      while ((nl = lineBuf.indexOf("\n")) !== -1) {
+        emit(lineBuf.slice(0, nl));
+        lineBuf = lineBuf.slice(nl + 1);
+      }
+    });
     child.stderr?.on("data", (d) => stderr += d);
     child.on(
       "error",
       (e) => finish({ ok: false, error: String(e.message) })
     );
     child.on("close", (code) => {
+      if (streaming && lineBuf) emit(lineBuf);
       if (code !== 0) {
         finish({
           ok: false,
@@ -1460,7 +2310,7 @@ async function handleAgents(res) {
     JSON.stringify({ agents: agents.map(({ id, label }) => ({ id, label })) })
   );
 }
-function handleAsk(req, res, specFile) {
+function handleAsk(req, res, specFile, catalogue) {
   if (req.method !== "POST") {
     res.statusCode = 405;
     res.end();
@@ -1485,44 +2335,295 @@ function handleAsk(req, res, specFile) {
   });
   req.on("end", async () => {
     if (aborted) return;
-    const reply = (status, payload) => {
+    const replyJson = (status, payload) => {
       res.statusCode = status;
       res.setHeader("content-type", "application/json");
       res.end(JSON.stringify(payload));
     };
     let question;
     let requested;
+    let clientContext;
+    let history;
     try {
       const parsed = JSON.parse(body);
       if (typeof parsed.question !== "string" || !parsed.question.trim())
         throw new Error("missing question");
       question = parsed.question.trim();
       requested = typeof parsed.agent === "string" ? parsed.agent : void 0;
+      clientContext = typeof parsed.context === "string" ? parsed.context : void 0;
+      if (Array.isArray(parsed.history))
+        history = parsed.history.filter(
+          (m) => !!m && typeof m === "object" && (m.role === "user" || m.role === "zai") && typeof m.text === "string"
+        ).slice(-MAX_HISTORY_TURNS);
     } catch (error) {
-      reply(400, { ok: false, error: String(error.message) });
+      replyJson(400, { ok: false, error: String(error.message) });
       return;
     }
     const agents = await detectAgents();
     if (agents.length === 0) {
-      reply(503, {
+      replyJson(503, {
         ok: false,
         error: "no agent CLI found \u2014 install claude, codex, or kimi"
       });
       return;
     }
     const runner = agents.find((a) => a.id === requested) ?? agents[0];
-    const prompt = await buildPrompt(specFile, question);
-    const result = await runAgent(runner, prompt, dirname2(specFile));
+    const prompt = await buildPrompt(
+      specFile,
+      question,
+      clientContext,
+      catalogue,
+      history
+    );
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/x-ndjson; charset=utf-8");
+    res.setHeader("cache-control", "no-store");
+    res.setHeader("x-accel-buffering", "no");
+    const send = (event) => {
+      try {
+        res.write(`${JSON.stringify(event)}
+`);
+      } catch {
+      }
+    };
+    const result = await runAgent(
+      runner,
+      prompt,
+      dirname2(specFile),
+      (text) => send({ type: "delta", text })
+    );
     if (result.ok)
-      reply(200, { ok: true, agent: runner.id, answer: result.answer });
-    else reply(502, { ok: false, agent: runner.id, error: result.error });
+      send({ type: "done", agent: runner.id, answer: result.answer });
+    else send({ type: "error", agent: runner.id, error: result.error });
+    try {
+      res.end();
+    } catch {
+    }
+  });
+}
+
+// ../core/src/account.ts
+import { createHmac } from "crypto";
+import { chmod, mkdir, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+function json(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.setHeader("cache-control", "no-store");
+  res.end(JSON.stringify(body));
+}
+var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+function isLocalRequest(req) {
+  const hostname = String(req.headers.host ?? "").split(":")[0];
+  if (!LOCAL_HOSTS.has(hostname)) return false;
+  const origin = req.headers.origin;
+  if (origin !== void 0) {
+    try {
+      if (!LOCAL_HOSTS.has(new URL(String(origin)).hostname)) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+var MAX_BODY_BYTES3 = 8192;
+function readBody(req, res) {
+  return new Promise((resolveBody) => {
+    let body = "";
+    let aborted = false;
+    req.on("data", (chunk) => {
+      if (aborted) return;
+      body += chunk;
+      if (body.length > MAX_BODY_BYTES3) {
+        aborted = true;
+        json(res, 413, { ok: false, error: "body too large" });
+        req.destroy();
+        resolveBody(null);
+      }
+    });
+    req.on("end", () => {
+      if (!aborted) resolveBody(body);
+    });
+  });
+}
+async function readStore() {
+  try {
+    const parsed = JSON.parse(
+      await readFile3(credentialsFile(), "utf8")
+    );
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+async function writeStore(store) {
+  await mkdir(storeHome(), { recursive: true, mode: 448 });
+  await chmod(storeHome(), 448).catch(() => {
+  });
+  await writeFile2(credentialsFile(), `${JSON.stringify(store, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
+}
+function envCredential(source) {
+  const up = source.toUpperCase();
+  const key = process.env[`ZFRAMES_${up}_KEY`];
+  const secret = process.env[`ZFRAMES_${up}_SECRET`];
+  return key && secret ? { key, secret } : null;
+}
+async function getCredential(source) {
+  const store = await readStore();
+  return store[source] ?? envCredential(source);
+}
+function maskKey(key) {
+  return key.length <= 4 ? "\u2026" : `\u2026${key.slice(-4)}`;
+}
+var STABLES = /* @__PURE__ */ new Set([
+  "USDT",
+  "USDC",
+  "BUSD",
+  "DAI",
+  "FDUSD",
+  "TUSD",
+  "USDP",
+  "USD"
+]);
+var BINANCE_BASE = "https://api.binance.com";
+var BINANCE_TIMEOUT_MS = 15e3;
+function signBinance(query, secret) {
+  return createHmac("sha256", secret).update(query).digest("hex");
+}
+function binanceHoldings(data) {
+  return (data.balances ?? []).map((b) => ({
+    symbol: b.asset,
+    amount: Number(b.free) + Number(b.locked)
+  })).filter((b) => Number.isFinite(b.amount) && b.amount > 0).map((b) => ({
+    symbol: b.symbol,
+    amount: b.amount,
+    valueUsd: STABLES.has(b.symbol.toUpperCase()) ? b.amount : void 0
+  }));
+}
+async function binanceAccount(cred, nowMs) {
+  const query = `timestamp=${nowMs}&recvWindow=5000`;
+  const signature = signBinance(query, cred.secret);
+  const res = await fetch(
+    `${BINANCE_BASE}/api/v3/account?${query}&signature=${signature}`,
+    {
+      headers: { "X-MBX-APIKEY": cred.key },
+      signal: AbortSignal.timeout(BINANCE_TIMEOUT_MS)
+    }
+  );
+  if (!res.ok) {
+    throw new Error(`binance ${res.status}`);
+  }
+  return res.json();
+}
+var binanceAdapter = {
+  async verify(cred) {
+    await binanceAccount(cred, Date.now());
+  },
+  async portfolio(cred) {
+    const data = await binanceAccount(cred, Date.now());
+    return {
+      source: "binance",
+      label: "Binance",
+      holdings: binanceHoldings(data),
+      asOf: Date.now()
+    };
+  }
+};
+var ADAPTERS = { binance: binanceAdapter };
+function sourceParam(req) {
+  const query = (req.url ?? "").split("?")[1] ?? "";
+  return new URLSearchParams(query).get("source") ?? "";
+}
+async function handleAccountPortfolio(req, res) {
+  if (!isLocalRequest(req))
+    return json(res, 403, { ok: false, error: "non-local origin" });
+  if (req.method !== "GET" && req.method !== "HEAD")
+    return json(res, 405, { ok: false, error: "GET only" });
+  const source = sourceParam(req);
+  const adapter = ADAPTERS[source];
+  if (!adapter)
+    return json(res, 400, { ok: false, error: `unknown source: ${source}` });
+  const cred = await getCredential(source);
+  if (!cred)
+    return json(res, 401, {
+      ok: false,
+      connected: false,
+      error: "not connected"
+    });
+  try {
+    json(res, 200, await adapter.portfolio(cred));
+  } catch (error) {
+    json(res, 502, { ok: false, error: String(error) });
+  }
+}
+async function handleAccountCredentials(req, res) {
+  if (!isLocalRequest(req))
+    return json(res, 403, { ok: false, error: "non-local origin" });
+  const method = req.method ?? "GET";
+  if (method === "GET") {
+    const cred = await getCredential(sourceParam(req));
+    return json(res, 200, {
+      connected: !!cred,
+      keyMasked: cred ? maskKey(cred.key) : null
+    });
+  }
+  if (method !== "POST" && method !== "DELETE")
+    return json(res, 405, { ok: false, error: "method not allowed" });
+  if (!String(req.headers["content-type"] ?? "").includes("application/json"))
+    return json(res, 415, {
+      ok: false,
+      error: "content-type must be application/json"
+    });
+  const raw = await readBody(req, res);
+  if (raw === null) return;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return json(res, 400, { ok: false, error: "invalid json" });
+  }
+  const source = String(parsed.source ?? "");
+  if (!ADAPTERS[source])
+    return json(res, 400, { ok: false, error: `unknown source: ${source}` });
+  if (method === "DELETE") {
+    const store2 = await readStore();
+    delete store2[source];
+    await writeStore(store2);
+    return json(res, 200, { ok: true, connected: false });
+  }
+  const key = String(parsed.key ?? "").trim();
+  const secret = String(parsed.secret ?? "").trim();
+  if (!key || !secret)
+    return json(res, 400, { ok: false, error: "key and secret required" });
+  try {
+    await ADAPTERS[source].verify({ key, secret });
+  } catch (error) {
+    return json(res, 400, {
+      ok: false,
+      verified: false,
+      error: `verification failed: ${String(error)}`
+    });
+  }
+  const store = await readStore();
+  store[source] = { key, secret };
+  await writeStore(store);
+  return json(res, 200, {
+    ok: true,
+    verified: true,
+    connected: true,
+    keyMasked: maskKey(key)
   });
 }
 
 // src/serve.ts
 var DEFAULT_PORT = 37263;
+var MAX_SWITCH_BODY_BYTES = 1e5;
+var FRAME_CATALOGUE = catalogueSummary(frameMetas);
 function parseArgs2(args) {
-  let file = "dashboard.json";
+  let file;
   let port = DEFAULT_PORT;
   let contact = process.env.ZFRAMES_CONTACT;
   for (let i = 0; i < args.length; i++) {
@@ -1546,31 +2647,97 @@ function parseArgs2(args) {
   }
   return { file, port, contact };
 }
+function sendJson(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.setHeader("cache-control", "no-store");
+  res.end(JSON.stringify(body));
+}
 function serve(args) {
   const parsed = parseArgs2(args);
   if ("error" in parsed) {
     console.error(`\u2717 ${parsed.error}`);
     console.error(
-      "usage: zframes serve [dashboard.json] [--port <n>] [--contact <email>]"
+      "usage: zframes serve [name|dashboard.json] [--port <n>] [--contact <email>]"
     );
     return Promise.resolve(1);
   }
-  const file = resolve2(process.cwd(), parsed.file);
-  if (!existsSync2(file) || !statSync2(file).isFile()) {
-    console.error(`\u2717 no dashboard.json at ${parsed.file}`);
-    console.error("  pass a path, or run from a directory that has one.");
+  const target = resolveServeTarget(parsed.file, process.cwd());
+  if ("error" in target) {
+    console.error(`\u2717 ${target.error}`);
     return Promise.resolve(1);
   }
-  const userDir = resolve2(file, "..");
+  let current = target;
+  const canSwitch = target.kind === "store";
   const bundleDir = fileURLToPath(new URL("../runtime", import.meta.url));
-  if (!existsSync2(join3(bundleDir, "index.html"))) {
+  if (!existsSync3(join3(bundleDir, "index.html"))) {
     console.error(`\u2717 runtime bundle missing at ${bundleDir}`);
     console.error("  run `pnpm build:cli` to build it.");
     return Promise.resolve(1);
   }
   const serveBundle = sirv(bundleDir, { dev: true });
-  const serveSiblings = sirv(userDir, { dev: true });
+  let serveSiblings = sirv(resolve3(current.file, ".."), { dev: true });
   const serveSpa = sirv(bundleDir, { dev: true, single: true });
+  function handleSwitch(req, res) {
+    if (!isLocalRequest(req)) {
+      sendJson(res, 403, { ok: false, error: "loopback only" });
+      return;
+    }
+    if (req.method !== "POST") {
+      res.statusCode = 405;
+      res.end();
+      return;
+    }
+    if (!canSwitch) {
+      sendJson(res, 409, {
+        ok: false,
+        error: "switching is only available when serving from the store"
+      });
+      return;
+    }
+    if (!String(req.headers["content-type"] ?? "").includes("application/json")) {
+      res.statusCode = 415;
+      res.end();
+      return;
+    }
+    let body = "";
+    let aborted = false;
+    req.on("data", (chunk) => {
+      if (aborted) return;
+      body += chunk;
+      if (body.length > MAX_SWITCH_BODY_BYTES) {
+        aborted = true;
+        res.statusCode = 413;
+        res.end();
+        req.destroy();
+      }
+    });
+    req.on("end", () => {
+      if (aborted) return;
+      let name;
+      try {
+        name = JSON.parse(body || "{}").name;
+      } catch {
+        sendJson(res, 400, { ok: false, error: "invalid JSON body" });
+        return;
+      }
+      if (typeof name !== "string" || !isValidName(name)) {
+        sendJson(res, 400, { ok: false, error: "invalid dashboard name" });
+        return;
+      }
+      const file = findDashboardFile(name);
+      if (!file) {
+        sendJson(res, 404, {
+          ok: false,
+          error: `no dashboard named "${name}" in the store`
+        });
+        return;
+      }
+      current = { kind: "store", name, file };
+      serveSiblings = sirv(resolve3(current.file, ".."), { dev: true });
+      sendJson(res, 200, { ok: true, name });
+    });
+  }
   return new Promise((done) => {
     const server = createServer((req, res) => {
       const rawPath = (req.url ?? "/").split("?")[0];
@@ -1584,7 +2751,7 @@ function serve(args) {
       }
       if (path === DASHBOARD_READ_ROUTE) {
         if (req.method === "GET" || req.method === "HEAD") {
-          void handleSpecRead(file, res);
+          void handleSpecRead(current.file, res);
         } else {
           res.statusCode = 405;
           res.end();
@@ -1592,7 +2759,32 @@ function serve(args) {
         return;
       }
       if (path === DASHBOARD_WRITE_ROUTE) {
-        handleSpecWrite(req, res, file);
+        handleSpecWrite(req, res, current.file);
+        return;
+      }
+      if (path === DASHBOARD_LIST_ROUTE) {
+        if (!isLocalRequest(req)) {
+          sendJson(res, 403, { ok: false, error: "loopback only" });
+          return;
+        }
+        if (req.method === "GET" || req.method === "HEAD") {
+          sendJson(res, 200, {
+            current: current.kind === "store" ? current.name : null,
+            canSwitch,
+            dashboards: canSwitch ? listDashboards().map((e) => ({
+              name: e.name,
+              title: e.title,
+              isDefault: e.isDefault
+            })) : []
+          });
+        } else {
+          res.statusCode = 405;
+          res.end();
+        }
+        return;
+      }
+      if (path === DASHBOARD_SWITCH_ROUTE) {
+        handleSwitch(req, res);
         return;
       }
       if (path === AGENTS_LIST_ROUTE) {
@@ -1605,7 +2797,15 @@ function serve(args) {
         return;
       }
       if (path === ASK_ROUTE) {
-        handleAsk(req, res, file);
+        handleAsk(req, res, current.file, FRAME_CATALOGUE);
+        return;
+      }
+      if (path === ACCOUNT_PORTFOLIO_ROUTE) {
+        void handleAccountPortfolio(req, res);
+        return;
+      }
+      if (path === ACCOUNT_CREDENTIALS_ROUTE) {
+        void handleAccountCredentials(req, res);
         return;
       }
       if (path === DASHBOARD_PROXY_ROUTE) {
@@ -1649,17 +2849,23 @@ function serve(args) {
     });
     server.listen(parsed.port, "127.0.0.1", () => {
       const url = `http://localhost:${parsed.port}`;
+      const label = target.kind === "store" ? `"${target.name}" from your store` : target.file;
       console.log(`\u26A1 zframes is live at ${url}`);
       console.log(
-        `   serving ${parsed.file} \u2014 live editing on; drag, resize, then Save writes back.`
+        `   serving ${label} \u2014 live editing on; drag, resize, then Save writes back.`
       );
+      if (canSwitch && listDashboards().length > 1) {
+        console.log(
+          "   switch dashboards from the header dropdown in the app."
+        );
+      }
     });
   });
 }
 
 // src/snapshot.ts
-import { existsSync as existsSync3, readFileSync } from "fs";
-import { dirname as dirname3, resolve as resolve3 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname3, join as join4, resolve as resolve4 } from "path";
 
 // ../core/src/cache.ts
 var TtlCache = class {
@@ -2168,19 +3374,19 @@ var DAY_MS = 864e5;
 function loadSpec(file) {
   let raw;
   try {
-    raw = readFileSync(file, "utf8");
+    raw = readFileSync2(file, "utf8");
   } catch {
     console.error(`\u2717 cannot read ${file}`);
     return null;
   }
-  let json;
+  let json2;
   try {
-    json = JSON.parse(raw);
+    json2 = JSON.parse(raw);
   } catch (error) {
     console.error(`\u2717 ${file} is not valid JSON: ${error.message}`);
     return null;
   }
-  const parsed = DashboardSpecSchema.safeParse(json);
+  const parsed = DashboardSpecSchema.safeParse(json2);
   if (!parsed.success) {
     console.error(`\u2717 ${file} is not a valid dashboard spec:`);
     for (const issue of parsed.error.issues)
@@ -2223,6 +3429,24 @@ function flagValue(args, name) {
   const index = args.indexOf(name);
   return index >= 0 ? args[index + 1] : void 0;
 }
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--log",
+  "--date",
+  "--model",
+  "--effort",
+  "--config"
+]);
+function positionalArg(args) {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("-")) {
+      if (VALUE_FLAGS.has(a)) i++;
+      continue;
+    }
+    return a;
+  }
+  return void 0;
+}
 function runMeta(args) {
   const pick = (flag, env) => flagValue(args, flag) ?? process.env[env] ?? null;
   const rawConfig = pick("--config", "ZFRAMES_CONFIG");
@@ -2241,27 +3465,31 @@ function runMeta(args) {
     config
   };
 }
-function loadPriorEntry(dashboardPath, logFlag) {
-  const logPath = logFlag ? resolve3(logFlag) : resolve3(dirname3(dashboardPath), "..", "public", "daily-analysis.json");
-  if (!existsSync3(logPath)) return null;
+function defaultLogPath(target) {
+  return target.kind === "store" ? join4(dirname3(target.file), "daily-analysis.json") : resolve4(dirname3(target.file), "..", "public", "daily-analysis.json");
+}
+function loadPriorEntry(logPath) {
+  if (!existsSync4(logPath)) return null;
   try {
-    const json = JSON.parse(readFileSync(logPath, "utf8"));
-    const entries = json.entries ?? [];
+    const json2 = JSON.parse(readFileSync2(logPath, "utf8"));
+    const entries = json2.entries ?? [];
     return entries.length ? entries[entries.length - 1] : null;
   } catch {
     return null;
   }
 }
+var USAGE = "usage: zframes snapshot [name|dashboard.json] [--log <file>] [--date YYYY-MM-DD]\n         [--model <id>] [--effort <level>] [--config <json>]\n  (no target \u2192 the default store dashboard, just like `serve`;\n   or ZFRAMES_MODEL / ZFRAMES_EFFORT / ZFRAMES_CONFIG env)";
 async function snapshot(args) {
-  const file = args.find((arg) => !arg.startsWith("--"));
-  if (!file) {
-    console.error(
-      "usage: zframes snapshot <dashboard.json> [--log <file>] [--date YYYY-MM-DD]\n         [--model <id>] [--effort <level>] [--config <json>]  (or ZFRAMES_MODEL / ZFRAMES_EFFORT / ZFRAMES_CONFIG env)"
-    );
+  const resolved = resolveServeTarget(positionalArg(args), process.cwd());
+  if ("error" in resolved) {
+    console.error(`\u2717 ${resolved.error}`);
+    console.error(USAGE);
     return 1;
   }
+  const file = resolved.file;
   const logFlag = flagValue(args, "--log");
   const dateFlag = flagValue(args, "--date");
+  const logPath = logFlag ? resolve4(logFlag) : defaultLogPath(resolved);
   const spec = loadSpec(file);
   if (!spec) return 1;
   const universe = symbolsFromSpec(spec);
@@ -2286,6 +3514,16 @@ async function snapshot(args) {
   const out = {
     date: dateFlag ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
     run: runMeta(args),
+    // Which dashboard this snapshot is for, and where its brief lives — so the
+    // /zframes-brief agent writes the new entry to the RIGHT per-dashboard log
+    // (`logPath`, a sibling of this dashboard inside its folder). The frame reads
+    // it at its default `/daily-analysis.json` — no per-name `src` needed.
+    dashboard: {
+      kind: resolved.kind,
+      name: resolved.kind === "store" ? resolved.name : null,
+      file,
+      logPath
+    },
     universe,
     featured,
     market: {
@@ -2297,7 +3535,7 @@ async function snapshot(args) {
       global,
       tvl: tvl ? tvl.slice(0, 12) : null
     },
-    priorEntry: loadPriorEntry(file, logFlag)
+    priorEntry: loadPriorEntry(logPath)
   };
   console.log(JSON.stringify(out, null, 2));
   return 0;
@@ -2306,39 +3544,57 @@ async function snapshot(args) {
 // src/index.ts
 var HELP = `zframes \u2014 AI-personalizable market dashboards
 
+A dashboard is one dashboard.json. Point at a file, or name one and it lives in
+your global store ($XDG_CONFIG_HOME/zframes, default ~/.config/zframes) so you
+can run from anywhere and keep many. A bare token (e.g. \`crypto\`) is a store
+name; anything with a "/" or a ".json" suffix is a file path.
+
 usage:
-  zframes init [dir|file]     write a bare, valid dashboard.json (envelope only \u2014
-                              version, author, grid, background, theme, empty
-                              frames) for the agent to fill in; --title <t>,
-                              --author <a>, --force to overwrite
-  zframes serve [file]        serve <dashboard.json> (default: ./dashboard.json)
-                              as a live, editable terminal at localhost:37263
-                              (--port <n> to change); Save writes back to the file
-  zframes catalogue           print the frame catalogue as JSON Schema
-                              (this is what a generating agent reads)
-  zframes lint <file>         validate a dashboard.json; exit 1 with readable
-                              errors (the agent's self-correction feedback)
-  zframes snapshot <file>     gather a keyless market snapshot for the symbols
-                              on <dashboard.json> + the prior brief, as JSON on
-                              stdout (the deterministic half of /zframes-brief)
-  zframes help                this text
+  zframes init [name|dir|file]  write a bare, valid dashboard (envelope only \u2014
+                                version, author, grid, background, theme, empty
+                                frames) for the agent to fill in. A name lands in
+                                the store (and becomes the default if you don't
+                                have one yet); --title <t>, --author <a>,
+                                --default, --force
+  zframes serve [name|file]     serve a dashboard as a live, editable terminal at
+                                localhost:37263 (--port <n>). With no arg: the
+                                default store dashboard, else ./dashboard.json,
+                                else a sole store entry. Save writes back; switch
+                                store dashboards from the in-app header dropdown
+  zframes list                  list the dashboards in your store (default *)
+  zframes use <name>            set the default store dashboard
+  zframes catalogue             print the frame catalogue as JSON Schema
+                                (this is what a generating agent reads)
+  zframes lint <name|file>      validate a dashboard; exit 1 with readable errors
+                                (the agent's self-correction feedback)
+  zframes snapshot [name|file]  gather a keyless market snapshot for the symbols
+                                on the dashboard + the prior brief, as JSON on
+                                stdout (the deterministic half of /zframes-brief;
+                                no target \u2192 the default store dashboard)
+  zframes help                  this text
 `;
-function lint(file) {
+function lint(arg) {
+  const resolved = classifyTarget(arg, process.cwd());
+  if ("error" in resolved) {
+    console.error(`\u2717 ${resolved.error}`);
+    return 1;
+  }
+  const file = resolved.file;
   let raw;
   try {
-    raw = readFileSync2(file, "utf8");
+    raw = readFileSync3(file, "utf8");
   } catch {
     console.error(`\u2717 cannot read ${file}`);
     return 1;
   }
-  let json;
+  let json2;
   try {
-    json = JSON.parse(raw);
+    json2 = JSON.parse(raw);
   } catch (error) {
     console.error(`\u2717 ${file} is not valid JSON: ${error.message}`);
     return 1;
   }
-  const parsed = DashboardSpecSchema.safeParse(json);
+  const parsed = DashboardSpecSchema.safeParse(json2);
   if (!parsed.success) {
     console.error(`\u2717 ${file} is not a valid dashboard spec:`);
     for (const issue of parsed.error.issues)
@@ -2374,6 +3630,11 @@ async function main() {
       return lint(arg);
     case "serve":
       return serve(args.slice(1));
+    case "list":
+    case "ls":
+      return list();
+    case "use":
+      return use(args.slice(1));
     case "snapshot":
       return snapshot(args.slice(1));
     case "help":