sentisense 0.42.0 → 0.44.0

package/README.md

@@ -56,7 +56,7 @@ Get a key at [app.sentisense.ai/get-api-key](https://app.sentisense.ai/get-api-k
 | `sentiment <ticker>` | SentiSense Score, tone, attention, per-source breakdown, `--days N` history |
 | `mood` | Composite market sentiment, the signals behind it, and the sector map |
 | `analysts <ticker>` | Consensus, price target band, recent upgrades and downgrades |
-| `earnings [ticker]` | Forward calendar with no ticker, per-quarter analysis with one |
+| `earnings [ticker]` | Forward calendar with no ticker, per-quarter analysis with one (`earnings AAPL`) |
 | `insiders <ticker>` | Filed Form 4 transactions, including whether they were pre-planned |
 | `insights <ticker>` | Generated signals, filterable by `--urgency` and `--type` |
 | `congress [ticker]` | Congressional disclosures, market-wide or for one symbol |
@@ -88,6 +88,25 @@ something supplementary does not come back, such as the Score history behind a s
 command still prints its answer and exits 0 with a `note:` line on stderr, so stdout stays
 clean for a pipe and the gap is never silent.
 
+### Saying who is calling
+
+If you set `SENTISENSE_AGENT_NAME` (what your agent is called) and `SENTISENSE_SKILL` (the
+slug of the skill driving it), requests carry that identity, so usage can be understood and
+the tools improved. Both are optional, never required, and nothing is inferred when they are
+absent.
+
+```bash
+export SENTISENSE_AGENT_NAME=research-desk
+export SENTISENSE_SKILL=stock-analysis
+npx -y sentisense@latest quote NVDA
+# User-Agent: sentisense-node/0.44.0 sentisense-cli/0.44.0 (stock-analysis; agent/research-desk)
+```
+
+Either can also be a flag (`--agent`, `--skill`) or a stored setting
+(`sentisense auth --agent research-desk --skill stock-analysis`), resolved flag first, then
+environment, then config. Values are reduced to letters, digits, dot, underscore and hyphen,
+and capped at 32 characters, so nothing you set can reshape the header.
+
 ### Exit codes
 
 Failures print two lines to stderr, what went wrong and what to do about it, and exit with a

package/dist/cli.cjs

@@ -55,8 +55,8 @@ var EXIT = {
 };
 var EXIT_TABLE = [
   [EXIT.OK, "success"],
-  [EXIT.ERROR, "API error or unexpected failure"],
-  [EXIT.USAGE, "bad usage: unknown command, flag, or missing argument"],
+  [EXIT.ERROR, "API error, including a request the API rejected as invalid"],
+  [EXIT.USAGE, "bad usage, caught before any request was sent"],
   [EXIT.AUTH, "missing or rejected API key"],
   [EXIT.NOT_FOUND, "no data for that symbol or identifier"],
   [EXIT.RATE_LIMIT, "rate limited"],
@@ -70,20 +70,27 @@ var CliUsageError = class extends Error {
     this.hint = hint;
   }
 };
+var UnknownTickerError = class extends Error {
+  constructor(ticker) {
+    super(`unknown ticker "${ticker}".`);
+    this.name = "UnknownTickerError";
+    this.ticker = ticker;
+  }
+};
 var MissingKeyError = class extends Error {
   constructor() {
     super("no API key configured.");
     this.name = "MissingKeyError";
   }
 };
-function describeError(error, debug) {
-  const report = classify(error);
+function describeError(error, debug, command) {
+  const report = classify(error, command);
   if (debug && error instanceof Error && error.stack) {
     report.lines.push(error.stack);
   }
   return report;
 }
-function classify(error) {
+function classify(error, command) {
   if (error instanceof MissingKeyError) {
     return {
       exitCode: EXIT.AUTH,
@@ -93,6 +100,15 @@ function classify(error) {
       ]
     };
   }
+  if (error instanceof UnknownTickerError) {
+    return {
+      exitCode: EXIT.NOT_FOUND,
+      lines: [
+        `error: ${error.message}`,
+        "next: check the symbol. Use canonical tickers, for example GOOGL rather than GOOG and BRK.B rather than BRK-B."
+      ]
+    };
+  }
   if (error instanceof CliUsageError) {
     return {
       exitCode: EXIT.USAGE,
@@ -140,6 +156,16 @@ function classify(error) {
         ]
       };
     }
+    if (error.status !== void 0 && error.status >= 400 && error.status < 500) {
+      const help = command ? `sentisense help ${command}` : "sentisense --help";
+      return {
+        exitCode: EXIT.ERROR,
+        lines: [
+          `error: the API rejected the request (${error.status}): ${error.message}`,
+          `next: check the flags and values you passed. Run "${help}" for the accepted fields and examples.`
+        ]
+      };
+    }
     return {
       exitCode: EXIT.ERROR,
       lines: [
@@ -158,6 +184,48 @@ function classify(error) {
   };
 }
 
+// src/cli/ticker.ts
+function rejectSurplus(args, name, allowed) {
+  if (args.positionals.length <= allowed) return;
+  throw new CliUsageError(
+    `${name} takes one ticker, and got ${args.positionals.length}.`,
+    "run it once per ticker. Only quote accepts more than one."
+  );
+}
+function oneTicker(args, name) {
+  rejectSurplus(args, name, 1);
+  const ticker = args.positionals[0];
+  if (!ticker) {
+    throw new CliUsageError(
+      `${name} needs a ticker.`,
+      `for example: sentisense ${name} NVDA`
+    );
+  }
+  return ticker.toUpperCase();
+}
+function optionalTicker(args, name) {
+  rejectSurplus(args, name, 1);
+  return args.positionals[0]?.toUpperCase();
+}
+function rejectPositionals(args, name) {
+  if (args.positionals.length === 0) return;
+  throw new CliUsageError(
+    `${name} takes no ticker, and got ${args.positionals.length}.`,
+    `run "sentisense help ${name}" for what it accepts.`
+  );
+}
+async function verifyTickerOnEmpty(api, ticker) {
+  try {
+    await api.stocks.getQuote(ticker);
+    return void 0;
+  } catch (error) {
+    if (error instanceof NotFoundError) throw new UnknownTickerError(ticker);
+    return `could not verify ${ticker}, so the empty result is unconfirmed`;
+  }
+}
+var EMPTY_VERIFY_NOTE = "An empty result verifies the ticker before reporting no data, so a typo exits 4 rather";
+var EMPTY_VERIFY_NOTE_2 = "than looking like a company with nothing to report.";
+
 // src/cli/render/doc.ts
 function cell(text, tone) {
   return tone ? { text, tone } : { text };
@@ -269,13 +337,7 @@ var analystsCommand = {
     days: { type: "number", placeholder: "N", describe: "Days of rating history (default 90)" }
   },
   async run({ args, client, full }) {
-    const ticker = args.positionals[0]?.toUpperCase();
-    if (!ticker) {
-      throw new CliUsageError(
-        "analysts needs a ticker.",
-        "for example: sentisense analysts NVDA"
-      );
-    }
+    const ticker = oneTicker(args, "analysts");
     const lookbackDays = typeof args.flags.days === "number" ? args.flags.days : void 0;
     const api = client();
     const notes = [];
@@ -383,6 +445,7 @@ function readConfig(dir) {
     const config = {};
     if (typeof raw.apiKey === "string") config.apiKey = raw.apiKey;
     if (typeof raw.agentName === "string") config.agentName = raw.agentName;
+    if (typeof raw.skill === "string") config.skill = raw.skill;
     if (typeof raw.baseUrl === "string") config.baseUrl = raw.baseUrl;
     return config;
   } catch {
@@ -412,10 +475,11 @@ function maskKey(key) {
 var authCommand = {
   name: "auth",
   summary: "Store an API key, show what is configured, or remove it",
-  usage: "sentisense auth [<key>] [--agent <name>] [--remove]",
+  usage: "sentisense auth [<key>] [--agent <name>] [--skill <slug>] [--remove]",
   examples: [
     "sentisense auth $SENTISENSE_API_KEY",
     "sentisense auth --agent research-desk",
+    "sentisense auth --skill stock-analysis --agent research-desk",
     "sentisense auth",
     "sentisense auth --remove"
   ],
@@ -423,8 +487,10 @@ var authCommand = {
     "Settings live in config.json under $SENTISENSE_CONFIG_DIR, $XDG_CONFIG_HOME/sentisense,",
     "or ~/.config/sentisense, written owner-readable only (0600).",
     "The key is never printed back in full, and never has to be pasted into a command again.",
-    "An agent name is optional. When set, it rides along in the User-Agent so your own",
-    "traffic is easy to tell apart from everything else calling the API."
+    "Two optional labels say who is calling: --agent is what your agent calls itself, and",
+    "--skill is the slug of the skill driving it. When set, they ride along in the",
+    "User-Agent, so usage can be understood and the tools improved. Both are voluntary and",
+    "nothing needs them to work."
   ],
   flags: {
     remove: { type: "boolean", describe: "Delete the stored settings" }
@@ -443,13 +509,15 @@ var authCommand = {
     }
     const key = args.positionals[0];
     const agent = typeof args.flags.agent === "string" ? args.flags.agent : void 0;
+    const skill = typeof args.flags.skill === "string" ? args.flags.skill : void 0;
     const baseUrl = typeof args.flags["base-url"] === "string" ? args.flags["base-url"] : void 0;
-    if (key || agent || baseUrl) {
+    if (key || agent || skill || baseUrl) {
       const stored2 = readConfig(dir);
       const next = {
         ...stored2,
         ...key ? { apiKey: key } : {},
         ...agent ? { agentName: agent } : {},
+        ...skill ? { skill } : {},
         ...baseUrl ? { baseUrl } : {}
       };
       writeConfig(dir, next);
@@ -458,6 +526,7 @@ var authCommand = {
           path,
           apiKey: next.apiKey ? maskKey(next.apiKey) : null,
           agentName: next.agentName ?? null,
+          skill: next.skill ?? null,
           baseUrl: next.baseUrl ?? null
         },
         doc: doc(
@@ -467,6 +536,7 @@ var authCommand = {
             items: fields(
               next.apiKey ? field("api key", maskKey(next.apiKey)) : void 0,
               next.agentName ? field("agent", next.agentName) : void 0,
+              next.skill ? field("skill", next.skill) : void 0,
               next.baseUrl ? field("base url", next.baseUrl) : void 0
             )
           }
@@ -482,6 +552,7 @@ var authCommand = {
         apiKey: resolved ? maskKey(resolved) : null,
         apiKeySource: context.apiKeySource,
         agentName: context.agentName ?? null,
+        skill: context.skill ?? null,
         baseUrl: context.baseUrl ?? null
       },
       doc: doc(
@@ -492,6 +563,7 @@ var authCommand = {
             field("source", resolved ? context.apiKeySource : "none"),
             field("config", path),
             context.agentName ? field("agent", context.agentName) : void 0,
+            context.skill ? field("skill", context.skill) : void 0,
             context.baseUrl ? field("base url", context.baseUrl) : void 0
           )
         },
@@ -519,7 +591,9 @@ var congressCommand = {
     "Disclosures are filed after the fact, so the gap between the trade date and the",
     "disclosure date is part of the picture. The delay column carries it in days.",
     "Amounts are the filed ranges, never exact figures: that is how the filings work.",
-    "A free key sees a short preview of either feed."
+    "A free key sees a short preview of either feed.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     days: { type: "number", placeholder: "N", describe: "Look-back window, 1 to 365 (default 90)" },
@@ -527,7 +601,8 @@ var congressCommand = {
   },
   async run({ args, client, full }) {
     const api = client();
-    const ticker = args.positionals[0]?.toUpperCase();
+    const ticker = optionalTicker(args, "congress");
+    const notes = [];
     const lookbackDays = typeof args.flags.days === "number" ? args.flags.days : void 0;
     const limit = typeof args.flags.limit === "number" ? args.flags.limit : void 0;
     let envelope;
@@ -546,6 +621,10 @@ var congressCommand = {
       );
     }
     const trades = envelope.data ?? [];
+    if (ticker && trades.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
     const shown = full ? trades : trades.slice(0, 20);
     const blocks = [
       {
@@ -594,7 +673,7 @@ var congressCommand = {
         tone: "dim"
       });
     }
-    return { json: envelope, doc: doc(...blocks) };
+    return { json: envelope, doc: doc(...blocks), notes };
   }
 };
 
@@ -612,14 +691,18 @@ var earningsCommand = {
   examples: [
     "sentisense earnings",
     "sentisense earnings --week next",
-    "sentisense earnings NVDA",
-    "sentisense earnings NVDA --limit 4 --full"
+    "sentisense earnings AAPL",
+    "sentisense earnings AAPL --limit 4 --full"
   ],
   notes: [
     "With no ticker this is the forward calendar: who reports, when, and the consensus EPS.",
     "With a ticker it is the backward-looking analysis: one entry per reported quarter with",
     "the editorial headline, and on a PRO key the written summary and guidance language.",
-    "A free key sees the current week of the calendar and the latest quarter of the analysis."
+    "A free key sees the current week of the calendar and the latest quarter of the analysis.",
+    "Coverage of the per-ticker analysis is not the whole market, so a tracked company can",
+    "have no stored quarter yet.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     week: { type: "string", placeholder: "this|next", describe: "Calendar window shorthand" },
@@ -630,7 +713,8 @@ var earningsCommand = {
   },
   async run({ args, client, full }) {
     const api = client();
-    const ticker = args.positionals[0]?.toUpperCase();
+    const ticker = optionalTicker(args, "earnings");
+    const notes = [];
     if (ticker) {
       const limit = typeof args.flags.limit === "number" ? args.flags.limit : void 0;
       const envelope2 = await api.earnings.getSummaries(
@@ -638,6 +722,10 @@ var earningsCommand = {
         limit === void 0 ? void 0 : { limit }
       );
       const quarters = envelope2.data ?? [];
+      if (quarters.length === 0) {
+        const note = await verifyTickerOnEmpty(api, ticker);
+        if (note) notes.push(note);
+      }
       const blocks2 = [
         {
           kind: "head",
@@ -699,7 +787,7 @@ var earningsCommand = {
           tone: "dim"
         });
       }
-      return { json: envelope2, doc: doc(...blocks2) };
+      return { json: envelope2, doc: doc(...blocks2), notes };
     }
     const week = typeof args.flags.week === "string" ? args.flags.week : void 0;
     if (week && week !== "this" && week !== "next") {
@@ -791,7 +879,9 @@ var flowsCommand = {
     "market. With a ticker it is that stock's institutional ownership and the quarter's",
     "notable position changes, since flows are only published market-wide.",
     "13F filings land up to 45 days after quarter end, so a still-open quarter shows only",
-    "early filers and says so."
+    "early filers and says so, and a ticker reads the newest quarter that has closed.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     limit: { type: "number", placeholder: "N", describe: `Rows per side (default ${DEFAULT_ROWS})` },
@@ -799,7 +889,8 @@ var flowsCommand = {
   },
   async run({ args, client, full }) {
     const api = client();
-    const ticker = args.positionals[0]?.toUpperCase();
+    const ticker = optionalTicker(args, "flows");
+    const notes = [];
     const limit = typeof args.flags.limit === "number" ? args.flags.limit : DEFAULT_ROWS;
     const quarter = typeof args.flags.quarter === "string" ? args.flags.quarter : void 0;
     if (ticker) {
@@ -820,6 +911,10 @@ var flowsCommand = {
       });
       const data2 = envelope2.data;
       const holders = data2?.holders ?? [];
+      if (holders.length === 0) {
+        const note = await verifyTickerOnEmpty(api, ticker);
+        if (note) notes.push(note);
+      }
       const blocks2 = [
         {
           kind: "head",
@@ -878,7 +973,7 @@ var flowsCommand = {
           tone: "dim"
         });
       }
-      return { json: envelope2, doc: doc(...blocks2) };
+      return { json: envelope2, doc: doc(...blocks2), notes };
     }
     const envelope = await api.institutional.getFlows(quarter, { limit });
     const data = envelope.data;
@@ -933,7 +1028,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.42.0";
+var VERSION = "0.44.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -2115,7 +2210,12 @@ var GLOBAL_FLAGS = {
   agent: {
     type: "string",
     placeholder: "name",
-    describe: "Label this call in the User-Agent"
+    describe: "Name your agent in the User-Agent, if you want to"
+  },
+  skill: {
+    type: "string",
+    placeholder: "slug",
+    describe: "Name the skill driving this call, if you want to"
   }
 };
 var SHORT_FLAGS = {
@@ -2250,6 +2350,7 @@ function resolveContext({ flags, env, configDir }) {
   const key = pick(flagString(flags, "api-key"), env.SENTISENSE_API_KEY, stored.apiKey);
   const base = pick(flagString(flags, "base-url"), env.SENTISENSE_BASE_URL, stored.baseUrl);
   const agent = pick(flagString(flags, "agent"), env.SENTISENSE_AGENT_NAME, stored.agentName);
+  const skill = pick(flagString(flags, "skill"), env.SENTISENSE_SKILL, stored.skill);
   return {
     configDir: dir,
     apiKey: key.value,
@@ -2257,21 +2358,27 @@ function resolveContext({ flags, env, configDir }) {
     baseUrl: base.value,
     baseUrlSource: base.source,
     agentName: agent.value,
-    agentSource: agent.source
+    agentSource: agent.source,
+    skill: skill.value,
+    skillSource: skill.source
   };
 }
 var DEFAULT_BASE_URL2 = "https://app.sentisense.ai";
 function effectiveBaseUrl(context) {
   return context.baseUrl ?? DEFAULT_BASE_URL2;
 }
-function sanitizeAgent(name) {
-  return name.trim().replace(/\s+/g, "-").replace(/[^A-Za-z0-9._-]/g, "");
+var MAX_IDENTITY = 32;
+function sanitizeIdentity(value) {
+  return value.trim().replace(/\s+/g, "-").replace(/[^A-Za-z0-9._-]/g, "").replace(/-{2,}/g, "-").slice(0, MAX_IDENTITY).replace(/^-+|-+$/g, "");
 }
 function userAgentSuffix(context) {
-  const parts = [`sentisense-cli/${VERSION}`];
-  const agent = context.agentName ? sanitizeAgent(context.agentName) : "";
-  if (agent) parts.push(`agent/${agent}`);
-  return parts.join(" ");
+  const product = `sentisense-cli/${VERSION}`;
+  const slug = sanitizeIdentity(context.skill ?? "");
+  const agent = sanitizeIdentity(context.agentName ?? "");
+  const comment = [];
+  if (slug) comment.push(slug);
+  if (agent) comment.push(`agent/${agent}`);
+  return comment.length === 0 ? product : `${product} (${comment.join("; ")})`;
 }
 function createClient(context, options = {}) {
   if (!options.anonymous && !context.apiKey) throw new MissingKeyError();
@@ -2312,7 +2419,8 @@ var healthCommand = {
     "Exits 3 when the key is missing or rejected, 6 when the host cannot be reached."
   ],
   flags: {},
-  async run({ context }) {
+  async run({ args, context }) {
+    rejectPositionals(args, "health");
     const baseUrl = effectiveBaseUrl(context);
     const anonymous = createClient(context, { anonymous: true });
     const reach = await probe(() => anonymous.stocks.getMarketStatus());
@@ -2382,25 +2490,27 @@ var insidersCommand = {
     "Rows are individual filed transactions, newest first, not a net total.",
     "The plan column says whether the trade was under a confirmed pre-arranged 10b5-1 plan,",
     "which is the difference between a scheduled sale and a discretionary one.",
-    "A free key sees the top few transactions; a PRO key sees the window you asked for."
+    "A free key sees the top few transactions; a PRO key sees the window you asked for.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     days: { type: "number", placeholder: "N", describe: "Look-back window, 1 to 365 (default 90)" }
   },
   async run({ args, client, full }) {
-    const ticker = args.positionals[0]?.toUpperCase();
-    if (!ticker) {
-      throw new CliUsageError(
-        "insiders needs a ticker.",
-        "for example: sentisense insiders NVDA"
-      );
-    }
+    const ticker = oneTicker(args, "insiders");
     const lookbackDays = typeof args.flags.days === "number" ? args.flags.days : void 0;
-    const envelope = await client().insider.getTrades(
+    const api = client();
+    const notes = [];
+    const envelope = await api.insider.getTrades(
       ticker,
       lookbackDays === void 0 ? void 0 : { lookbackDays }
     );
     const trades = envelope.data ?? [];
+    if (trades.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
     const shown = full ? trades : trades.slice(0, 15);
     const buys = trades.filter((trade) => trade.transactionType === "BUY");
     const sells = trades.filter((trade) => trade.transactionType === "SELL");
@@ -2451,7 +2561,7 @@ var insidersCommand = {
         tone: "dim"
       });
     }
-    return { json: envelope, doc: doc(...blocks) };
+    return { json: envelope, doc: doc(...blocks), notes };
   }
 };
 
@@ -2468,25 +2578,23 @@ var insightsCommand = {
   examples: [
     "sentisense insights NVDA",
     "sentisense insights NVDA --urgency high",
-    "sentisense insights NVDA --type insider_buy_signal --full"
+    "sentisense insights NVDA --type institutional_position_change --full"
   ],
   notes: [
     "Signals are generated observations about filings, flows, and attention, ordered by",
     "urgency then confidence. They describe what the data shows, not what to do about it.",
-    "A free key sees the top three; a PRO key sees the whole list."
+    "A free key sees the top three; a PRO key sees the whole list.",
+    "Signal types vary by ticker and over time, so take --type from what a plain run reports",
+    "rather than guessing a name.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     urgency: { type: "string", placeholder: "level", describe: "Filter to low, medium, or high" },
     type: { type: "string", placeholder: "name", describe: "Filter to one signal type" }
   },
   async run({ args, client, full }) {
-    const ticker = args.positionals[0]?.toUpperCase();
-    if (!ticker) {
-      throw new CliUsageError(
-        "insights needs a ticker.",
-        "for example: sentisense insights NVDA"
-      );
-    }
+    const ticker = oneTicker(args, "insights");
     const urgency = typeof args.flags.urgency === "string" ? args.flags.urgency : void 0;
     if (urgency && !["low", "medium", "high"].includes(urgency)) {
       throw new CliUsageError(
@@ -2498,11 +2606,17 @@ var insightsCommand = {
       ...urgency ? { urgency } : {},
       ...typeof args.flags.type === "string" ? { insightType: args.flags.type } : {}
     };
-    const envelope = await client().insights.stock(
+    const api = client();
+    const notes = [];
+    const envelope = await api.insights.stock(
       ticker,
       Object.keys(options).length > 0 ? options : void 0
     );
     const insights = envelope.data ?? [];
+    if (insights.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
     const shown = full ? insights : insights.slice(0, 8);
     const blocks = [
       {
@@ -2555,7 +2669,7 @@ var insightsCommand = {
         tone: "dim"
       });
     }
-    return { json: envelope, doc: doc(...blocks) };
+    return { json: envelope, doc: doc(...blocks), notes };
   }
 };
 
@@ -2584,7 +2698,8 @@ var moodCommand = {
     "46-55 neutral, 56-70 optimism, 71-85 greed, 86-100 extreme greed."
   ],
   flags: {},
-  async run({ client, full }) {
+  async run({ args, client, full }) {
+    rejectPositionals(args, "mood");
     const payload = await client().marketMood.get();
     const market = readMarket(payload);
     const sectors = readSectors(payload);
@@ -2669,7 +2784,9 @@ var newsCommand = {
     "A story is a cluster of articles covering the same event, not a single headline, so",
     "the size column is how many sources picked it up and impact ranks how much it moved.",
     "Tone is the average sentiment across the cluster, between -1 and 1.",
-    "--days only applies to the market-wide feed."
+    "--days only applies to the market-wide feed.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     limit: { type: "number", placeholder: "N", describe: `Stories to return (default ${DEFAULT_LIMIT})` },
@@ -2677,10 +2794,15 @@ var newsCommand = {
   },
   async run({ args, client, full }) {
     const api = client();
-    const ticker = args.positionals[0]?.toUpperCase();
+    const ticker = optionalTicker(args, "news");
+    const notes = [];
     const limit = typeof args.flags.limit === "number" ? args.flags.limit : DEFAULT_LIMIT;
     const days = typeof args.flags.days === "number" ? args.flags.days : void 0;
     const stories = ticker ? await api.documents.getStoriesByTicker(ticker, { limit }) : await api.documents.getStories({ limit, ...days === void 0 ? {} : { days } });
+    if (ticker && stories.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
     const blocks = [
       {
         kind: "head",
@@ -2738,7 +2860,7 @@ var newsCommand = {
         tone: "dim"
       });
     }
-    return { json: stories, doc: doc(...blocks) };
+    return { json: stories, doc: doc(...blocks), notes };
   }
 };
 
@@ -2766,23 +2888,25 @@ var optionsCommand = {
     "End of day, not live: readings describe the latest completed session and refresh the",
     "following morning. Percentiles are against that ticker's own trailing history, so they",
     "compare a stock to its past self, never to another stock.",
-    "Coverage is the most actively optioned names plus the tracked ETFs. A ticker outside",
-    "that set reports no coverage and exits 0, the same as any other empty result.",
+    "Coverage is the most actively optioned names plus the tracked ETFs. A real ticker",
+    "outside that set reports no coverage and exits 0, the same as any other empty result.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2,
     "A free key gets the full dossier for the first ten calls each month, then a headline",
     "preview. Calls that return no dossier do not count against that."
   ],
   flags: {},
   async run({ args, client, full }) {
-    const ticker = args.positionals[0]?.toUpperCase();
-    if (!ticker) {
-      throw new CliUsageError("options needs a ticker.", "for example: sentisense options NVDA");
-    }
-    const envelope = await client().stocks.getOptionsSummary(ticker);
+    const ticker = oneTicker(args, "options");
+    const api = client();
+    const envelope = await api.stocks.getOptionsSummary(ticker);
     const data = envelope.data;
     if (!data) {
+      const note = await verifyTickerOnEmpty(api, ticker);
       return {
         json: envelope,
-        doc: doc({ kind: "text", text: `No options coverage for ${ticker}.` })
+        doc: doc({ kind: "text", text: `No options coverage for ${ticker}.` }),
+        notes: note ? [note] : void 0
       };
     }
     const latest = data.latest ?? {};
@@ -3109,6 +3233,7 @@ var screenCommand = {
     etf: { type: "boolean", describe: "Screen the ETF universe" }
   },
   async run({ args, client, full }) {
+    rejectPositionals(args, "screen");
     const api = client();
     const etf = args.flags.etf === true;
     if (args.flags.fields === true) {
@@ -3314,13 +3439,7 @@ var sentimentCommand = {
     days: { type: "number", placeholder: "N", describe: `Days of Score history (default ${DEFAULT_DAYS})` }
   },
   async run({ args, client, full }) {
-    const ticker = args.positionals[0]?.toUpperCase();
-    if (!ticker) {
-      throw new CliUsageError(
-        "sentiment needs a ticker.",
-        "for example: sentisense sentiment NVDA"
-      );
-    }
+    const ticker = oneTicker(args, "sentiment");
     const days = typeof args.flags.days === "number" ? args.flags.days : DEFAULT_DAYS;
     if (days < 1) {
       throw new CliUsageError("--days must be at least 1.", "for example: --days 30");
@@ -3517,6 +3636,12 @@ function mainHelp() {
     "",
     'Run "sentisense help <command>" for flags, examples, and exit codes.',
     "",
+    "Saying who is calling (optional):",
+    "  SENTISENSE_AGENT_NAME=<name>   what your agent calls itself",
+    "  SENTISENSE_SKILL=<slug>        the skill driving it",
+    "  Set either and requests carry that identity, so usage can be understood and the",
+    "  tools improved. Nothing needs them, and nothing is inferred when they are absent.",
+    "",
     "Research data, not investment advice."
   ];
   return `${lines.join("\n")}
@@ -3785,7 +3910,7 @@ async function runCli(argv, io) {
     return result.exitCode ?? EXIT.OK;
   } catch (error) {
     const debug = argv.includes("--debug");
-    const report = describeError(error, debug);
+    const report = describeError(error, debug, name);
     for (const line of report.lines) io.stderr(`${line}
 `);
     return report.exitCode;