mindvest-atlas 0.14.2 → 0.14.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindvest-atlas",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "description": "Atlas CLI \u2014 OAuth login, tool calls, and live alert/flow streaming for the Atlas trading API",
   "type": "module",
   "bin": {

package/src/commands/remote-control.js

@@ -9,7 +9,7 @@
 // A job that could NOT run is reported too: silence is indistinguishable from
 // a schedule that quietly broke, which is the failure the record exists to make
 // visible.
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { API, baseUrl } from '../config.js';
 import { requestJson, jobToken } from '../api/client.js';
 import { runStream } from '../util/stream-loop.js';
@@ -17,8 +17,9 @@ import { color, eprintln } from '../util/ui.js';
 import {
   DEFAULT_TIMEOUT_MS, claimRun, computerName, isPaused, jobEnv, listJobFiles, listRuns, machineId,
   osLabel, readJobFile, releaseRun, staleness, summarize, tail, workspace, workspaceRoot,
-  setPaused, writeHelpers, askModel, listModels, chatModel,
+  setPaused, writeHelpers, askModel, listModels, chatModel, answerPermission,
   createProject, ensureProjectFiles, listChats, readChat, deleteChat, appendChat,
+  readSchedule, cronMatches, dueMinutes, SCRIPTS_DIR, projectsForAlert, readMode,
 } from '../remote-control.js';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -67,14 +68,57 @@ async function report() {
   return undefined;
 }
 
-function runOnce(argv, dir, env, timeoutMs) {
+/** The run going on in each project right now, by folder name, so Stop can
+ *  reach it. One run per project means one entry per project. */
+const running = new Map();
+
+/** Kill a run's whole process tree. On Windows a plain kill leaves the
+ *  script's own children going; taskkill /T takes the tree. */
+function killTree(child) {
+  if (!child || child.pid === undefined) return;
+  if (process.platform === 'win32') {
+    try { spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { windowsHide: true }); return; } catch { /* fall through */ }
+  }
+  try { child.kill('SIGTERM'); } catch { /* already gone */ }
+  const pid = child.pid;
+  setTimeout(() => { try { process.kill(pid, 0); process.kill(pid, 'SIGKILL'); } catch { /* gone */ } }, 3_000).unref();
+}
+
+/** Stop the run in one project, if there is one. Returns whether there was. */
+/** Listeners the owner stopped by hand: not restarted until Run now or a
+ *  relaunch. Pressing Stop on something that comes straight back is a lie. */
+const userStopped = new Set();
+/** Per-listener restart pacing: when it last exited, and how many times in a
+ *  row it died young. A crash loop backs off to a minute, not a spin. */
+const listenerExits = new Map();
+
+export function stopRun(slug) {
+  const entry = running.get(slug);
+  if (!entry) return false;
+  entry.stopped = true;
+  userStopped.add(slug);
+  killTree(entry.child);
+  return true;
+}
+
+export function runOnce(argv, dir, env, timeoutMs) {
   return new Promise((resolve) => {
     let out = '';
     let done = false;
     const child = spawn(argv[0], argv.slice(1), { cwd: dir, env });
-    const finish = (r) => { if (!done) { done = true; resolve(r); } };
-    const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ }
-      finish({ timedOut: true, out }); }, timeoutMs);
+    const entry = { child, stopped: false };
+    running.set(path.basename(dir), entry);
+    const finish = (r) => {
+      if (done) return;
+      done = true;
+      running.delete(path.basename(dir));
+      resolve(entry.stopped ? { stopped: true, out } : r);
+    };
+    // No timer at all for a listener: it is meant to stay up.
+    const timer = timeoutMs > 0
+      ? setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ }
+        finish({ timedOut: true, out }); }, timeoutMs)
+      : null;
     const cap = (c) => { out += String(c); if (out.length > 200_000) out = out.slice(-200_000); };
     child.stdout.on('data', cap);
     child.stderr.on('data', cap);
@@ -124,6 +168,13 @@ async function handleAsk(ask, root) {
     return answer(ask.request_id, { ok: true, paused: setPaused(dir, Boolean(ask.paused)) });
   }
   if (ask.op === 'runs') return answer(ask.request_id, { ok: true, runs: listRuns(root) });
+  if (ask.op === 'stop') {
+    // Stop replaces Pause on the web (owner, 2026-09-03): what a person wants
+    // from the button is the run going right now to end, not a flag for later.
+    const { dir } = workspace(ask.job || '', root);
+    const had = stopRun(path.basename(dir));
+    return answer(ask.request_id, had ? { ok: true, stopped: true } : { ok: true, stopped: false, error: 'Nothing is running.' });
+  }
   if (ask.op === 'read') return answer(ask.request_id, readJobFile(ask.job || '', ask.path || '', root));
   if (ask.op === 'chat') {
     // A person typing at the web, talking to the model on this machine. Each
@@ -160,6 +211,14 @@ async function handleAsk(ask, root) {
       });
     return undefined;
   }
+  if (ask.op === 'permission') {
+    // The person's answer to a question the model asked mid-turn. Its own ask,
+    // not part of the chat stream: the stream is one-way. `permission_id` is
+    // the question; `request_id` is this ask, which is what gets the ack.
+    void answerPermission(ask.permission_id || '', ask.option_id ?? null)
+      .then((r) => answer(ask.request_id, r));
+    return undefined;
+  }
   if (ask.op === 'create') return answer(ask.request_id, createProject(ask.job || '', root));
   if (ask.op === 'chats') return answer(ask.request_id, { ok: true, chats: listChats(ask.job || '', root) });
   if (ask.op === 'chat_read') return answer(ask.request_id, readChat(ask.job || '', ask.chat_id || '', root));
@@ -237,6 +296,11 @@ async function runJob(job, root, timeoutMs) {
   }
 
   const { dir, entry, argv } = workspace(job.automation_id, root);
+  // A listener has no run timeout, and the owner pressing Run now on one they
+  // stopped means "bring it back".
+  const listen = readMode(dir) === 'listen';
+  if (listen) timeoutMs = 0;
+  if (job.source === 'manual') userStopped.delete(path.basename(dir));
   // Paused is the owner saying "not now". A scheduled run that fires anyway
   // would make the switch meaningless; a MANUAL run is the owner asking
   // directly, so it goes through.
@@ -286,6 +350,20 @@ async function runJob(job, root, timeoutMs) {
   };
   const r = await runOnce(argv, dir, env, timeoutMs);
   const finished = Date.now();
+  if (listen) {
+    // How it ended paces the restart: a listener that lived a while is
+    // restarted at once; one that died young backs off.
+    const prev = listenerExits.get(path.basename(dir)) || { exits: 0 };
+    const young = finished - started < 5 * 60_000;
+    listenerExits.set(path.basename(dir), { at: finished, exits: young ? prev.exits + 1 : 0 });
+  }
+  if (r.stopped) {
+    // The owner pressed Stop. Not a failure: they asked, it stopped.
+    eprintln(color.yellow(`■ ${name} — stopped`));
+    writeLog(dir, job, 'stopped', started, finished, `Stopped by you.\n${tail(r.out) || ''}`);
+    releaseRun(dir);
+    return report(job, 'stopped', started, finished);
+  }
   if (r.timedOut) {
     eprintln(color.red(`✗ ${name} — timed out`));
     writeLog(dir, job, 'failed', started, finished,
@@ -307,6 +385,156 @@ async function runJob(job, root, timeoutMs) {
   return report(job, ok ? 'completed' : 'failed', started, finished);
 }
 
+/**
+ * The local clock (owner decision 2026-09-03: schedule on the computer, not the
+ * server).
+ *
+ * Every 20s, for each project whose atlas.json names a `schedule`, look at the
+ * minutes since this project was last checked. The current minute firing starts
+ * a run through the same path a queued job takes (one run per project, same
+ * logs, same paused rule). Any EARLIER minute that fired while nobody was
+ * checking — the app was closed, the laptop asleep — is written down as one
+ * "Computer was off" row, because a schedule that misses in silence is the one
+ * failure the owner can never see. The last-checked minute lives in
+ * runs/.schedule so a restart knows what it slept through.
+ */
+const SCHEDULE_STATE = '.schedule';
+const TICK_MS = 20_000;
+const warnedSchedules = new Set();
+
+function lastChecked(dir) {
+  try {
+    const n = parseInt(fs.readFileSync(path.join(dir, 'runs', SCHEDULE_STATE), 'utf8'), 10);
+    return Number.isFinite(n) ? n : null;
+  } catch { return null; }
+}
+
+function markChecked(dir, minute) {
+  try {
+    fs.mkdirSync(path.join(dir, 'runs'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'runs', SCHEDULE_STATE), `${minute}\n`);
+  } catch { /* the next tick tries again */ }
+}
+
+export function scheduleTick(root, timeoutMs, nowSec = Date.now() / 1000) {
+  const base = path.join(workspaceRoot(root), SCRIPTS_DIR);
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(base, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch { return; }
+  const now = Math.floor(nowSec / 60) * 60;
+  for (const slug of dirs) {
+    const dir = path.join(base, slug);
+    const sched = readSchedule(dir);
+    if (!sched) continue;
+    if (sched.error) {
+      if (!warnedSchedules.has(slug)) {
+        warnedSchedules.add(slug);
+        eprintln(color.yellow(`· ${slug} — ${sched.error}`));
+      }
+      continue;
+    }
+    const last = lastChecked(dir);
+    if (last !== null && now <= last) continue;   // this minute is already handled
+    markChecked(dir, now);
+    const job = { automation_id: slug, name: slug, source: 'schedule', scheduled_for_epoch: now };
+    if (last === null) {
+      // First sight of this schedule: start from now. Nothing before it is a
+      // gap, because nothing before it was promised.
+      if (cronMatches(sched.cron, now, sched.tz)) spawnJob(job, root, timeoutMs);
+      continue;
+    }
+    const due = dueMinutes(sched.cron, last, now, sched.tz);
+    const missed = due.filter((t) => t !== now);
+    if (missed.length && !isPaused(dir)) {
+      const first = missed[0] * 1000;
+      const lastMissed = missed[missed.length - 1] * 1000;
+      eprintln(color.yellow(`· ${slug} — ${missed.length} scheduled run(s) missed while this was not running`));
+      writeLog(dir, job, 'skipped_offline', first, lastMissed,
+        `Computer was off or asleep. ${missed.length} run(s) due between `
+        + `${iso(first)} and ${iso(lastMissed)} did not happen.\n`);
+    }
+    if (due.includes(now)) spawnJob(job, root, timeoutMs);
+  }
+}
+
+/**
+ * Keep every `mode: listen` project up.
+ *
+ * Runs on the same 20s beat as the schedule. A listener that is not running,
+ * not paused and not stopped by hand is started through the normal job path
+ * (one run per project, the same logs); one that keeps dying young is retried
+ * on a growing delay, 5s to 60s, so a broken adapter shows up as a row of
+ * failures and not as a busy loop.
+ */
+export function listenerTick(root, timeoutMs, nowMs = Date.now(), spawn = spawnJob) {
+  const base = path.join(workspaceRoot(root), SCRIPTS_DIR);
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(base, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch { return []; }
+  const started = [];
+  for (const slug of dirs) {
+    const dir = path.join(base, slug);
+    if (readMode(dir) !== 'listen') continue;
+    if (running.has(slug) || userStopped.has(slug) || isPaused(dir)) continue;
+    if (!fs.existsSync(path.join(dir, 'main.py')) && !fs.existsSync(path.join(dir, 'main.js')) && !fs.existsSync(path.join(dir, 'main.mjs'))) continue;
+    const last = listenerExits.get(slug);
+    if (last) {
+      const delay = Math.min(60_000, 5_000 * 2 ** Math.max(0, last.exits - 1));
+      if (last.exits > 0 && nowMs - last.at < delay) continue;
+    }
+    started.push(slug);
+    spawn({ automation_id: slug, name: slug, source: 'listen', scheduled_for_epoch: Math.floor(nowMs / 1000) }, root, timeoutMs);
+  }
+  return started;
+}
+
+function startLocalSchedule(root, timeoutMs) {
+  scheduleTick(root, timeoutMs);
+  listenerTick(root, timeoutMs);
+  const t = setInterval(() => { scheduleTick(root, timeoutMs); listenerTick(root, timeoutMs); }, TICK_MS);
+  t.unref?.();
+  return () => clearInterval(t);
+}
+
+/**
+ * The owner's alerts, as a trigger (owner decision 2026-09-03: triggers kept
+ * local, like the schedule).
+ *
+ * This computer already holds one outbound stream for jobs; this is a second,
+ * to the same alert feed `atlas alerts` shows, with charts left out. When an
+ * alert fires, every project whose atlas.json `on_alert` names it runs through
+ * the same path a queued job takes, with the whole alert event as the job's
+ * payload — so a script can read what fired and ask the model what to do about
+ * it. Nothing is registered on the server: the feed was always the owner's.
+ */
+export function onAlertEvent(event, root, timeoutMs, spawn = spawnJob) {
+  if (!event || typeof event !== 'object') return [];
+  const slugs = projectsForAlert(root, event);
+  const now = Math.floor(Date.now() / 1000);
+  for (const slug of slugs) {
+    eprintln(color.dim(`⚡ ${event.label || event.name || 'alert'}${event.symbol ? ` ${event.symbol}` : ''} → ${slug}`));
+    spawn({ automation_id: slug, name: slug, source: 'alert', scheduled_for_epoch: now,
+      payload: { alert: event } }, root, timeoutMs);
+  }
+  return slugs;
+}
+
+function startAlertListener(root, timeoutMs) {
+  // Deliberately NOT awaited: it reconnects on its own for as long as the
+  // process lives, beside the jobs stream, and a computer with no on_alert
+  // projects costs the server one idle subscriber.
+  void runStream(`${API.alerts}?chart=0`, {
+    label: 'alerts',
+    reconnect: true,
+    onEvent: ({ event, payload }) => {
+      if (event === 'meta' || event === 'error') return;
+      onAlertEvent(payload, root, timeoutMs);
+    },
+  }).catch((err) => eprintln(color.dim(`● alert feed: ${err.message}`)));
+}
+
 export async function remoteControlCommand(args) {
   const flags = args.flags;
   const root = typeof flags.dir === 'string' ? flags.dir : undefined;
@@ -315,6 +543,13 @@ export async function remoteControlCommand(args) {
   eprintln(color.dim(`${computerName()} — Atlas can run jobs here. Workspace: ${workspaceRoot(root)}`));
   eprintln(color.dim('Nothing runs while this is closed. Ctrl-C to stop.'));
 
+  // The schedules are kept HERE, on this computer, and keep going whether or
+  // not the server can be reached: the stream below only carries manual runs
+  // and the web's questions.
+  const stopSchedule = startLocalSchedule(root, timeoutMs);
+  process.once('exit', stopSchedule);
+  startAlertListener(root, timeoutMs);
+
   // Identity is the machine id; the name and OS are how it is DISPLAYED. Two
   // processes on one computer therefore share one row instead of splitting it.
   const q = new URLSearchParams({ computer: computerName(), machine_id: machineId(), os: osLabel() });

package/src/config.js

@@ -2,7 +2,7 @@
 import path from 'node:path';
 import os from 'node:os';
 
-export const VERSION = '0.14.2';
+export const VERSION = '0.14.4';
 export const DEFAULT_BASE_URL = 'https://atlasmcp.finmanagerai.com';
 export const DEFAULT_SCOPE = 'atlas broker';
 export const CLIENT_NAME = 'Atlas CLI';

package/src/helpers/atlas_env.js

@@ -0,0 +1,154 @@
+// Secrets for this job. Written by Atlas — edits are overwritten.
+import fs from "node:fs";
+//
+// Values come from the environment Atlas set up before starting this script. Do
+// NOT open .env: this module is the supported way to reach a secret, and the
+// file itself is not something a script or a model needs to read.
+
+/** The value of one secret, for USE — never for printing or logging. */
+export const secret = (name, fallback) => process.env[name] ?? fallback;
+
+/** Whether a secret has been filled in. True/false only, never the value. */
+export const hasSecret = (name) => Boolean(process.env[name]);
+
+/**
+ * Call an Atlas tool over the REST API. Returns the parsed JSON.
+ *
+ * This is the way to do anything real — quotes, chains, orders, alerts. The
+ * `atlas` CLI shells out a whole process per call and hands back text to
+ * re-parse; this is one HTTPS request that returns data, which is what you
+ * actually want inside a loop over twenty tickers.
+ *
+ * The token and base URL are already in this job's environment. Do not read
+ * them, print them, or pass them anywhere else.
+ *
+ *     const quote = await atlas("stock-quote", { symbol: "SPY" });
+ */
+export async function atlas(tool, params = {}) {
+  const base = (process.env.ATLAS_BASE_URL || "https://atlasmcp.finmanagerai.com").replace(/\/+$/, "");
+  const token = process.env.ATLAS_TOKEN;
+  if (!token) throw new Error("This job has no Atlas token. Is Local Mode signed in?");
+  const res = await fetch(`${base}/api/v1/tools/${tool}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    body: JSON.stringify(params),
+  });
+  if (!res.ok) throw new Error(`Atlas ${tool} failed (${res.status}): ${(await res.text()).slice(0, 500)}`);
+  return res.json();
+}
+
+/**
+ * Ask YOUR OWN model a question and get its answer back as text.
+ *
+ * For the steps only a model can do: reading a filing and pulling out the
+ * guidance, judging whether a headline is about the company or its sector,
+ * summarising what changed since yesterday. Everything else - fetching,
+ * counting, comparing, placing orders - is faster and more reliable as plain
+ * code, so use this for judgement, not for arithmetic.
+ *
+ * It runs on this computer, through the model already connected in Atlas
+ * Remote Control. The prompt never reaches Atlas.
+ *
+ *     const verdict = await ask(`Is this headline about AAPL itself or the sector?\n${line}`);
+ *
+ * tools:true lets the model reach Atlas data while it answers; false is faster
+ * for pure text. fresh:false keeps ONE conversation for this job (the model
+ * starts up once, later questions can refer to earlier ones); fresh:true is for
+ * independent questions that should not pile into one context.
+ */
+export async function ask(prompt, { tools = true, fresh = false, timeoutMs = 600000 } = {}) {
+  const url = process.env.ATLAS_ASK_URL;
+  const token = process.env.ATLAS_ASK_TOKEN;
+  if (!url || !token) {
+    throw new Error(
+      "No model is connected on this computer, so this script cannot ask one. " +
+      "Connect a model in Atlas Remote Control, or do this step in code."
+    );
+  }
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "X-Atlas-Token": token },
+    body: JSON.stringify({ job: process.env.ATLAS_JOB || "", prompt: String(prompt), tools, fresh }),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const out = await res.json().catch(() => ({}));
+  if (!res.ok || !out.ok) throw new Error(`The model could not answer: ${out.error || res.status}`);
+  return out.answer || "";
+}
+
+/**
+ * Call a tool on one of YOUR connected MCP servers.
+ *
+ * Robinhood, Stripe, whatever is linked to the Atlas account. One credential
+ * does it: this job already carries an Atlas token, and Atlas holds the
+ * connector's own sign-in, does its handshake and keeps the session warm. The
+ * script never sees that server's credentials and never speaks JSON-RPC.
+ *
+ *     const quotes = await mcp("Robinhood", "get_equity_quotes", { symbols: ["SPY"] });
+ *
+ * Use mcpTools() to see what is connected and what each tool takes.
+ */
+export async function mcp(server, tool, args = {}) {
+  return atlas("mcp-call", { server, tool, arguments: args });
+}
+
+/**
+ * What is connected, and what each tool takes. Names and input schemas only —
+ * narrow it with `server` or `search` rather than reading a catalogue of sixty.
+ */
+export async function mcpTools({ server = "", search = "" } = {}) {
+  return atlas("mcp-tools", { server, search });
+}
+
+/**
+ * Stop cleanly when a secret has not been filled in yet.
+ *
+ * Names what is missing and nothing else: a blank key is the owner's to fill in
+ * Atlas Remote Control, not something a script should work around.
+ */
+export function require_(...names) {
+  const missing = names.filter((n) => !process.env[n]);
+  if (missing.length) {
+    console.log(`Missing: ${missing.join(", ")}. Add the value in Atlas Remote Control, then run again.`);
+    process.exit(2);
+  }
+}
+
+/**
+ * Write one CLOSED trade into this project's Performance page.
+ *
+ * Appends to trades.json beside the script; Atlas draws the equity curve, the
+ * win/loss bar and the calendar from it. Same fields as every Atlas performance
+ * row, so it looks exactly like a workflow's record:
+ *
+ *     recordTrade({ symbol: "SPY", quantity: 2, entry_price: 1.20, exit_price: 1.85,
+ *                   opened_at: "2026-09-03T13:35:00Z", closed_at: "2026-09-03T14:10:00Z",
+ *                   option_type: "CALL", strike: 560, expiration: "2026-09-05" });
+ *
+ * option_type is "CALL" / "PUT" for a contract (P&L is per 100), null for
+ * shares. pnl is worked out when not given. The first real trade replaces the
+ * example row the project started with.
+ */
+export function recordTrade(t) {
+  const mult = t.option_type ? 100 : 1;
+  const qty = Number(t.quantity || 0);
+  const entry = Number(t.entry_price || 0);
+  const exit = Number(t.exit_price || 0);
+  const pnl = t.pnl_dollars ?? Math.round((exit - entry) * qty * mult * 100) / 100;
+  const cost = Math.abs(entry * qty * mult);
+  const row = {
+    id: Math.random().toString(36).slice(2) + Date.now().toString(36),
+    symbol: String(t.symbol).toUpperCase(),
+    option_type: t.option_type ? String(t.option_type).toUpperCase() : null,
+    strike: t.strike ?? null, expiration: t.expiration ?? null, quantity: qty,
+    entry_price: entry, exit_price: exit, pnl_dollars: pnl,
+    pnl_pct: t.pnl_pct ?? (cost ? Math.round((pnl / cost) * 10000) / 100 : 0),
+    opened_at: t.opened_at, closed_at: t.closed_at,
+  };
+  let data = {};
+  try { data = JSON.parse(fs.readFileSync("trades.json", "utf8")); } catch { data = {}; }
+  const trades = (data.trades || []).filter((x) => !x.example);
+  trades.push(row);
+  fs.writeFileSync("trades.json", JSON.stringify({ trades }, null, 2));
+  return row;
+}

package/src/helpers/atlas_env.py

@@ -0,0 +1,191 @@
+"""Secrets for this job. Written by Atlas — edits are overwritten.
+
+Values come from the environment Atlas set up before starting this script. Do
+NOT open .env: this module is the supported way to reach a secret, and the file
+itself is not something a script or a model needs to read.
+"""
+import os
+import sys
+
+
+def secret(name, default=None):
+    """The value of one secret, for USE — never for printing or logging."""
+    return os.environ.get(name, default)
+
+
+def has_secret(name):
+    """Whether a secret has been filled in. True/False only, never the value."""
+    return bool(os.environ.get(name))
+
+
+def atlas(tool, **params):
+    """Call an Atlas tool over the REST API. Returns the parsed JSON.
+
+    This is the way to do anything real — quotes, chains, orders, alerts. The
+    `atlas` CLI shells out a whole process per call and hands back text to
+    re-parse; this is one HTTPS request that returns data, which is what you
+    actually want inside a loop over twenty tickers.
+
+    The token and the base URL are already in this job's environment. Do not
+    read them, print them, or pass them anywhere else.
+
+        quote = atlas("stock-quote", symbol="SPY")
+        print(quote["price"])
+    """
+    import json as _json
+    import urllib.error
+    import urllib.request
+
+    base = os.environ.get("ATLAS_BASE_URL", "https://atlasmcp.finmanagerai.com").rstrip("/")
+    token = os.environ.get("ATLAS_TOKEN", "")
+    if not token:
+        raise RuntimeError("This job has no Atlas token. Is Local Mode signed in?")
+    req = urllib.request.Request(
+        "%s/api/v1/tools/%s" % (base, tool),
+        data=_json.dumps(params).encode("utf-8"),
+        headers={"Content-Type": "application/json", "Authorization": "Bearer " + token},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=120) as r:
+            return _json.loads(r.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", "replace")[:500]
+        raise RuntimeError("Atlas %s failed (%d): %s" % (tool, e.code, body))
+
+
+def ask(prompt, tools=True, fresh=False, timeout=600):
+    """Ask YOUR OWN model a question and get its answer back as text.
+
+    For the steps only a model can do: reading a filing and pulling out the
+    guidance, judging whether a headline is about the company or its sector,
+    summarising what changed since yesterday. Everything else - fetching,
+    counting, comparing, placing orders - is faster and more reliable as plain
+    code, so use this for judgement, not for arithmetic.
+
+    It runs on this computer, through the model already connected in Atlas
+    Remote Control. The prompt never reaches Atlas.
+
+        verdict = ask("Is this headline about AAPL itself or the sector?\n" + line)
+        if "itself" in verdict.lower():
+            ...
+
+    tools=True lets the model reach Atlas data while it answers; pass
+    tools=False for pure text work, which is faster.
+
+    fresh=False keeps ONE conversation for this job, so later questions can
+    refer to earlier ones and the model starts up only once. Pass fresh=True
+    when each question is independent - twenty classifications should not pile
+    into one enormous context.
+    """
+    import json as _json
+    import urllib.error
+    import urllib.request
+
+    url = os.environ.get("ATLAS_ASK_URL", "")
+    token = os.environ.get("ATLAS_ASK_TOKEN", "")
+    if not url or not token:
+        raise RuntimeError(
+            "No model is connected on this computer, so this script cannot ask one. "
+            "Connect a model in Atlas Remote Control, or do this step in code."
+        )
+    body = {"job": os.environ.get("ATLAS_JOB", ""), "prompt": str(prompt),
+            "tools": bool(tools), "fresh": bool(fresh)}
+    req = urllib.request.Request(
+        url, data=_json.dumps(body).encode("utf-8"),
+        headers={"Content-Type": "application/json", "X-Atlas-Token": token},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            out = _json.loads(r.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        body_text = e.read().decode("utf-8", "replace")[:500]
+        try:
+            body_text = _json.loads(body_text).get("error") or body_text
+        except Exception:
+            pass
+        raise RuntimeError("The model could not answer: %s" % body_text)
+    if not out.get("ok"):
+        raise RuntimeError("The model could not answer: %s" % (out.get("error") or "unknown"))
+    return out.get("answer") or ""
+
+
+def mcp(server, tool, **arguments):
+    """Call a tool on one of YOUR connected MCP servers.
+
+    Robinhood, Stripe, whatever is linked to the Atlas account. One credential
+    does it: this job already carries an Atlas token, and Atlas holds the
+    connector's own sign-in, does its handshake and keeps the session warm. The
+    script never sees that server's credentials and never speaks JSON-RPC.
+
+        quotes = mcp("Robinhood", "get_equity_quotes", symbols=["SPY"])
+
+    Use mcp_tools() to see what is connected and what each tool takes.
+    """
+    return atlas("mcp-call", server=server, tool=tool, arguments=arguments)
+
+
+def mcp_tools(server="", search=""):
+    """What is connected, and what each tool takes.
+
+    Names and input schemas only. Narrow it with `server` or `search` rather
+    than reading a catalogue of sixty.
+    """
+    return atlas("mcp-tools", server=server or "", search=search or "")
+
+
+def require(*names):
+    """Stop cleanly when a secret has not been filled in yet.
+
+    Names what is missing and nothing else: a blank key is the owner's to fill
+    in Atlas Remote Control, not something a script should work around.
+    """
+    missing = [n for n in names if not os.environ.get(n)]
+    if missing:
+        print("Missing: %s. Add the value in Atlas Remote Control, then run again."
+              % ", ".join(missing))
+        sys.exit(2)
+
+
+def record_trade(symbol, quantity, entry_price, exit_price, opened_at, closed_at,
+                 option_type=None, strike=None, expiration=None, pnl_dollars=None, pnl_pct=None):
+    """Write one CLOSED trade into this project's Performance page.
+
+    Appends to trades.json beside the script; Atlas draws the equity curve, the
+    win/loss bar and the calendar from it. Same fields as every Atlas
+    performance row, so it looks exactly like a workflow's record:
+
+        record_trade("SPY", 2, 1.20, 1.85, "2026-09-03T13:35:00Z", "2026-09-03T14:10:00Z",
+                     option_type="CALL", strike=560, expiration="2026-09-05")
+
+    option_type is "CALL" / "PUT" for a contract (P&L is per 100), None for
+    shares. pnl is worked out when not given. The first real trade replaces the
+    example row the project started with.
+    """
+    import json as _json
+    import uuid as _uuid
+    mult = 100 if option_type else 1
+    qty = float(quantity or 0)
+    if pnl_dollars is None:
+        pnl_dollars = round((float(exit_price or 0) - float(entry_price or 0)) * qty * mult, 2)
+    if pnl_pct is None:
+        cost = abs(float(entry_price or 0) * qty * mult)
+        pnl_pct = round(pnl_dollars / cost * 100, 2) if cost else 0.0
+    row = {
+        "id": _uuid.uuid4().hex, "symbol": str(symbol).upper(),
+        "option_type": (str(option_type).upper() if option_type else None),
+        "strike": strike, "expiration": expiration, "quantity": qty,
+        "entry_price": float(entry_price or 0), "exit_price": float(exit_price or 0),
+        "pnl_dollars": pnl_dollars, "pnl_pct": pnl_pct,
+        "opened_at": opened_at, "closed_at": closed_at,
+    }
+    try:
+        data = _json.load(open("trades.json", encoding="utf-8"))
+    except Exception:
+        data = {}
+    trades = [t for t in (data.get("trades") or []) if not t.get("example")]
+    trades.append(row)
+    with open("trades.json", "w", encoding="utf-8") as fh:
+        _json.dump({"trades": trades}, fh, indent=2)
+    return row

package/src/remote-control.js

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
 import { configDir } from './config.js';
 
 /**
@@ -195,6 +196,195 @@ export function readManifest(dir) {
   }
 }
 
+// ---- the schedule, kept IN the project ---------------------------------------
+//
+// LOCAL CRON (owner decision 2026-09-03, reversing 2026-08-29). The schedule
+// lives in atlas.json on the computer that runs it, and this process keeps the
+// time; the server is not in the loop. "Make things as local as possible": a
+// project is a folder that knows how to start itself AND when. The one thing a
+// local clock cannot do is record a run the computer slept through, so the
+// ticker writes a "Computer was off" row for any gap it finds when it wakes.
+
+const CRON_RANGES = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]];
+
+/**
+ * Parse a five-field cron line into sets, or null when it is not one.
+ *
+ * Supports what people actually write: `*`, `n`, `a-b`, `* /n` (no space),
+ * `a-b/n` and comma lists. Day-of-week 7 is Sunday like 0. No names.
+ */
+export function parseCron(expr) {
+  const parts = String(expr || '').trim().split(/\s+/);
+  if (parts.length !== 5) return null;
+  const fields = [];
+  for (let i = 0; i < 5; i += 1) {
+    const set = new Set();
+    for (const piece of parts[i].split(',')) {
+      const m = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(piece);
+      if (!m) return null;
+      let [lo, hi] = CRON_RANGES[i];
+      if (m[1] !== '*') {
+        const [a, b] = m[1].split('-').map(Number);
+        lo = a; hi = b === undefined ? a : b;
+      }
+      const step = m[2] ? Number(m[2]) : 1;
+      if (!(step > 0) || lo < CRON_RANGES[i][0] || hi > CRON_RANGES[i][1] || lo > hi) return null;
+      for (let v = lo; v <= hi; v += step) set.add(i === 4 && v === 7 ? 0 : v);
+    }
+    fields.push(set);
+  }
+  return {
+    minute: fields[0], hour: fields[1], dom: fields[2], month: fields[3], dow: fields[4],
+    domStar: parts[2] === '*', dowStar: parts[4] === '*',
+  };
+}
+
+const DOW = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+
+/** The wall-clock fields of a moment in a time zone (or this machine's). */
+export function localFields(epochSec, tz) {
+  const date = new Date(epochSec * 1000);
+  let fmt = null;
+  if (tz) {
+    try {
+      fmt = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz, hour12: false, minute: 'numeric', hour: 'numeric',
+        day: 'numeric', month: 'numeric', weekday: 'short',
+      });
+    } catch { fmt = null; /* an unknown zone falls back to local time */ }
+  }
+  if (!fmt) {
+    return { minute: date.getMinutes(), hour: date.getHours(), dom: date.getDate(),
+      month: date.getMonth() + 1, dow: date.getDay() };
+  }
+  const out = {};
+  for (const part of fmt.formatToParts(date)) {
+    if (part.type === 'minute') out.minute = Number(part.value);
+    else if (part.type === 'hour') out.hour = Number(part.value) % 24;
+    else if (part.type === 'day') out.dom = Number(part.value);
+    else if (part.type === 'month') out.month = Number(part.value);
+    else if (part.type === 'weekday') out.dow = DOW[part.value] ?? 0;
+  }
+  return out;
+}
+
+/** Does this cron fire at this minute? Standard rule: when BOTH the day-of-month
+ *  and the day-of-week are restricted, either one matching is enough. */
+export function cronMatches(cron, epochSec, tz) {
+  if (!cron) return false;
+  const f = localFields(epochSec, tz);
+  if (!cron.minute.has(f.minute) || !cron.hour.has(f.hour) || !cron.month.has(f.month)) return false;
+  const domOk = cron.dom.has(f.dom);
+  const dowOk = cron.dow.has(f.dow);
+  if (cron.domStar && cron.dowStar) return true;
+  if (cron.domStar) return dowOk;
+  if (cron.dowStar) return domOk;
+  return domOk || dowOk;
+}
+
+/**
+ * Every minute in (from, to] at which the cron fires, as epoch seconds.
+ *
+ * Bounded to the last 24 hours so a laptop shut for a fortnight comes back to
+ * one honest gap row, not a loop over twenty thousand minutes.
+ */
+export function dueMinutes(cron, fromEpoch, toEpoch, tz) {
+  const out = [];
+  if (!cron) return out;
+  const end = Math.floor(toEpoch / 60) * 60;
+  let t = Math.floor(fromEpoch / 60) * 60 + 60;
+  if (t < end - 86400) t = end - 86400;
+  for (; t <= end; t += 60) if (cronMatches(cron, t, tz)) out.push(t);
+  return out;
+}
+
+/** The schedule a project declares in atlas.json, or null when it has none.
+ *  `{ expr, cron, tz, error }` — `error` names a line that could not be read,
+ *  so the owner is told instead of the project silently never running. */
+export function readSchedule(dir) {
+  const m = readManifest(dir);
+  const expr = typeof m.schedule === 'string' ? m.schedule.trim() : '';
+  if (!expr) return null;
+  const tz = typeof m.timezone === 'string' && m.timezone.trim() ? m.timezone.trim() : '';
+  const cron = parseCron(expr);
+  return { expr, cron, tz, error: cron ? null : `schedule "${expr}" is not a cron line I understand` };
+}
+
+/**
+ * How a project runs: 'once' (one pass, exits, the schedule or a trigger brings
+ * it back) or 'listen' (an ADAPTER the model wrote — a broker websocket, a
+ * webhook port the owner exposes themselves — that this computer keeps running:
+ * no run timeout, restarted when it exits, ended by Stop). Owner rule
+ * 2026-09-03: nothing passes through the Atlas server; the builder builds the
+ * adapters, so the runner has to be able to hold one open.
+ */
+export function readMode(dir) {
+  const m = readManifest(dir);
+  if (m.mode === 'listen' || m.keep_running === true) return 'listen';
+  return 'once';
+}
+
+/**
+ * The alerts a project wants to run on, from atlas.json `on_alert`.
+ *
+ * A string or a list. Each entry names an alert the owner already has: its
+ * label ("SPY DEX flip"), its id, its symbol ("SPY"), or its kind ("king_node").
+ * "*" means any alert of theirs. Matching is case-insensitive. Empty = none:
+ * the project runs on its schedule or Run now only. The server is not told
+ * about any of this; the computer listens to the owner's own alert feed and
+ * decides for itself (owner, 2026-09-03: triggers, kept local).
+ */
+export function readAlertTriggers(dir) {
+  const raw = readManifest(dir).on_alert;
+  const list = Array.isArray(raw) ? raw : (typeof raw === 'string' && raw.trim() ? [raw] : []);
+  return list.map((v) => String(v || '').trim().toLowerCase()).filter(Boolean);
+}
+
+/** Does a fired alert (the /api/v1/alerts event) match a project's on_alert list? */
+export function alertMatches(triggers, event) {
+  if (!triggers || !triggers.length || !event || typeof event !== 'object') return false;
+  const facets = [event.label, event.id, event.symbol, event.name, event.alert_type]
+    .map((v) => String(v || '').trim().toLowerCase()).filter(Boolean);
+  return triggers.some((t) => t === '*' || facets.includes(t));
+}
+
+/** Every project on this computer that wants this alert, as folder names. */
+export function projectsForAlert(root, event) {
+  const base = path.join(workspaceRoot(root), SCRIPTS_DIR);
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(base, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch { return []; }
+  return dirs.filter((slug) => alertMatches(readAlertTriggers(path.join(base, slug)), event));
+}
+
+/**
+ * What the running script last said about where it is, from the progress file
+ * the manifest names (runs/progress.json by default). Null when there is none.
+ * Clipped, typed and confined to the project: this is read for the web.
+ */
+export function readProgress(dir) {
+  const rel = readManifest(dir).progress;
+  const want = typeof rel === 'string' && rel.trim() ? rel.trim() : 'runs/progress.json';
+  const file = path.resolve(dir, want);
+  if (!file.startsWith(path.resolve(dir) + path.sep)) return null;
+  try {
+    const st = fs.statSync(file);
+    const d = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!d || typeof d !== 'object') return null;
+    const num = (v) => (Number.isFinite(Number(v)) && v !== null && v !== '' ? Number(v) : null);
+    return {
+      step: typeof d.step === 'string' ? d.step.slice(0, 200) : '',
+      done: num(d.done),
+      total: num(d.total),
+      message: typeof d.message === 'string' ? d.message.slice(0, 500) : '',
+      at: st.mtimeMs / 1000,
+    };
+  } catch {
+    return null;
+  }
+}
+
 /** The command the agent declared, split for spawning, or null. */
 export function manifestCommand(dir) {
   const run = readManifest(dir).run;
@@ -277,59 +467,16 @@ export function readEnvFile(file) {
  * changes nothing.
  */
 export function writeHelpers(dir) {
-  const py = `"""Secrets for this job. Written by Atlas — edits are overwritten.
-
-Values come from the environment Atlas set up before starting this script. Do
-NOT open .env: this module is the supported way to reach a secret, and the file
-itself is not something a script or a model needs to read.
-"""
-import os
-import sys
-
-
-def secret(name, default=None):
-    """The value of one secret, for USE — never for printing or logging."""
-    return os.environ.get(name, default)
-
-
-def has_secret(name):
-    """Whether a secret has been filled in. True/False only, never the value."""
-    return bool(os.environ.get(name))
-
-
-def require(*names):
-    """Stop cleanly when a secret has not been filled in yet."""
-    missing = [n for n in names if not os.environ.get(n)]
-    if missing:
-        print("Missing: %s. Add the value in Atlas Remote Control, then run again."
-              % ", ".join(missing))
-        sys.exit(2)
-`;
-  const js = `// Secrets for this job. Written by Atlas — edits are overwritten.
-//
-// Values come from the environment Atlas set up before starting this script. Do
-// NOT open .env: this module is the supported way to reach a secret, and the
-// file itself is not something a script or a model needs to read.
-
-/** The value of one secret, for USE — never for printing or logging. */
-export const secret = (name, fallback) => process.env[name] ?? fallback;
-
-/** Whether a secret has been filled in. True/false only, never the value. */
-export const hasSecret = (name) => Boolean(process.env[name]);
-
-/** Stop cleanly when a secret has not been filled in yet. */
-export function require_(...names) {
-  const missing = names.filter((n) => !process.env[n]);
-  if (missing.length) {
-    console.log(\`Missing: \${missing.join(", ")}. Add the value in Atlas Remote Control, then run again.\`);
-    process.exit(2);
-  }
-}
-`;
+  // ONE helper text for both CLIs. The python CLI keeps the source of truth
+  // inline (HELPER_PY / HELPER_JS in remote_control.py); these files are that
+  // text, shipped inside the npm package. They used to be a shorter copy with
+  // no ask()/atlas()/mcp(), so a script written to the build prompt failed on
+  // a computer running THIS CLI (which is every Studio install, 2026-09-03).
+  const here = path.dirname(fileURLToPath(import.meta.url));
   try {
-    fs.writeFileSync(path.join(dir, 'atlas_env.py'), py);
-    fs.writeFileSync(path.join(dir, 'atlas_env.js'), js);
-  } catch { /* a helper is a courtesy, never a failure */ }
+    fs.writeFileSync(path.join(dir, 'atlas_env.py'), fs.readFileSync(path.join(here, 'helpers', 'atlas_env.py'), 'utf8'));
+    fs.writeFileSync(path.join(dir, 'atlas_env.js'), fs.readFileSync(path.join(here, 'helpers', 'atlas_env.js'), 'utf8'));
+  } catch { /* best effort: a run without helpers still runs */ }
 }
 
 export function jobEnv(dir, root) {
@@ -581,10 +728,15 @@ export function listRuns(root, limit = 50) {
       } catch { /* mid-write */ }
       runs.push({ job, name: nm, status: 'running', started_at: started, duration_s: null, log: '' });
     }
+    // "If we come back later we see the progress" (owner, 2026-09-03): the
+    // newest row of a project carries what its progress file last said, so a
+    // run that is going shows a bar and a finished one shows where it ended.
+    const newest = runs.length;
+    const progress = readProgress(path.join(base, job));
     let files = [];
     try {
       files = fs.readdirSync(path.join(base, job, 'runs')).filter((f) => f.endsWith('.log')).sort().reverse();
-    } catch { continue; }
+    } catch { if (progress && runs[newest]) runs[newest].progress = progress; continue; }
     for (const f of files.slice(0, limit)) {
       const stem = f.replace(/\.log$/, '');
       const parts = stem.split('-');
@@ -604,6 +756,9 @@ export function listRuns(root, limit = 50) {
       } catch { /* unreadable: the filename still tells the story */ }
       runs.push({ job, name, status, started_at: Number.isFinite(started) ? started : 0, duration_s: took, log: f });
     }
+    // Only when the file was touched during or after that run: a stale bar
+    // from last week under today's row would be a lie.
+    if (progress && runs[newest] && progress.at >= runs[newest].started_at - 5) runs[newest].progress = progress;
   }
   runs.sort((a, b) => b.started_at - a.started_at);
   return runs.slice(0, limit);
@@ -713,6 +868,35 @@ export async function chatModel(prompt, onEvent, { job = '', model = '', timeout
   }
 }
 
+/**
+ * Hand the model the person's answer to a question it asked mid-turn.
+ *
+ * With "Ask before the model uses a tool" on, the bridge streams the question
+ * as a `permission` event and the model waits. The answer arrives from the web
+ * as its own ask (a stream is one-way), and this passes it to the bridge. `ok`
+ * false with a reason when nothing was waiting: the turn ended, it timed out,
+ * or the id was never asked.
+ */
+export async function answerPermission(requestId, optionId, timeoutMs = 15000) {
+  const url = process.env.ATLAS_ASK_URL;
+  const token = process.env.ATLAS_ASK_TOKEN;
+  if (!url || !token) return { ok: false, error: 'No model is connected on this computer.' };
+  if (!requestId) return { ok: false, error: 'Which question?' };
+  try {
+    const res = await fetch(url.replace('/ask', '/chat/permission'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Atlas-Token': token },
+      body: JSON.stringify({ request_id: String(requestId), option_id: optionId ?? null }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const out = await res.json().catch(() => ({}));
+    if (!res.ok || !out.ok) return { ok: false, error: out.error || `The model did not take the answer (${res.status}).` };
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: String(err?.message || err) };
+  }
+}
+
 // The starter a project gets the moment it is created, so an agent opening the
 // folder finds a shape to work in rather than an empty directory. Nothing here
 // runs: it is scaffolding, the model replaces main.* on the first build.
@@ -725,8 +909,14 @@ const STARTER_README = (name) => [
   '- `.env`           your keys. Values stay on this computer and are never read',
   '                   back by anything, including the model.',
   '- `atlas_env.py`   helpers: secret(), require(), atlas(), ask().',
-  '- `flow.md`        a diagram of what happens, written after the first build.', '',
-  'Nothing here is stored on Atlas servers.', '',
+  '- `flow.md`        a diagram of what happens, written after the first build.',
+  '- `atlas.json`     how to start it, and WHEN: `schedule` is a cron line this',
+  '                   computer keeps to. Empty = only when you press Run now.',
+  '- `runs/`          one log per run, and progress.json while it works.',
+  '- `trades.json`    the trades this project made, shown on its Performance',
+  '                   page. record_trade() in atlas_env writes one.', '',
+  'Nothing here is stored on Atlas servers. The schedule runs on this computer,',
+  'while Atlas Remote Control is open.', '',
 ].join('\n');
 
 const STARTER_MAIN = (name) => [
@@ -762,11 +952,38 @@ const STARTER_FLOW = (name) => [
 
 const STARTER_MANIFEST = JSON.stringify({
   run: '',
+  schedule: '',
+  timezone: '',
+  on_alert: [],
+  mode: 'once',
   progress: 'runs/progress.json',
   _note: 'run: how to start this project, e.g. "python main.py" or "py -3 -m mypkg". '
-    + 'Empty means Atlas looks for main.py itself. progress: a file you overwrite with '
-    + '{step, done, total, message} while you work, and Atlas draws a bar from it. '
-    + 'Neither is required.',
+    + 'Empty means Atlas looks for main.py itself. '
+    + 'schedule: WHEN to run it, as a five-field cron line kept by this computer, e.g. '
+    + '"*/5 9-16 * * 1-5" (every 5 minutes, 9am-4pm, weekdays). Empty means only when '
+    + 'someone presses Run now. timezone: the zone the schedule is read in, e.g. '
+    + '"America/New_York"; empty means this computer\'s own clock. '
+    + 'on_alert: run when one of the owner\'s Atlas alerts fires - a list of alert labels, '
+    + 'ids, symbols or kinds, or ["*"] for any; the alert arrives in $ATLAS_JOB_PAYLOAD as '
+    + '{"alert": {label, symbol, message, result, ...}}. '
+    + 'mode: "once" (default: one pass, then exit) or "listen" (an adapter that stays up - a '
+    + 'websocket, a webhook port - which this computer keeps running and restarts if it exits). '
+    + 'progress: a file you overwrite with {step, done, total, message} while you work, '
+    + 'and Atlas draws a bar from it. None of these is required.',
+}, null, 2) + '\n';
+
+// A project's Performance page starts with one EXAMPLE trade, so the model can
+// see every field it must fill and the owner sees what the page looks like
+// before anything real has happened. The first real trade replaces it.
+const STARTER_TRADES = JSON.stringify({
+  _note: 'One closed trade per row, written by record_trade() / recordTrade() in atlas_env. '
+    + 'Fields are exactly the Atlas performance row. option_type CALL/PUT for a contract '
+    + '(P&L per 100), null for shares. The example row is dropped by the first real trade.',
+  trades: [{
+    id: 'example', example: true, symbol: 'SPY', option_type: 'CALL', strike: 560, expiration: '2026-09-05',
+    quantity: 2, entry_price: 1.20, exit_price: 1.85, pnl_dollars: 130, pnl_pct: 54.17,
+    opened_at: '2026-09-03T13:35:00Z', closed_at: '2026-09-03T14:10:00Z',
+  }],
 }, null, 2) + '\n';
 
 /**
@@ -783,6 +1000,7 @@ export function starterFiles(slug) {
     ['main.py', STARTER_MAIN(slug)],
     ['flow.md', STARTER_FLOW(slug)],
     ['atlas.json', STARTER_MANIFEST],
+    ['trades.json', STARTER_TRADES],
     ['.env', '# KEY=value - one per line. Values stay on this computer.\n'],
   ];
 }

package/src/util/help.js

@@ -55,6 +55,7 @@ export function printRootHelp() {
   println(c.dim('  atlas create-task --name "Close SPY 3:55" --instruction "Close my SPY position" --schedule-times 15:55'));
   println(c.dim('  atlas run-task --task-id <id>'));
   println(c.dim('  atlas workflow-create --name "GEX signal" --schedule "30 9 * * 1-5" --tools Stock-Quote --instruction "…"'));
+  println(c.dim('  atlas workflow-create --name "FOMC day" --run-once-at "2026-09-17 14:00" --tools Stock-Quote --instruction "…"   # once, at specific dates/times; --trigger-source manual = Run now only'));
   println(c.dim('  atlas alerts --symbol SPY --name greek_exposure --save-charts ./charts'));
   println(c.dim('  atlas flow stream --symbol NVDA'));
 }