gangtise-openapi-cli 0.30.1 → 0.32.0

package/dist/src/cli.js

@@ -2,9 +2,9 @@
 import { Command, Option } from "commander";
 import { checkAsyncContent, pollAsyncContent, POLL_MAX_ATTEMPTS } from "./core/asyncContent.js";
 import { readTokenCache, redactTokenCache } from "./core/auth.js";
-import { collectKeyValue, collectList, collectNumberList, dateArg, datetimeArg, duplicateScreenerCodes, isVersionNewer, localDateString, maybeArray, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, parseScreenerIndicators, parseSize, parseTimestamp13 } from "./core/args.js";
+import { collectKeyValue, collectList, collectNumberList, dateArg, datetimeArg, screenerExpressionFields, isVersionNewer, localDateString, maybeArray, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, parseScreenerIndicators, parseSize, parseTimestamp13 } from "./core/args.js";
 import { buildIndicatorCrossSectionBody, buildIndicatorScreenerBody, buildIndicatorTimeSeriesBody, buildQuoteKlineBody, buildStockPoolStocksBody, buildWechatChatroomListBody, buildWechatMessageListBody } from "./core/commandBodies.js";
-import { droppedFromMatrix, flattenCrossSection, flattenTimeSeries, unwrapIndicatorData } from "./core/indicatorMatrix.js";
+import { checkScreenerBindings, droppedFromMatrix, flattenCrossSection, flattenTimeSeries, isEmptyMatrix, requireIndicatorMatrix, unwrapIndicatorData } from "./core/indicatorMatrix.js";
 import { callKlineWithSharding, isAllMarket, isFullMarket } from "./core/quoteSharding.js";
 import { loadConfig } from "./core/config.js";
 import { resolveTitle, saveDownloadResult, uniquePath } from "./core/download.js";
@@ -87,10 +87,10 @@ async function runDownload(client, endpointKey, query, options) {
  */
 function addDownloadCommand(parent, spec) {
     const cmd = parent.command(spec.name ?? "download").requiredOption(`${spec.idOption} <id>`);
-    if (spec.fileType?.required)
-        cmd.requiredOption("--file-type <number>", spec.fileType.description);
-    else if (spec.fileType)
-        cmd.option("--file-type <number>", spec.fileType.description, spec.fileType.default);
+    if (spec.fileType) {
+        const option = new Option("--file-type <number>", spec.fileType.description).choices(spec.fileType.choices);
+        cmd.addOption(spec.fileType.required ? option.makeOptionMandatory() : option.default(spec.fileType.default));
+    }
     if (spec.contentTypeDescription)
         cmd.requiredOption("--content-type <type>", spec.contentTypeDescription);
     cmd.option("--output <path>").action((options) => withClient(async (client) => {
@@ -116,7 +116,7 @@ function addTimeFilters(command) {
         .option("--end-time <datetime>", "End time", datetimeArg("--end-time"))
         .option("--keyword <keyword>", "Keyword");
 }
-import { setVerbose } from "./core/transport.js";
+import { isVerbose, setVerbose } from "./core/transport.js";
 import { CLI_VERSION } from "./version.js";
 const program = new Command();
 program
@@ -158,6 +158,7 @@ program.addCommand(lookup);
 const insight = new Command("insight").description("Insight APIs");
 const opinion = new Command("opinion");
 const summary = new Command("summary");
+const pamirsSummary = new Command("pamirs-summary");
 const roadshow = new Command("roadshow");
 const siteVisit = new Command("site-visit");
 const strategy = new Command("strategy");
@@ -173,19 +174,39 @@ const independentOpinion = new Command("independent-opinion");
 const officialAccount = new Command("official-account");
 const qa = new Command("qa");
 const reportImage = new Command("report-image");
-addTimeFilters(opinion.command("list").option("--rank-type <number>", "Rank type", "1").option("--research-area <id>", "Research area ID", collectList, []).option("--chief <id>", "Chief ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--concept <id>", "Concept ID", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--source <source>", "Source", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.opinion.list", {
+addTimeFilters(opinion.command("list").addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--research-area <id>", "Research area ID", collectList, []).option("--chief <id>", "Chief ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--concept <id>", "Concept ID", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--source <source>", "Source", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.opinion.list", {
     from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime,
     rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }), keyword: options.keyword, researchAreaList: maybeArray(options.researchArea), chiefList: maybeArray(options.chief),
     securityList: maybeArray(options.security), brokerList: maybeArray(options.broker), industryList: maybeArray(options.industry), conceptList: maybeArray(options.concept),
     llmTagList: maybeArray(options.llmTag), sourceList: maybeArray(options.source),
 })));
-addTimeFilters(summary.command("list").option("--search-type <number>", "Search type", "1").option("--rank-type <number>", "Rank type", "1").option("--source <number>", "Source type", collectNumberList, []).option("--research-area <id>", "Research area", collectList, []).option("--security <code>", "Security code", collectList, []).option("--institution <id>", "Institution ID", collectList, []).option("--category <name>", "Category", collectList, []).option("--market <name>", "Market", collectList, []).option("--participant-role <name>", "Participant role", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.summary.list", {
+addTimeFilters(summary.command("list").addOption(new Option("--search-type <number>", "Search type: 1=title 2=fulltext").choices(["1", "2"]).default("1")).addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--source <number>", "Source type", collectNumberList, []).option("--research-area <id>", "Research area", collectList, []).option("--security <code>", "Security code", collectList, []).option("--institution <id>", "Institution ID", collectList, []).option("--category <name>", "Category", collectList, []).option("--market <name>", "Market", collectList, []).option("--participant-role <name>", "Participant role", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.summary.list", {
     from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime,
     searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }), rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }), keyword: options.keyword, sourceList: options.source.length ? options.source : undefined,
     researchAreaList: maybeArray(options.researchArea), securityList: maybeArray(options.security), institutionList: maybeArray(options.institution),
     categoryList: maybeArray(options.category), marketList: maybeArray(options.market), participantRoleList: maybeArray(options.participantRole),
 }), { endpointKey: "insight.summary.list", idField: "summaryId" }));
-addDownloadCommand(summary, { endpointKey: "insight.summary.download", idOption: "--summary-id", idField: "summaryId", fallbackPrefix: "summary", fileType: { description: "File type: 1=original(default) 2=HTML; only affects meeting platform summaries" }, titleListEndpoint: "insight.summary.list" });
+addDownloadCommand(summary, { endpointKey: "insight.summary.download", idOption: "--summary-id", idField: "summaryId", fallbackPrefix: "summary", fileType: { description: "File type: 1=original(default) 2=HTML; only affects meeting platform summaries", choices: ["1", "2"] }, titleListEndpoint: "insight.summary.list" });
+// Pamirs is one lead institution's expert-summary library, exposed on its own
+// path rather than as a `summary list` filter. It advertises a NARROWER filter
+// set than `summary` — no --source / --institution / --participant-role — so the
+// options are spelled out here instead of sharing summary's builder: an
+// unsupported flag would be dropped server-side and silently widen the result.
+// Every enum is whitelisted locally. The server drops an unrecognised VALUE the
+// same way it drops an unrecognised FIELD — silently, returning the unfiltered
+// set with exit 0. Worse, a bad `--search-type` takes `--keyword` down with it:
+// `--keyword 茅台 --search-type 99` answers 2963 (the whole library) instead of 2,
+// so the caller reads a full-library dump as a keyword hit. Same class of defect
+// that put whitelists on securities-search / institution-search / official-account.
+const PAMIRS_CATEGORIES = ["companyAnalysis", "industryAnalysis"];
+const PAMIRS_MARKETS = ["aShares", "hkStocks", "usChinaConcept", "usStocks"];
+addTimeFilters(pamirsSummary.command("list").description("List Pamirs expert summaries (requires the expert-summary database)").addOption(new Option("--search-type <number>", "Search type: 1=title 2=fulltext").choices(["1", "2"]).default("1")).addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--research-area <id>", "Research area ID; unlike most insight lists this accepts BOTH citicIndustry (1008001xx) and swIndustry (104xx0000) codes", collectList, []).option("--security <code>", "Security code, e.g. 000001.SZ", collectList, []).option("--category <name>", `Category: ${PAMIRS_CATEGORIES.join(" / ")}`, collectList, []).option("--market <name>", `Market: ${PAMIRS_MARKETS.join(" / ")}`, collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.pamirs-summary.list", {
+    from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime,
+    searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }), rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }), keyword: options.keyword,
+    researchAreaList: maybeArray(options.researchArea), securityList: maybeArray(options.security),
+    categoryList: parseChoiceList(options.category, "--category", PAMIRS_CATEGORIES), marketList: parseChoiceList(options.market, "--market", PAMIRS_MARKETS),
+}), { endpointKey: "insight.pamirs-summary.list", idField: "summaryId" }));
+addDownloadCommand(pamirsSummary, { endpointKey: "insight.pamirs-summary.download", idOption: "--summary-id", idField: "summaryId", fallbackPrefix: "pamirs-summary", fileType: { description: "File type: 1=original(default) 2=HTML", choices: ["1", "2"] }, titleListEndpoint: "insight.pamirs-summary.list" });
 const addScheduleList = (command, endpointKey, fields) => {
     const list = command.command("list");
     if (fields.researchArea)
@@ -310,7 +331,7 @@ performanceCalendar.command("list").description("Earnings calendar (业绩预告
     }, { endpointKey: "insight.performance-calendar.list", idField: "performanceReportId" });
 });
 addDownloadCommand(performanceCalendar, { endpointKey: "insight.performance-calendar.download", idOption: "--performance-report-id", idField: "performanceReportId", fallbackPrefix: "performance-calendar", titleListEndpoint: "insight.performance-calendar.list" });
-addTimeFilters(research.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--broker <id>", "Broker ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--category <name>", "Report category", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--min-pages <number>", "Min report pages").option("--max-pages <number>", "Max report pages").option("--source <type>", "Source type", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.research.list", {
+addTimeFilters(research.command("list").addOption(new Option("--search-type <number>", "Search type: 1=title 2=fulltext").choices(["1", "2"]).default("1")).addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--broker <id>", "Broker ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--category <name>", "Report category", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--min-pages <number>", "Min report pages").option("--max-pages <number>", "Max report pages").option("--source <type>", "Source type", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.research.list", {
     from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
     searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }), rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }),
     brokerList: maybeArray(options.broker), securityList: maybeArray(options.security), industryList: maybeArray(options.industry),
@@ -318,8 +339,8 @@ addTimeFilters(research.command("list").option("--search-type <number>", "Search
     ratingChangeList: maybeArray(options.ratingChange), minReportPages: parseOptionalNumberOption(options.minPages, "--min-pages", { integer: true, min: 0 }),
     maxReportPages: parseOptionalNumberOption(options.maxPages, "--max-pages", { integer: true, min: 0 }), sourceList: maybeArray(options.source),
 }), { endpointKey: "insight.research.list", idField: "reportId" }));
-addDownloadCommand(research, { endpointKey: "insight.research.download", idOption: "--report-id", idField: "reportId", fallbackPrefix: "research", fileType: { description: "File type: 1=PDF 2=Markdown", default: "1" }, titleListEndpoint: "insight.research.list" });
-addTimeFilters(foreignReport.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code", collectList, []).option("--region <id>", "Region ID", collectList, []).option("--category <name>", "Report category", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--min-pages <number>", "Min report pages").option("--max-pages <number>", "Max report pages").option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.foreign-report.list", {
+addDownloadCommand(research, { endpointKey: "insight.research.download", idOption: "--report-id", idField: "reportId", fallbackPrefix: "research", fileType: { description: "File type: 1=PDF 2=Markdown", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.research.list" });
+addTimeFilters(foreignReport.command("list").addOption(new Option("--search-type <number>", "Search type: 1=title 2=fulltext").choices(["1", "2"]).default("1")).addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--security <code>", "Security code", collectList, []).option("--region <id>", "Region ID", collectList, []).option("--category <name>", "Report category", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--min-pages <number>", "Min report pages").option("--max-pages <number>", "Max report pages").option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.foreign-report.list", {
     from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
     searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }), rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }),
     securityList: maybeArray(options.security), regionList: maybeArray(options.region), categoryList: maybeArray(options.category),
@@ -327,21 +348,21 @@ addTimeFilters(foreignReport.command("list").option("--search-type <number>", "S
     ratingList: maybeArray(options.rating), ratingChangeList: maybeArray(options.ratingChange),
     minReportPages: parseOptionalNumberOption(options.minPages, "--min-pages", { integer: true, min: 0 }), maxReportPages: parseOptionalNumberOption(options.maxPages, "--max-pages", { integer: true, min: 0 }),
 }), { endpointKey: "insight.foreign-report.list", idField: "reportId" }));
-addDownloadCommand(foreignReport, { endpointKey: "insight.foreign-report.download", idOption: "--report-id", idField: "reportId", fallbackPrefix: "foreign-report", fileType: { description: "File type: 1=PDF 2=Markdown 3=CN-PDF 4=CN-Markdown", default: "1" }, titleListEndpoint: "insight.foreign-report.list" });
+addDownloadCommand(foreignReport, { endpointKey: "insight.foreign-report.download", idOption: "--report-id", idField: "reportId", fallbackPrefix: "foreign-report", fileType: { description: "File type: 1=PDF 2=Markdown 3=CN-PDF 4=CN-Markdown", choices: ["1", "2", "3", "4"], default: "1" }, titleListEndpoint: "insight.foreign-report.list" });
 // Contract: A-share announcement startTime/endTime go out as 13-digit epoch millis
 // (parseTimestamp13), while HK/US announcement and every other insight list send the
 // datetime string straight through. All three filter correctly — verified live against
 // a narrow past window (each returns in-window rows). A-share's API also accepts the
 // string form, but the 13-digit conversion is kept as the historical spec contract;
 // don't "unify" it away without re-confirming the A-share announcement spec.
-addTimeFilters(announcement.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code", collectList, []).option("--category <id>", "Category ID", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.announcement.list", {
+addTimeFilters(announcement.command("list").addOption(new Option("--search-type <number>", "Search type: 1=title 2=fulltext").choices(["1", "2"]).default("1")).addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--security <code>", "Security code", collectList, []).option("--category <id>", "Category ID", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.announcement.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     startTime: parseTimestamp13(options.startTime, "--start-time"), endTime: parseTimestamp13(options.endTime, "--end-time"),
     searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }), rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }), keyword: options.keyword,
     securityList: maybeArray(options.security), categoryList: maybeArray(options.category),
 }), { endpointKey: "insight.announcement.list", idField: "announcementId" }));
-addDownloadCommand(announcement, { endpointKey: "insight.announcement.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement", fileType: { description: "File type: 1=PDF 2=Markdown", default: "1" }, titleListEndpoint: "insight.announcement.list" });
-addTimeFilters(announcementHk.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code (e.g. 01913.HK)", collectList, []).option("--category <id>", "Category ID", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.announcement-hk.list", {
+addDownloadCommand(announcement, { endpointKey: "insight.announcement.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement", fileType: { description: "File type: 1=PDF 2=Markdown", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.announcement.list" });
+addTimeFilters(announcementHk.command("list").addOption(new Option("--search-type <number>", "Search type: 1=title 2=fulltext").choices(["1", "2"]).default("1")).addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--security <code>", "Security code (e.g. 01913.HK)", collectList, []).option("--category <id>", "Category ID", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.announcement-hk.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     startTime: options.startTime, endTime: options.endTime,
     searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }),
@@ -349,8 +370,8 @@ addTimeFilters(announcementHk.command("list").option("--search-type <number>", "
     keyword: options.keyword,
     securityList: maybeArray(options.security), categoryList: maybeArray(options.category),
 }), { endpointKey: "insight.announcement-hk.list", idField: "announcementId" }));
-addDownloadCommand(announcementHk, { endpointKey: "insight.announcement-hk.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement-hk", fileType: { description: "File type: 1=original 2=Markdown", default: "1" }, titleListEndpoint: "insight.announcement-hk.list" });
-addTimeFilters(announcementUs.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code (e.g. TSLA.O)", collectList, []).option("--category <id>", "Category ID (constant-list usShareAnnouncementCategory)", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.announcement-us.list", {
+addDownloadCommand(announcementHk, { endpointKey: "insight.announcement-hk.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement-hk", fileType: { description: "File type: 1=original 2=Markdown", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.announcement-hk.list" });
+addTimeFilters(announcementUs.command("list").addOption(new Option("--search-type <number>", "Search type: 1=title 2=fulltext").choices(["1", "2"]).default("1")).addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--security <code>", "Security code (e.g. TSLA.O)", collectList, []).option("--category <id>", "Category ID (constant-list usShareAnnouncementCategory)", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.announcement-us.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     startTime: options.startTime, endTime: options.endTime,
     searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }),
@@ -358,8 +379,8 @@ addTimeFilters(announcementUs.command("list").option("--search-type <number>", "
     keyword: options.keyword,
     securityList: maybeArray(options.security), categoryList: maybeArray(options.category),
 }), { endpointKey: "insight.announcement-us.list", idField: "announcementId" }));
-addDownloadCommand(announcementUs, { endpointKey: "insight.announcement-us.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement-us", fileType: { description: "File type: 1=original PDF 2=Markdown", default: "1" }, titleListEndpoint: "insight.announcement-us.list" });
-addTimeFilters(foreignOpinion.command("list").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code (e.g. UBER.N)", collectList, []).option("--region <code>", "Region code", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.foreign-opinion.list", {
+addDownloadCommand(announcementUs, { endpointKey: "insight.announcement-us.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement-us", fileType: { description: "File type: 1=original PDF 2=Markdown", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.announcement-us.list" });
+addTimeFilters(foreignOpinion.command("list").addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--security <code>", "Security code (e.g. UBER.N)", collectList, []).option("--region <code>", "Region code", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.foreign-opinion.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     startTime: options.startTime, endTime: options.endTime,
     rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }),
@@ -368,7 +389,7 @@ addTimeFilters(foreignOpinion.command("list").option("--rank-type <number>", "Ra
     securityList: maybeArray(options.security), brokerList: maybeArray(options.broker),
     ratingList: maybeArray(options.rating), ratingChangeList: maybeArray(options.ratingChange),
 })));
-addTimeFilters(independentOpinion.command("list").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code (e.g. GSK.N)", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.independent-opinion.list", {
+addTimeFilters(independentOpinion.command("list").addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--security <code>", "Security code (e.g. GSK.N)", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.independent-opinion.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     startTime: options.startTime, endTime: options.endTime,
     rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }),
@@ -376,8 +397,8 @@ addTimeFilters(independentOpinion.command("list").option("--rank-type <number>",
     industryList: maybeArray(options.industry), securityList: maybeArray(options.security),
     ratingList: maybeArray(options.rating), ratingChangeList: maybeArray(options.ratingChange),
 })));
-addDownloadCommand(independentOpinion, { endpointKey: "insight.independent-opinion.download", idOption: "--independent-opinion-id", idField: "independentOpinionId", fallbackPrefix: "independent-opinion", fileType: { description: "File type: 1=original HTML 2=CN-translated HTML", required: true } });
-addTimeFilters(officialAccount.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--account-id <id>", "Official account ID", collectList, []).option("--security <code>", "Security code (e.g. 000001.SZ)", collectList, []).option("--category <type>", "Article type: news/law/report/view/data/event/meeting/notice/recruit/investEdu/brand/notes/other", collectList, []).option("--industry <id>", "Industry ID (constant-list citicIndustry/swIndustry)", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.official-account.list", {
+addDownloadCommand(independentOpinion, { endpointKey: "insight.independent-opinion.download", idOption: "--independent-opinion-id", idField: "independentOpinionId", fallbackPrefix: "independent-opinion", fileType: { description: "File type: 1=original HTML 2=CN-translated HTML", choices: ["1", "2"], required: true } });
+addTimeFilters(officialAccount.command("list").addOption(new Option("--search-type <number>", "Search type: 1=title 2=fulltext").choices(["1", "2"]).default("1")).addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--account-id <id>", "Official account ID", collectList, []).option("--security <code>", "Security code (e.g. 000001.SZ)", collectList, []).option("--category <type>", "Article type: news/law/report/view/data/event/meeting/notice/recruit/investEdu/brand/notes/other", collectList, []).option("--industry <id>", "Industry ID (constant-list citicIndustry/swIndustry)", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.official-account.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     startTime: options.startTime, endTime: options.endTime,
     searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }),
@@ -386,7 +407,7 @@ addTimeFilters(officialAccount.command("list").option("--search-type <number>",
     accountIdList: maybeArray(options.accountId), securityList: maybeArray(options.security),
     categoryList: maybeArray(options.category), industryList: maybeArray(options.industry),
 }), { endpointKey: "insight.official-account.list", idField: "articleId" }));
-addDownloadCommand(officialAccount, { endpointKey: "insight.official-account.download", idOption: "--article-id", idField: "articleId", fallbackPrefix: "official-account", fileType: { description: "File type: 1=txt(default) 2=HTML", default: "1" }, titleListEndpoint: "insight.official-account.list" });
+addDownloadCommand(officialAccount, { endpointKey: "insight.official-account.download", idOption: "--article-id", idField: "articleId", fallbackPrefix: "official-account", fileType: { description: "File type: 1=txt(default) 2=HTML", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.official-account.list" });
 // QA request keys are BARE (source/questionCategory/answerImportant), not the *List
 // convention — the body below mirrors the spec exactly. Datetimes pass through as strings.
 qa.command("list").requiredOption("--security-code <code>", "Security code, e.g. 601012.SH").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all (max page 500)").option("--start-time <datetime>", "Start time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)", datetimeArg("--start-time")).option("--end-time <datetime>", "End time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)", datetimeArg("--end-time")).option("--source <type>", "Source: conference/interactive/survey (repeat)", collectList, []).option("--question-category <name>", "Question category (repeat): productAndBusiness/capacityAndProjects/ordersAndCustomers/financialData/materialEvents/capitalOperations/shareholdersAndDividends/corporateGovernance/marketAndValuation/macroAndIndustry/risksAndOthers", collectList, []).option("--answer-important <flag>", "Answer involves key info: 1=yes 0=no (repeat; omit for all)", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("insight.qa.list", {
@@ -402,6 +423,7 @@ reportImage.command("list").requiredOption("--keyword <text>", "Search keyword,
 addDownloadCommand(reportImage, { endpointKey: "insight.report-image.download", idOption: "--chunk-id", idField: "chunkId", fallbackPrefix: "report-image" });
 insight.addCommand(opinion);
 insight.addCommand(summary);
+insight.addCommand(pamirsSummary);
 insight.addCommand(roadshow);
 insight.addCommand(siteVisit);
 insight.addCommand(strategy);
@@ -697,21 +719,60 @@ alternative.command("edb-data").option("--indicator-id <id>", "Indicator ID (rep
 alternative.command("concept-info").requiredOption("--concept-id <id>", "Concept (theme index) ID, e.g. 121000130 机器人; discover via 'gangtise reference concept-search'").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("alternative.concept-info", { conceptId: options.conceptId })));
 alternative.command("concept-securities").requiredOption("--concept-id <id>", "Concept (theme index) ID, e.g. 121000130 机器人; discover via 'gangtise reference concept-search'").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("alternative.concept-securities", { conceptId: options.conceptId })));
 program.addCommand(alternative);
-/** Tell the caller what the server left out. EDE does not pad missing data with
- * `null`: an indicator empty for every security vanishes from `indicatorList`,
- * a security empty for every indicator vanishes from `securityCodeList` (probed
- * 2026-08-02). Without this the shortfall is invisible — exit code 0, a
- * plausible-looking table, and a `--key-by code` mapping whose key simply is not
- * there. stderr only, so piped output stays machine-readable. */
-function warnDropped(data, requestedSecurities, requestedIndicators) {
+/** Mark and report the request codes the server did not answer for at all.
+ *
+ * What this catches changed on the server. EDE used to drop any axis it had no
+ * DATA for — an indicator empty for every security vanished from
+ * `indicatorList`, a security empty for every indicator vanished from
+ * `securityCodeList`. Re-probed 2026-08-08: a coverage gap is now padded with
+ * `null` and keeps its row and column (`mgn_bal` × 00700.HK, `finc_pb_mrq` ×
+ * 09992.HK — both null, both present, even as the only cell in the request).
+ *
+ * A code the server cannot RESOLVE still vanishes: an unknown indicator code, or
+ * a security code with the wrong suffix (`AAPL.US`, whose real form is
+ * `AAPL.O`). So this is now a typo detector rather than a coverage detector —
+ * which is the more useful of the two, since a coverage gap is visible as `null`
+ * but a misspelled code is otherwise invisible: exit code 0, a plausible-looking
+ * table, and a `--key-by code` mapping whose key simply is not there.
+ *
+ * Same signal as a failed page or a row cap: `partial` on the payload (printData
+ * → exit 3) plus the omitted codes, so an automated caller can react without
+ * parsing stderr. */
+function flagDropped(rows, data, requestedSecurities, requestedIndicators) {
+    // A wholly empty response is not a partial one: the diff against the request
+    // would list everything as "omitted", which says nothing about which axis is
+    // at fault. Exit 0, but say why it is ambiguous.
+    if (isEmptyMatrix(data)) {
+        process.stderr.write("[gangtise] note: the query returned no data at all. Since a real coverage gap now comes back as a null cell rather than an empty table, this usually means NOTHING in the request resolved — every security code or every indicator code was unrecognised — or a parameter name is wrong. Cross-check codes against 'gangtise indicator search --format json' and 'gangtise reference securities-search'.\n");
+        return;
+    }
     const { securities, indicators } = droppedFromMatrix(data, requestedSecurities, requestedIndicators);
+    if (securities.length === 0 && indicators.length === 0)
+        return;
+    if (rows && typeof rows === "object" && !Array.isArray(rows)) {
+        const rec = rows;
+        rec.partial = true;
+        if (indicators.length > 0)
+            rec.omittedIndicators = indicators;
+        if (securities.length > 0)
+            rec.omittedSecurities = securities;
+    }
     const parts = [];
     if (indicators.length > 0)
         parts.push(`indicators ${indicators.join(", ")}`);
     if (securities.length > 0)
         parts.push(`securities ${securities.join(", ")}`);
-    if (parts.length > 0) {
-        process.stderr.write(`[gangtise] warning: the response omits ${parts.join(" and ")} entirely (no data for any counterpart, not null) — check scopeList coverage and the date semantics for those indicators.\n`);
+    process.stderr.write(`[gangtise] warning: the response omits ${parts.join(" and ")} entirely — no row/column at all, not a null one. A code the server merely has no data for still comes back as null, so this normally means the code itself was not recognised: check it for typos and, for securities, for the wrong market suffix (US tickers are .O/.N, not .US). Result marked partial (exit 3).\n`);
+}
+/** `--indicator` / `--security` are repeatable, so Commander cannot mark them
+ * required — but every matrix endpoint needs at least one of each and answers a
+ * missing one with 100001, whose hint sends the user to `--help`, which in turn
+ * showed them as optional with a `[]` default. Catch it here: no request, no
+ * round trip, and a message that names the flag. */
+function requireIndicatorScope(indicators, securities) {
+    const missing = [indicators.length === 0 ? "--indicator" : "", securities.length === 0 ? "--security" : ""].filter(Boolean);
+    if (missing.length > 0) {
+        throw new ValidationError(`${missing.join(" and ")} ${missing.length > 1 ? "are" : "is"} required (repeat the flag for multiple values)`);
     }
 }
 const indicator = new Command("indicator").description("Data indicator (EDE) APIs: search codes, cross-section, time-series, screener");
@@ -723,35 +784,82 @@ indicator.command("search").requiredOption("--keyword <text>", "Search keyword,
     });
     await printData(unwrapIndicatorData(raw), format, options.output);
 }));
-indicator.command("cross-section").option("--indicator <code>", "Indicator code, e.g. qte_close (repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (repeat; union, deduped)", collectList, []).requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as each indicator's tradeDate — report-period indicators need --indicator-param 'code:reportDate=...' instead", dateArg("--date")).option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectList, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode, unique & order-stable for batch code→value mapping").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+indicator.command("cross-section").option("--indicator <code>", "Indicator code, e.g. qte_close (REQUIRED, repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, []).requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as each indicator's tradeDate — the server resolves that to the enclosing report period for report-period indicators, or pass --indicator-param 'code:reportDate=...' to be explicit", dateArg("--date")).option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectList, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode, unique & order-stable for batch code→value mapping").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
+    requireIndicatorScope(options.indicator, options.security);
     const raw = await client.call("indicator.cross-section", buildIndicatorCrossSectionBody(options));
-    const data = unwrapIndicatorData(raw);
-    warnDropped(data, options.security, options.indicator);
-    await printData(flattenCrossSection(data, options.keyBy), format, options.output);
+    const data = requireIndicatorMatrix(raw);
+    // Flatten first: a shape error must not be preceded by a dropped-rows warning
+    // that reads like the run merely came back short.
+    const rows = flattenCrossSection(data, options.keyBy);
+    flagDropped(rows, data, options.security, options.indicator);
+    await printData(rows, format, options.output);
 }));
-indicator.command("time-series").option("--indicator <code>", "Indicator code, e.g. qte_close (repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (repeat; union, deduped)", collectList, []).requiredOption("--start-date <date>", "Start date (yyyy-MM-dd)", dateArg("--start-date")).requiredOption("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date")).option("--calendar-type <type>", "Calendar: ND=natural TD=trading WD=weekday (default TD)").option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectList, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode/securityCode, unique & order-stable for batch mapping").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+indicator.command("time-series").option("--indicator <code>", "Indicator code, e.g. qte_close (REQUIRED, repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, []).requiredOption("--start-date <date>", "Start date (yyyy-MM-dd)", dateArg("--start-date")).requiredOption("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date")).option("--calendar-type <type>", "Calendar: ND=natural TD=trading WD=weekday (default TD)").option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectList, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode/securityCode, unique & order-stable for batch mapping").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
+    requireIndicatorScope(options.indicator, options.security);
     const raw = await client.call("indicator.time-series", buildIndicatorTimeSeriesBody(options));
-    const data = unwrapIndicatorData(raw);
-    warnDropped(data, options.security, options.indicator);
-    // Pass the REQUESTED security count: the server drops securities with no data,
-    // and deriving the axis from the response turns a single-indicator ×
-    // two-security query into an unlabelled indicator column when one is uncovered.
-    await printData(flattenTimeSeries(data, options.keyBy, options.security.length), format, options.output);
+    const data = requireIndicatorMatrix(raw);
+    // Pass the universe itself, not a count: flattenTimeSeries needs to know
+    // whether a sector ID is in play (the server expands it, so one entry can mean
+    // many securities) and dedupes internally. The request only breaks the tie when
+    // the response is 1×1 anyway. Flatten before flagging so a shape error surfaces
+    // on its own.
+    const rows = flattenTimeSeries(data, options.keyBy, options.security);
+    flagDropped(rows, data, options.security, options.indicator);
+    await printData(rows, format, options.output);
 }));
-indicator.command("screener").description("Screen securities by an expression over indicator values (条件选股)").option("--indicator <spec>", "Bind a variable to an indicator, 'F1:code', e.g. F1:qte_mkt_cptl (repeat)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (repeat; union, deduped)", collectList, []).requiredOption("--expression <expr>", "Filter over the bound variables, e.g. 'F1 >= 800 && (F2 >= 20 && F2 <= 30)'; also supports contains/notcontains on string indicators").requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as every indicator's tradeDate unless it already has one — required because the screener drops any indicator sent with no parameters at all", dateArg("--date")).option("--indicator-param <spec>", "Per-variable param 'F1:key=value', e.g. F1:scale=8 (repeat); read exact keys from 'indicator search'", collectList, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+indicator.command("screener").description("Screen securities by an expression over indicator values (条件选股)").option("--indicator <spec>", "Bind a variable to an indicator, 'F1:code', e.g. F1:qte_mkt_cptl (REQUIRED, repeat)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, []).requiredOption("--expression <expr>", "Filter over the bound variables, e.g. 'F1 >= 800 && (F2 >= 20 && F2 <= 30)'; also supports contains/notcontains on string indicators").requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as every indicator's tradeDate unless it already has one — omitting it leaves date-bearing indicators unfiltered and silently yields an empty screen", dateArg("--date")).option("--indicator-param <spec>", "Per-variable param 'F1:key=value', e.g. F1:scale=8 (repeat); read exact keys from 'indicator search'", collectList, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
-    const duplicated = duplicateScreenerCodes(parseScreenerIndicators(options.indicator, options.indicatorParam, options.expression));
-    if (duplicated.length > 0) {
-        process.stderr.write(`[gangtise] warning: ${duplicated.join(", ")} bound to more than one variable — the API allows this but the server currently answers such a request with an empty result (probed 2026-08-02). Split into separate calls until it is fixed.\n`);
-    }
+    requireIndicatorScope(options.indicator, options.security);
+    // Binding one indicator code to several variables (the same price on two
+    // dates) is supported: the server used to answer every such binding from the
+    // EARLIEST date among them and null the rest, which made the whole result
+    // untrustworthy and needed an `unreliable` flag. Re-probed 2026-08-08 — fixed:
+    // each variable now carries its own date's value, stable across repeats.
+    const bindings = parseScreenerIndicators(options.indicator, options.indicatorParam, options.expression);
     const raw = await client.call("indicator.screener", buildIndicatorScreenerBody(options));
     // Same payload shape as cross-section (one row per matched security, one
     // column per indicator) with a `field` on each indicator entry. No dropped-row
-    // warning here: a security missing from a screener result means it failed the
+    // flag here: a security missing from a screener result means it failed the
     // filter, which is the whole point.
-    await printData(flattenCrossSection(unwrapIndicatorData(raw), options.keyBy), format, options.output);
+    const data = requireIndicatorMatrix(raw);
+    // Before anything is rendered: the returned bindings must be the ones that
+    // were asked for, and the expression must still be evaluable from the columns
+    // that came back — otherwise the rows cannot be shown to satisfy the
+    // conditions they claim to. See checkScreenerBindings for how a missing column
+    // is weighed against the expression's boolean structure.
+    // Flatten first: it asserts the payload's structural axes, and a response
+    // missing `indicatorList` outright deserves that diagnosis rather than being
+    // reported as a binding problem. Nothing renders in between, so ordering the
+    // structural check ahead of the semantic one is free.
+    const rows = flattenCrossSection(data, options.keyBy);
+    const filteredOn = screenerExpressionFields(options.expression);
+    const unbound = checkScreenerBindings(data, bindings, options.expression);
+    // Same ambiguity as the other matrix commands: an empty screen is a normal
+    // answer AND what a wrong parameter name produces. Keyed on "nothing matched"
+    // rather than the strict canonical-empty shape — a response that returns zero
+    // securities while still echoing `indicatorList` is just as empty to the
+    // caller, and just as ambiguous, but would slip past isEmptyMatrix.
+    // flattenCrossSection above already asserted this is an array of non-empty
+    // strings, so only its length is left to read.
+    if (data.securityCodeList.length === 0) {
+        process.stderr.write("[gangtise] note: nothing matched the expression. That is a normal answer — but an empty result is ALSO what an unrecognised code or a wrong parameter name produces. Cross-check the indicator codes and parameters against 'gangtise indicator search --format json'.\n");
+    }
+    if (unbound.length > 0) {
+        // Whatever reached here still leaves the expression evaluable (or was never
+        // read by it), so the rows stand: losing the column costs information, not
+        // correctness, and it degrades rather than failing.
+        const rec = rows;
+        rec.partial = true;
+        rec.omittedIndicators = unbound.map((field) => bindings.find((b) => b.field === field)?.indicatorCode ?? field);
+        const alsoFiltered = unbound.filter((field) => filteredOn.includes(field));
+        const filterNote = alsoFiltered.length > 0
+            ? ` The expression also filters on ${alsoFiltered.join(", ")}, so that condition was applied to none of these rows — another branch of the expression could still have matched them legitimately, but verify before relying on that filter.`
+            : "";
+        process.stderr.write(`[gangtise] warning: ${unbound.join(", ")} produced no column at all — those output values are missing. An indicator the server merely has no data for still returns a null column, so this normally means the bound code was not recognised; check it against 'gangtise indicator search'.${filterNote} Result marked partial (exit 3).\n`);
+    }
+    await printData(rows, format, options.output);
 }));
 program.addCommand(indicator);
 const tool = new Command("tool").description("Research tool APIs: PDF parsing");
@@ -832,12 +940,64 @@ async function checkForUpdate(timeoutMs = 2000) {
     }
     catch { /* best-effort: offline or a slow registry must not break --version */ }
 }
-// `gangtise ... | head` closes stdout early; without a handler the final big write
-// crashes Node with an unhandled 'error' event. Exit quietly like a normal CLI.
+/** Last-resort reporting for anything that escapes main()'s try/catch: an error
+ * thrown inside an event callback or a rejected promise nobody awaited. Node's
+ * default is a multi-line crash dump on stdout/stderr AND a non-zero exit — so a
+ * command whose data was already printed correctly would end up looking like a
+ * hard failure, with a stack trace where a message belongs. This release is
+ * about exit codes meaning what they say; that is the one path that lies.
+ *
+ * The stack is kept behind --verbose: reaching here at all means a CLI bug
+ * rather than an API failure, and one line is not enough to locate one. */
+/** Milliseconds to let already-queued stdout reach the pipe before leaving. */
+const FATAL_FLUSH_MS = 200;
+let leaving = false;
+function reportFatal(error) {
+    // `error.stack` already opens with "Name: message" — printing both duplicates
+    // the first line.
+    const stack = error instanceof Error ? error.stack : undefined;
+    const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    const text = `${isVerbose() && stack ? stack : message}\n`;
+    if (leaving) {
+        process.stderr.write(text);
+        return;
+    }
+    leaving = true;
+    process.exitCode = 1;
+    // Terminating is not optional: a fatal error with a live handle (a timer, an
+    // open socket) would otherwise keep the process running forever on `exitCode`
+    // alone. But `process.exit()` on the spot truncates whatever is still queued —
+    // to a pipe BOTH streams are written asynchronously — and a handler meant to
+    // stop this release from lying about exit codes must not start dropping output
+    // to do it. So wait for the diagnostic itself AND for anything stdout still
+    // owes, each bounded by the same deadline.
+    //
+    // stderr is not merely "check the length": the write is issued right here, so
+    // its callback is the only thing that knows when it actually reached the pipe.
+    // Exiting on the spot truncated a large diagnostic to one 64 KiB buffer.
+    let pending = 1;
+    const leave = () => { if (--pending === 0)
+        process.exit(1); };
+    if (process.stdout.writableLength > 0) {
+        pending++;
+        process.stdout.once("drain", leave);
+    }
+    setTimeout(() => process.exit(1), FATAL_FLUSH_MS);
+    process.stderr.write(text, leave);
+}
+process.on("uncaughtException", reportFatal);
+process.on("unhandledRejection", reportFatal);
+/** Teardown races on a closed stdout: the reader went away, which is not this
+ * process's failure. `gangtise ... | head` is the everyday case — it truncates
+ * the output and still exits 0, so a same-class race has no principled reason to
+ * exit 1. Without a handler the final write crashes Node with an unhandled
+ * 'error' event; rethrowing from this callback did the same by another route
+ * (a crash dump appended AFTER the correct JSON had already been written). */
+const READER_GONE = new Set(["EPIPE", "ERR_STREAM_DESTROYED", "EBADF"]);
 process.stdout.on("error", (error) => {
-    if (error?.code === "EPIPE")
+    if (error?.code && READER_GONE.has(error.code))
         process.exit(0);
-    throw error;
+    reportFatal(error);
 });
 async function main() {
     // Positional check, not argv.includes: "--version" appearing later (e.g. as