zframes 0.3.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";
@@ -66,8 +66,16 @@ var FrameInstanceSchema = z2.object({
   )
 });
 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'."
@@ -135,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: {
@@ -148,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(
@@ -182,7 +197,11 @@ var DashboardSpecSchema = z2.preprocess(
       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
@@ -211,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;
@@ -244,7 +421,8 @@ 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",
@@ -331,12 +509,12 @@ var priceChartMeta = defineFrameMeta({
   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."),
@@ -353,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."
@@ -373,7 +551,7 @@ 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".'
     )
   })
 });
@@ -431,6 +609,24 @@ 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",
@@ -1418,6 +1614,7 @@ var frameMetas = [
   priceLivelineMeta,
   priceTickerMeta,
   ratesBoardMeta,
+  fxBoardMeta,
   shortVolumeMeta,
   topMoversMeta,
   tvlTreemapMeta,
@@ -1450,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") {
@@ -1471,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 {
@@ -1478,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 {
@@ -1524,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(
@@ -1537,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;
     }
@@ -1551,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}`);
@@ -1626,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 join4, 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";
 
@@ -1638,6 +1929,8 @@ 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";
@@ -1656,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
@@ -1928,11 +2222,13 @@ ${recent.map(
     // 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 equity perps (e.g. "xyz:TSLA") shown alongside crypto. Help the user read what's on their screen and the markets it tracks.
+    `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.
 
 ${frameCatalogue}${grounding}
 
-${transcript}Answer the user's question in 2\u20134 sentences of plain text \u2014 no markdown headings, no preamble, no tool use, just the answer.
+${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}`
   );
@@ -1943,7 +2239,7 @@ function runAgent(runner, prompt, cwd, onDelta) {
     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), {
@@ -1951,7 +2247,7 @@ function runAgent(runner, prompt, cwd, onDelta) {
         stdio: ["ignore", "pipe", "pipe"]
       });
     } catch (error) {
-      resolve4({ ok: false, error: String(error) });
+      resolve5({ ok: false, error: String(error) });
       return;
     }
     let stdout = "";
@@ -1962,7 +2258,7 @@ function runAgent(runner, prompt, cwd, onDelta) {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
-      resolve4(r);
+      resolve5(r);
     };
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
@@ -2108,9 +2404,7 @@ function handleAsk(req, res, specFile, catalogue) {
 
 // ../core/src/account.ts
 import { createHmac } from "crypto";
-import { mkdir, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
-import { homedir } from "os";
-import { join as join3 } from "path";
+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");
@@ -2151,19 +2445,21 @@ function readBody(req, res) {
     });
   });
 }
-var CRED_DIR = join3(homedir(), ".zframes");
-var CRED_FILE = join3(CRED_DIR, "credentials.json");
 async function readStore() {
   try {
-    const parsed = JSON.parse(await readFile3(CRED_FILE, "utf8"));
+    const parsed = JSON.parse(
+      await readFile3(credentialsFile(), "utf8")
+    );
     return parsed && typeof parsed === "object" ? parsed : {};
   } catch {
     return {};
   }
 }
 async function writeStore(store) {
-  await mkdir(CRED_DIR, { recursive: true, mode: 448 });
-  await writeFile2(CRED_FILE, `${JSON.stringify(store, null, 2)}
+  await mkdir(storeHome(), { recursive: true, mode: 448 });
+  await chmod(storeHome(), 448).catch(() => {
+  });
+  await writeFile2(credentialsFile(), `${JSON.stringify(store, null, 2)}
 `, {
     encoding: "utf8",
     mode: 384
@@ -2324,9 +2620,10 @@ async function handleAccountCredentials(req, res) {
 
 // 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++) {
@@ -2350,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(join4(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];
@@ -2388,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();
@@ -2396,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) {
@@ -2409,7 +2797,7 @@ function serve(args) {
         return;
       }
       if (path === ASK_ROUTE) {
-        handleAsk(req, res, file, FRAME_CATALOGUE);
+        handleAsk(req, res, current.file, FRAME_CATALOGUE);
         return;
       }
       if (path === ACCOUNT_PORTFOLIO_ROUTE) {
@@ -2461,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 {
@@ -2980,7 +3374,7 @@ 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;
@@ -3035,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");
@@ -3053,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 json2 = JSON.parse(readFileSync(logPath, "utf8"));
+    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);
@@ -3098,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: {
@@ -3109,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;
@@ -3118,27 +3544,45 @@ 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;
@@ -3186,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":