@oxygen-agent/cli 1.1014.135 → 1.1014.618

package/dist/commands/columns.js

@@ -0,0 +1,1628 @@
+import { parseKeyValuePairs, parseJsonObject, readNonNegativeInt, readPositiveInt, readRecordString } from "../cli-values.js";
+import { readColumnDecisionFlags } from "../column-decision-options.js";
+import { formatAiPromptPreviewNotice, formatColumnReferenceNotices, formatEnrichmentInputMappingNotice } from "../column-run-notices.js";
+import { collectRepeatable, parseJsonArray, parseJsonValue, readCsvOption, readFileIfPresent, readFilterSelectionOption, readFormulaValuesOption, readJsonFileValue, readNonNegativeNumber, readPositiveNumber, tableRunsListPath, waitForTableActionRun } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { runLocalCustomHttpColumn } from "../local-custom-http-column.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { AI_COLUMN_CREDITS, AI_COLUMN_WEB_SEARCH_TYPICAL_CREDITS } from "@oxygen/shared/pricing-sheet";
+import { lookupColumnDataType } from "@oxygen/shared/table-field-types";
+import { sleep } from "@oxygen/shared/timing";
+import { Command, Option } from "commander";
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+// Single-row paid runs are auto-backgrounded server-side; the CLI waits this
+// long for the cell to finish before handing back the queued run envelope.
+const SINGLE_ROW_COLUMN_RUN_WAIT_DEFAULT_TIMEOUT_SECONDS = 90;
+const SINGLE_ROW_COLUMN_RUN_WAIT_DEFAULT_INTERVAL_SECONDS = 2;
+function writeAiPromptPreviewNotice(data) {
+    const notice = formatAiPromptPreviewNotice(data);
+    if (notice)
+        process.stderr.write(`${notice}\n`);
+}
+function writeColumnReferenceNotices(data) {
+    for (const notice of [...formatColumnReferenceNotices(data), ...formatEnrichmentInputMappingNotice(data)]) {
+        process.stderr.write(`${notice}\n`);
+    }
+}
+// `--prompt <text-or-file>` on `columns add` / `columns update`, using the same
+// inline-text-or-path reader as `sourcing plan --prompt` and friends: an
+// unreadable path is the prompt itself.
+function readAiPromptOption(value) {
+    const raw = readOption(value);
+    return raw === null ? null : readFileIfPresent(raw);
+}
+// `--prompt` layers onto `--definition-json` (the escape hatch for credentialMode,
+// webSearch, promptTemplateSlug, ...) rather than replacing it. A `prompt` in both
+// is genuinely ambiguous, so it fails instead of picking a silent winner.
+/** --prompt authors an AI column; bind/lookup flags author a different kind. */
+function assertPromptNotAlsoOtherKind(prompt, flag) {
+    if (prompt === null)
+        return;
+    throw new OxygenError("invalid_request", `--prompt authors an AI column, but ${flag} authors a different column kind. Add them as separate columns.`, { exitCode: 1 });
+}
+function assertPromptNotAlsoInDefinition(definition, prompt) {
+    if (typeof definition.prompt === "string") {
+        throw new OxygenError("invalid_request", "Pass the prompt either as --prompt or as \"prompt\" inside --definition-json, not both.", { exitCode: 1 });
+    }
+    return prompt;
+}
+const AI_PROMPT_TEMPLATE_TOKEN = /{{\s*([^{}]+?)\s*}}/g;
+// Rows carry these system fields next to the workspace columns (WorkspaceTableRow
+// in packages/tenant-db), so a prompt may legitimately reference them.
+const AI_PROMPT_SYSTEM_ROW_KEYS = ["_row_id", "_created_at", "_updated_at"];
+const AI_PROMPT_AVAILABLE_COLUMNS_SHOWN = 20;
+function readAiPromptTemplateTokens(prompt) {
+    const tokens = [];
+    const seen = new Set();
+    for (const match of prompt.matchAll(AI_PROMPT_TEMPLATE_TOKEN)) {
+        const raw = (match[1] ?? "").trim();
+        if (!raw || seen.has(raw))
+            continue;
+        seen.add(raw);
+        const segments = raw.split(".").map((segment) => segment.trim()).filter(Boolean);
+        const root = segments.shift();
+        if (!root)
+            continue;
+        tokens.push({ raw, root, path: segments.length > 0 ? segments.join(".") : null });
+    }
+    return tokens;
+}
+/**
+ * The first `{{column.path}}` whose column declares fields but not that one.
+ *
+ * Author-time rather than per-row, and deliberately narrow: only a column that
+ * actually publishes `output_fields` is checked. An undeclared jsonb payload can
+ * hold anything, so rejecting a path into one would refuse references that work.
+ */
+function findUnknownColumnFieldReference(tokens, columns) {
+    for (const token of tokens) {
+        if (!token.path)
+            continue;
+        const column = (columns ?? []).find((entry) => entry.key === token.root);
+        const fields = column?.output_fields ?? null;
+        if (!fields || fields.length === 0)
+            continue;
+        const paths = fields.map((field) => field.path);
+        if (paths.includes(token.path))
+            continue;
+        // A path INTO a declared object field is fine — the declaration stops at the
+        // depth the schema described, not at the depth the payload goes.
+        if (paths.some((path) => token.path?.startsWith(`${path}.`)))
+            continue;
+        const nearMisses = nearMissColumnKeys(token.path, paths);
+        return new OxygenError("invalid_prompt_column", [
+            `Prompt references {{${token.raw}}}, but "${token.root}" has no field "${token.path}".`,
+            nearMisses.length > 0
+                ? ` Did you mean {{${token.root}.${nearMisses[0]}}}?`
+                : "",
+            ` Fields on "${token.root}": ${paths.slice(0, AI_PROMPT_AVAILABLE_COLUMNS_SHOWN).join(", ")}.`,
+        ].join(""), {
+            details: {
+                column: token.root,
+                unknown_field: token.path,
+                near_misses: nearMisses,
+                available_fields: paths,
+            },
+            exitCode: 1,
+        });
+    }
+    return null;
+}
+// Plain Levenshtein distance, capped at the short keys this is used on — enough to
+// catch the single-character and transposition typos ({{frist_name}}) the near-miss
+// hint exists for.
+function columnKeyEditDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_unused, index) => index);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+            current[j] = Math.min(substitution, previous[j] + 1, current[j - 1] + 1);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+function nearMissColumnKeys(reference, columnKeys) {
+    const needle = reference.toLowerCase();
+    // Scale the tolerance with the key length so short keys don't match everything.
+    const budget = Math.max(1, Math.floor(needle.length / 3));
+    return columnKeys
+        .map((key) => ({ key, distance: columnKeyEditDistance(needle, key.toLowerCase()) }))
+        .filter((candidate) => candidate.distance <= budget)
+        .sort((a, b) => a.distance - b.distance || a.key.localeCompare(b.key))
+        .slice(0, 3)
+        .map((candidate) => candidate.key);
+}
+/**
+ * Resolve a column definition's `{{tokens}}` against the table's live columns
+ * BEFORE the write, so a typo is one typed error instead of one failed row per
+ * row. `analyzeColumnReferences` (packages/tenant-db) is the authority and the
+ * server now rejects the same thing on every surface; this is the local
+ * pre-flight that saves a round trip and prints the near-miss hint.
+ *
+ * Scans the whole definition, not just `--prompt`: the prompt, the research
+ * query template, and every `type: "template"` input all share one grammar, and
+ * a definition pasted into `--definition-json` used to skip the check entirely.
+ * A token naming one of the column's OWN inputs resolves at run time, so those
+ * names count as known.
+ */
+async function assertColumnDefinitionReferences(table, definition) {
+    if (!isRecord(definition))
+        return;
+    const inputMapping = isRecord(definition.inputMapping) ? definition.inputMapping : {};
+    const templates = [];
+    if (typeof definition.prompt === "string")
+        templates.push(definition.prompt);
+    const webSearch = isRecord(definition.webSearch) ? definition.webSearch : {};
+    if (typeof webSearch.queryTemplate === "string")
+        templates.push(webSearch.queryTemplate);
+    for (const ref of Object.values(inputMapping)) {
+        if (isRecord(ref) && ref.type === "template" && typeof ref.value === "string") {
+            templates.push(ref.value);
+        }
+    }
+    if (templates.length === 0)
+        return;
+    await assertPromptColumnReferences(table, templates.join("\n"), Object.keys(inputMapping));
+}
+// The core of the check above. The server is authoritative — this is the local
+// pre-flight that fails before the round trip and names the near miss.
+async function assertPromptColumnReferences(table, prompt, inputNames = []) {
+    const tokens = readAiPromptTemplateTokens(prompt);
+    if (tokens.length === 0)
+        return;
+    // include_archived: an archived column is a metadata flag over a physical
+    // column that still exists, so `{{archived_key}}` still resolves at run time.
+    // Leaving them out would reject here what the server accepts — the one
+    // divergence a local pre-flight must never have.
+    const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table, include_archived: true } });
+    const columns = describe.columns ?? [];
+    const columnKeys = columns.map((column) => column.key).filter(Boolean);
+    const known = new Set([...columnKeys, ...AI_PROMPT_SYSTEM_ROW_KEYS, ...inputNames]);
+    const refs = [...new Set(tokens.map((token) => token.root))];
+    const unknown = refs.filter((ref) => !known.has(ref));
+    // A path into a column that DOES exist is checked against what that column
+    // declares it exposes, so `{{icp_fit.scoer}}` fails here rather than resolving
+    // to null on every row of a paid run. Only checked when the column actually
+    // declares fields — an undeclared jsonb payload can hold anything.
+    if (unknown.length === 0) {
+        const badPath = findUnknownColumnFieldReference(tokens, columns);
+        if (badPath)
+            throw badPath;
+        return;
+    }
+    const nearMisses = nearMissColumnKeys(unknown[0], columnKeys);
+    const shown = columnKeys.slice(0, AI_PROMPT_AVAILABLE_COLUMNS_SHOWN);
+    const overflow = columnKeys.length - shown.length;
+    throw new OxygenError(
+    // invalid_* so exitCodeForOxygenError classifies this as a validation
+    // failure (exit 2) alongside the server's invalid_column_definition.
+    "invalid_prompt_column", [
+        `Prompt references {{${unknown[0]}}}, which is not a column on table "${table}" and not one of this column's inputs.`,
+        nearMisses.length > 0
+            ? ` Did you mean ${nearMisses.map((key) => `{{${key}}}`).join(", ")}?`
+            : "",
+        ` Available columns: ${shown.join(", ") || "(none)"}${overflow > 0 ? `, +${overflow} more` : ""}.`,
+    ].join(""), {
+        details: {
+            table,
+            unknown_tokens: unknown,
+            near_misses: nearMisses,
+            available_columns: columnKeys,
+        },
+        exitCode: 1,
+    });
+}
+/**
+ * Human rendering of `columns catalog`: one line per template with the input it
+ * reads and the credits per row, grouped by family. The JSON envelope is the
+ * contract; this is what a person reads in a terminal.
+ */
+function printColumnCatalog(result) {
+    // `requestOxygen` hands back the envelope's `data` already unwrapped, so the
+    // entries sit at the top level; a wrapped envelope is accepted too. Reading
+    // only `result.data` printed "No column templates match." for every catalog
+    // that actually matched (v1.985.2–v1.987.0).
+    const data = isRecord(result) ? (isRecord(result.data) ? result.data : result) : null;
+    const entries = data && Array.isArray(data.entries) ? data.entries.filter(isRecord) : [];
+    const bundles = data && Array.isArray(data.bundles) ? data.bundles.filter(isRecord) : [];
+    // Native column kinds (Classify) are sent only by a server that runs them.
+    const native = data && Array.isArray(data.native) ? data.native.filter(isRecord) : [];
+    if (entries.length === 0 && bundles.length === 0 && native.length === 0) {
+        process.stderr.write("No column templates match. No preset bundle matches either.\n"
+            + "A template is one column (`columns add <table> --prompt-key <key>`); a bundle is a preset that creates several at once (`columns add <table> --preset <id>`).\n"
+            + "Shorten --search, drop it, or pick a section: `columns catalog --category people`.\n");
+        return;
+    }
+    const byFamily = new Map();
+    for (const entry of entries) {
+        const family = typeof entry.family === "string" ? entry.family : (typeof entry.category === "string" ? entry.category : "other");
+        const bucket = byFamily.get(family) ?? [];
+        bucket.push(entry);
+        byFamily.set(family, bucket);
+    }
+    const lines = [];
+    for (const kind of native) {
+        const credits = isRecord(kind.credit_estimate) && typeof kind.credit_estimate.label === "string" ? kind.credit_estimate.label : "";
+        lines.push(`${String(kind.label)}  [native${credits ? ` · ${credits}` : ""}]`);
+        if (typeof kind.description === "string" && kind.description)
+            lines.push(`      ${kind.description}`);
+        for (const mode of Array.isArray(kind.modes) ? kind.modes.filter(isRecord) : []) {
+            if (typeof mode.add_command === "string")
+                lines.push(`      ${mode.add_command}`);
+        }
+        if (typeof kind.review_uncertain === "string" && kind.review_uncertain)
+            lines.push(`      ${kind.review_uncertain}`);
+    }
+    if (native.length > 0 && byFamily.size > 0)
+        lines.push("");
+    for (const [family, bucket] of byFamily) {
+        lines.push(`${family.replaceAll("_", " ")}:`);
+        for (const entry of bucket) {
+            const inputs = Array.isArray(entry.inputs)
+                ? entry.inputs.filter(isRecord).map((input) => `${String(input.name)}${input.required === false ? "?" : ""}`).join(", ")
+                : "";
+            const credits = isRecord(entry.credit_estimate) && typeof entry.credit_estimate.label === "string"
+                ? entry.credit_estimate.label
+                : "";
+            lines.push(`  ${String(entry.key)}  [${String(entry.source)}${inputs ? ` · ${inputs}` : ""}]  ${credits}`);
+            if (typeof entry.description === "string" && entry.description)
+                lines.push(`      ${entry.description}`);
+        }
+    }
+    // Bundles after the templates, because a bundle is the bigger commitment (it
+    // creates several columns) and a search that matches both should read as
+    // "here is the single column, and here is the pre-built set". Before this,
+    // `columns catalog --search domain` printed nothing at all for the
+    // domain_check preset and the only surface naming it was `columns add --help`
+    // (blind user eval, 2026-09-17).
+    if (bundles.length > 0) {
+        lines.push("");
+        lines.push("Bundles (several columns at once):");
+        for (const bundle of bundles) {
+            const credits = isRecord(bundle.credit_estimate) && typeof bundle.credit_estimate.label === "string"
+                ? bundle.credit_estimate.label
+                : "";
+            const columnCount = typeof bundle.column_count === "number" ? `${bundle.column_count} columns` : "";
+            const facts = [columnCount, credits].filter(Boolean).join(" · ");
+            lines.push(`  ${String(bundle.id)}  [${String(bundle.category ?? "")}${facts ? ` · ${facts}` : ""}]`);
+            if (typeof bundle.description === "string" && bundle.description)
+                lines.push(`      ${bundle.description}`);
+            if (typeof bundle.caveat === "string" && bundle.caveat)
+                lines.push(`      ${bundle.caveat}`);
+            if (typeof bundle.add_command === "string" && bundle.add_command)
+                lines.push(`      ${bundle.add_command}`);
+        }
+    }
+    lines.push("");
+    lines.push("Prices: a fixed figure is what every row costs; `~X credits/row (up to Y)` is X when the first grounding lane answers and Y reserved per row — `columns run --dry-run` quotes Y for your rows.");
+    lines.push("Add one: oxygen columns add <table> --prompt-key <key> --input <input>=<column_key>, then `columns run <table> <key> --dry-run` for the exact cost.");
+    // The blind acceptance judge watched an agent filter this list with python3
+    // because nothing on screen said the command can narrow itself.
+    lines.push("Narrow this list: --family pricing|job_posting|events|filings|site_facts|market|portfolio|text_extraction, --category extract, --search <word>, --kind research|ai|formula. Template credits may reserve primary and fallback lanes; Classify has the fixed per-row price shown in its entry.");
+    process.stderr.write(`${lines.join("\n")}\n`);
+}
+function applyAiColumnConfig(definition, options) {
+    const model = readOption(options.model);
+    if (model)
+        definition.model = model;
+    const reasoningLevel = readOption(options.reasoningLevel);
+    if (reasoningLevel)
+        definition.reasoningLevel = reasoningLevel;
+    const runCondition = readOption(options.runCondition);
+    if (runCondition) {
+        definition.runCondition = {
+            type: "formula",
+            expression: runCondition,
+            referencedColumns: readCsvOption(options.runConditionColumns),
+        };
+    }
+    const outputSchemaJson = readOption(options.outputSchemaJson);
+    const outputSchemaFile = readOption(options.outputSchemaFile);
+    if (outputSchemaJson && outputSchemaFile) {
+        throw new OxygenError("invalid_request", "Pass either --output-schema-json or --output-schema-file, not both.", { exitCode: 1 });
+    }
+    if (outputSchemaJson) {
+        definition.outputSchema = parseJsonValue(outputSchemaJson, "--output-schema-json");
+    }
+    else if (outputSchemaFile) {
+        definition.outputSchema = readJsonFileValue(resolve(outputSchemaFile), "--output-schema-file");
+    }
+    // Only written when the flag was actually passed. Absent must stay absent: on
+    // `columns update` the definition is merged, so writing `true` by default
+    // would re-enable structure on a column the author had deliberately set to
+    // prose without ever mentioning it.
+    if (options.structuredOutput === false)
+        definition.structuredOutput = false;
+    else if (options.structuredOutput === true)
+        definition.structuredOutput = true;
+    return definition;
+}
+// Client-side mirror of the server's managed grounding rosters
+// (AI_WEB_SEARCH_ENGINES / AI_WEB_FETCH_ENGINES in @oxygen/tenant-db). Kept in
+// step by hand: if this set is wider than the server's, `--research-engine` takes
+// a value the server then rejects; if it is narrower, the CLI blocks an engine
+// that works. D52 took parallel and linkup to BYOK and moved firecrawl off the
+// search rail onto scraping only.
+//
+// Restored 2026-09-21: b152df38b (a Dashboards CLI change) rebased a 295-line
+// addition over a stale copy of this file and silently reverted both sets to the
+// pre-D52 values, so dev shipped a CLI that accepted `--research-engine parallel`
+// and let the server reject it. `research-engine-roster.test.ts` now asserts
+// these against the tenant-db unions so the next stale rebase fails the gate
+// instead of reaching a customer.
+const RESEARCH_DEPTHS = new Set(["quick", "standard", "deep"]);
+// A quick research row pays the tier's model price plus the typical grounding
+// read; derived from the pricing sheet so a re-price cannot orphan the help.
+function quickResearchRowCredits(level) {
+    return Math.round((AI_COLUMN_CREDITS[level] + AI_COLUMN_WEB_SEARCH_TYPICAL_CREDITS) * 10) / 10;
+}
+const REASONING_LEVEL_OPTION_HELP = "AI column reasoning level: low, medium, or high (shown in the web UI as Oxygen Fast, Oxygen Balanced, and Oxygen Max). "
+    + `On a research column it applies only at --research-depth quick (typical row: low about ${quickResearchRowCredits("low")}, `
+    + `medium about ${quickResearchRowCredits("medium")}, high about ${quickResearchRowCredits("high")} credits); standard and deep choose their own tier and ignore it.`;
+const RESEARCH_DEPTH_OPTION_HELP = "Research columns: how hard each row searches. quick: one search and one page read (about 2.1 credits/row on the default tier; --reasoning-level applies to quick only). standard: the agent plans a few searches and page reads on Oxygen Fast (about 5.5; the default for new columns). deep: more searches and subpages on Oxygen Balanced (about 10). Standard and deep cost the same whatever --reasoning-level says. Each row reserves a higher maximum; `columns run --dry-run` quotes this column's typical and max.";
+/** `--research-depth`, validated before the round trip; null when not passed. */
+function readResearchDepthOption(value) {
+    const depth = readOption(value)?.toLowerCase();
+    if (!depth)
+        return null;
+    if (!RESEARCH_DEPTHS.has(depth)) {
+        throw new OxygenError("invalid_request", `--research-depth must be quick, standard or deep (got ${depth}).`, { exitCode: 1 });
+    }
+    return depth;
+}
+const RESEARCH_ENGINES = new Set(["serper", "exa"]);
+const RESEARCH_FETCH_ENGINES = new Set(["firecrawl", "exa"]);
+const RESEARCH_MODES = new Set(["strict", "estimate"]);
+/**
+ * Fold the `--research-*` flags into `definition.webSearch`.
+ *
+ * Only keys the user actually passed are written: the server fills engine,
+ * evidence mode, and result count, so an untouched research column stays on
+ * Oxygen's defaults rather than freezing today's values into the definition.
+ */
+function applyResearchColumnConfig(definition, options) {
+    const existing = isRecord(definition.webSearch) ? definition.webSearch : {};
+    // Supply the required default only when absent. Preserving an explicit false
+    // lets the server reject it instead of silently turning paid web access on.
+    const webSearch = { ...existing };
+    if (!Object.hasOwn(webSearch, "enabled"))
+        webSearch.enabled = true;
+    const queryTemplate = readOption(options.researchQuery);
+    if (queryTemplate)
+        webSearch.queryTemplate = queryTemplate;
+    const allowedDomains = readCsvOption(options.researchDomains);
+    if (allowedDomains.length > 0)
+        webSearch.allowedDomains = allowedDomains;
+    const excludedDomains = readCsvOption(options.researchExcludeDomains);
+    if (excludedDomains.length > 0)
+        webSearch.excludedDomains = excludedDomains;
+    const mode = readOption(options.researchMode)?.toLowerCase();
+    if (mode) {
+        if (!RESEARCH_MODES.has(mode)) {
+            throw new OxygenError("invalid_request", `--research-mode must be strict or estimate (got ${mode}).`, { exitCode: 1 });
+        }
+        webSearch.evidenceMode = mode;
+    }
+    // Fetch mode: the column reads one page per row instead of searching. The
+    // URL column is a row column key (the same thing a {{token}} would name), so
+    // the server can reject a typo at write time instead of once per row.
+    const researchUrl = readOption(options.researchUrl);
+    if (researchUrl) {
+        if (readOption(options.researchQuery)) {
+            throw new OxygenError("invalid_request", "--research-url reads one page per row, so --research-query does not apply. Drop one of the two.", { exitCode: 1 });
+        }
+        webSearch.source = "fetch";
+        webSearch.urlInput = researchUrl;
+    }
+    const engine = readOption(options.researchEngine)?.toLowerCase();
+    if (engine) {
+        const allowed = researchUrl ? RESEARCH_FETCH_ENGINES : RESEARCH_ENGINES;
+        if (!allowed.has(engine)) {
+            throw new OxygenError("invalid_request", researchUrl
+                ? `--research-engine with --research-url must be firecrawl or exa (got ${engine}).`
+                : `--research-engine must be serper or exa (got ${engine}).`, { exitCode: 1 });
+        }
+        webSearch.engine = engine;
+    }
+    const results = readOption(options.researchResults);
+    if (results) {
+        const parsed = Number(results);
+        if (!Number.isInteger(parsed) || parsed < 1 || parsed > 25) {
+            throw new OxygenError("invalid_request", `--research-results must be a whole number from 1 to 25 (got ${results}).`, { exitCode: 1 });
+        }
+        webSearch.maxResults = parsed;
+        webSearch.maxTotalResults = parsed;
+    }
+    definition.webSearch = webSearch;
+    return definition;
+}
+// Parse a `--bind-map identity=column,identity2=column2` value into an
+// inputMapping of column refs. Server-side normalizeBindColumnDefinition also
+// accepts a bare column-key string, but we emit the explicit ref shape so the
+// wire payload is self-describing. Full JSON control stays available via
+// --definition-json.
+function parseBindMapOption(value) {
+    const mapping = {};
+    for (const entry of readCsvOption(value)) {
+        const separator = entry.indexOf("=");
+        if (separator <= 0 || separator === entry.length - 1) {
+            throw new OxygenError("invalid_bind_map", "--bind-map entries must be identity=column pairs, e.g. domain=website,linkedin_url=li.", { details: { entry }, exitCode: 1 });
+        }
+        const identity = entry.slice(0, separator).trim();
+        const columnKey = entry.slice(separator + 1).trim();
+        mapping[identity] = { type: "column", columnKey };
+    }
+    return mapping;
+}
+// `columns add` bind sugar: assemble the { version, object, inputMapping,
+// onNoMatch } definition from --bind-object / --bind-map / --bind-create. The API
+// column normalizer does all validation (identity slugs, ref shapes); the CLI only
+// marshals. --definition-json remains the escape hatch for createValues /
+// minConfidence / runCondition.
+function applyBindColumnConfig(definition, options) {
+    definition.version = 1;
+    const object = readOption(options.bindObject);
+    if (object)
+        definition.object = object;
+    const mapping = parseBindMapOption(options.bindMap);
+    if (Object.keys(mapping).length > 0) {
+        const existing = isRecord(definition.inputMapping) ? definition.inputMapping : {};
+        definition.inputMapping = { ...existing, ...mapping };
+    }
+    if (options.bindCreate)
+        definition.onNoMatch = "create";
+    return definition;
+}
+const LOOKUP_NORMALIZE_ALIASES = {
+    exact: "exact",
+    "lower-trim": "lower_trim",
+    lower_trim: "lower_trim",
+    email: "email_v1",
+    domain: "domain_v1",
+    linkedin: "linkedin_url_v1",
+};
+const LOOKUP_MODE_ALIASES = {
+    "first-match": "first_match",
+    first_match: "first_match",
+    count: "count",
+    exists: "exists",
+    aggregate: "aggregate",
+};
+// Parse `--lookup-match localColumn=sourceColumn` into its two halves (LHS is the
+// working-row column, RHS the source table's join column).
+function parseLookupMatchOption(value) {
+    const trimmed = readOption(value);
+    if (!trimmed)
+        return null;
+    const separator = trimmed.indexOf("=");
+    if (separator <= 0 || separator === trimmed.length - 1) {
+        throw new OxygenError("invalid_lookup_match", "--lookup-match must be localColumn=sourceColumn, e.g. company_domain=domain.", { details: { value: trimmed }, exitCode: 1 });
+    }
+    return { localColumn: trimmed.slice(0, separator).trim(), sourceColumn: trimmed.slice(separator + 1).trim() };
+}
+function parseLookupNormalizeOption(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return null;
+    const mapped = LOOKUP_NORMALIZE_ALIASES[raw.trim().toLowerCase()];
+    if (!mapped) {
+        throw new OxygenError("invalid_lookup_normalize", "--lookup-normalize must be exact, lower-trim, email, domain, or linkedin.", { details: { value: raw }, exitCode: 1 });
+    }
+    return mapped;
+}
+function parseLookupModeOption(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return null;
+    const mapped = LOOKUP_MODE_ALIASES[raw.trim().toLowerCase()];
+    if (!mapped) {
+        throw new OxygenError("invalid_lookup_mode", "--lookup-mode must be first-match, count, exists, or aggregate.", { details: { value: raw }, exitCode: 1 });
+    }
+    return mapped;
+}
+function parseLookupOrderOption(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return null;
+    const separator = raw.indexOf(":");
+    const column = (separator === -1 ? raw : raw.slice(0, separator)).trim();
+    const directionRaw = (separator === -1 ? "asc" : raw.slice(separator + 1)).trim().toLowerCase();
+    if (!column || (directionRaw !== "asc" && directionRaw !== "desc")) {
+        throw new OxygenError("invalid_lookup_order", "--lookup-order must be column or column:asc|desc, e.g. created_at:desc.", { details: { value: raw }, exitCode: 1 });
+    }
+    return { column, direction: directionRaw };
+}
+function parseLookupAggregateOption(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return null;
+    const separator = raw.indexOf(":");
+    if (separator <= 0 || separator === raw.length - 1) {
+        throw new OxygenError("invalid_lookup_aggregate", "--lookup-aggregate must be fn:column, e.g. sum:amount.", { details: { value: raw }, exitCode: 1 });
+    }
+    const fn = raw.slice(0, separator).trim().toLowerCase();
+    const column = raw.slice(separator + 1).trim();
+    if (fn !== "sum" && fn !== "avg" && fn !== "min" && fn !== "max") {
+        throw new OxygenError("invalid_lookup_aggregate", "--lookup-aggregate fn must be sum, avg, min, or max.", { details: { value: raw }, exitCode: 1 });
+    }
+    return { fn, column };
+}
+// `columns add` lookup sugar: assemble the { version, sourceTable, match,
+// inputMapping, mode, returnColumns, orderBy, aggregate } definition from the
+// --lookup-* flags. The API column normalizer does all validation (mode-specific
+// requirements, self-lookup, ref shapes); the CLI only marshals. --definition-json
+// remains the escape hatch for runCondition and literal match_value refs.
+function applyLookupColumnConfig(definition, options) {
+    definition.version = 1;
+    const sourceTable = readOption(options.lookupTable);
+    if (sourceTable)
+        definition.sourceTable = sourceTable;
+    const match = parseLookupMatchOption(options.lookupMatch);
+    const normalization = parseLookupNormalizeOption(options.lookupNormalize);
+    if (match || normalization) {
+        const existingMatch = isRecord(definition.match) ? definition.match : {};
+        definition.match = {
+            ...existingMatch,
+            ...(match ? { sourceColumn: match.sourceColumn } : {}),
+            ...(normalization ? { normalization } : {}),
+        };
+    }
+    if (match) {
+        definition.inputMapping = { match_value: { type: "column", columnKey: match.localColumn } };
+    }
+    const mode = parseLookupModeOption(options.lookupMode);
+    if (mode)
+        definition.mode = mode;
+    const returnColumns = readCsvOption(options.lookupReturn);
+    if (returnColumns.length > 0)
+        definition.returnColumns = returnColumns;
+    const orderBy = parseLookupOrderOption(options.lookupOrder);
+    if (orderBy)
+        definition.orderBy = orderBy;
+    const aggregate = parseLookupAggregateOption(options.lookupAggregate);
+    if (aggregate)
+        definition.aggregate = aggregate;
+    return definition;
+}
+// `--options a,b,c` or `--options-json '[...]'`: a choice column's option list in
+// the shape the server's `options` field takes (strings or {value,label,color}).
+function readColumnOptionsFlags(options) {
+    const csv = readOption(options.options);
+    const json = readOption(options.optionsJson);
+    if (csv && json) {
+        throw new OxygenError("invalid_request", "Pass --options or --options-json, not both.", { exitCode: 1 });
+    }
+    if (json)
+        return parseJsonArray(json);
+    if (!csv)
+        return null;
+    return csv.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+function hasLookupColumnFlags(options) {
+    return Boolean(readOption(options.lookupTable)
+        || readOption(options.lookupMatch)
+        || readOption(options.lookupNormalize)
+        || readOption(options.lookupMode)
+        || readOption(options.lookupReturn)
+        || readOption(options.lookupOrder)
+        || readOption(options.lookupAggregate));
+}
+async function readStoredColumnForUpdate(table, column) {
+    const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table, include_archived: true } });
+    const stored = (describe.columns ?? []).find((entry) => entry.key === column || entry.id === column);
+    if (!stored) {
+        throw new OxygenError("column_not_found", `Column ${column} was not found on ${table}.`, {
+            details: { table, column },
+            exitCode: 1,
+        });
+    }
+    return stored;
+}
+function storedDefinitionCopy(stored) {
+    return isRecord(stored.definition) ? structuredClone(stored.definition) : {};
+}
+function pickDefinitionKeys(definition, keys) {
+    return Object.fromEntries(keys.filter((key) => definition[key] !== undefined).map((key) => [key, definition[key]]));
+}
+// `columns update --lookup-*`: the same flags as `columns add`, applied over the
+// stored lookup so a partial edit (only the normalization, only the mode) keeps
+// the rest of the join. A new source table needs its own join column.
+function lookupDefinitionEdit(stored, options) {
+    if (stored.kind !== "lookup") {
+        throw new OxygenError("invalid_request", `--lookup-* flags edit a lookup column, and ${stored.key} is a ${stored.kind ?? "plain"} column.`, { details: { column: stored.key, kind: stored.kind ?? null }, exitCode: 1 });
+    }
+    if (readOption(options.lookupTable) && !readOption(options.lookupMatch)) {
+        throw new OxygenError("invalid_request", "--lookup-table changes the source table, so pass --lookup-match localColumn=sourceColumn with it: the join column belongs to the source table.", { exitCode: 1 });
+    }
+    const next = applyLookupColumnConfig(storedDefinitionCopy(stored), options);
+    return pickDefinitionKeys(next, ["version", "sourceTable", "match", "inputMapping", "mode", "returnColumns", "orderBy", "aggregate"]);
+}
+// `columns update --bind-*`: applied over the stored binding; --bind-map adds or
+// changes identities and keeps the others (`--input-mapping` replaces them all).
+function bindDefinitionEdit(stored, options) {
+    if (stored.kind !== "bind") {
+        throw new OxygenError("invalid_request", `--bind-* flags edit a bind column, and ${stored.key} is a ${stored.kind ?? "plain"} column.`, { details: { column: stored.key, kind: stored.kind ?? null }, exitCode: 1 });
+    }
+    const next = applyBindColumnConfig(storedDefinitionCopy(stored), options);
+    if (options.bindCreate === false)
+        next.onNoMatch = "none";
+    return pickDefinitionKeys(next, ["version", "object", "inputMapping", "onNoMatch"]);
+}
+async function requestColumnsRun(body, table, options) {
+    const traceId = randomUUID();
+    let result;
+    try {
+        result = await requestOxygen("/api/cli/tables/columns/run", {
+            method: "POST",
+            body,
+            traceId,
+        });
+    }
+    catch (error) {
+        // Paid runs are durable background runs server-side (even single-row since
+        // v1.144.0), so a network timeout is always recoverable by locating the
+        // created run via its trace id - not only when --background was passed.
+        // Inline (formula) runs have no run to recover; recovery returns null and
+        // the original error propagates.
+        if (!isNetworkTimeoutError(error))
+            throw error;
+        const recovered = await recoverBackgroundColumnRun(table, traceId);
+        if (!recovered)
+            throw error;
+        return recovered;
+    }
+    // "Run this cell" still resolves to the finished value in one command: when
+    // the server auto-backgrounds a single-row paid run (caller did not pass
+    // --background), wait for the created run and attach its item output.
+    // Inline (formula) results carry no action_run_id and pass through as-is.
+    if (!options.background && typeof body.row_id === "string" && isRecord(result)) {
+        const actionRunId = readRecordString(result, "action_run_id");
+        if (actionRunId) {
+            writeSingleRowColumnRunReceipt(result, actionRunId);
+            return resolveSingleRowColumnRun(result, actionRunId);
+        }
+    }
+    return result;
+}
+// The durable run exists before the convenience auto-wait begins. Emit its
+// receipt on stderr immediately so strict JSON stdout remains one envelope while
+// a shell/agent timeout can still recover the charged run instead of reporting
+// a silent failure with no inspectable id.
+function writeSingleRowColumnRunReceipt(envelope, actionRunId) {
+    const webUrl = readRecordString(envelope, "web_url")
+        ?? readRecordString(envelope, "run_web_url");
+    const inspection = webUrl ? ` (${webUrl})` : "";
+    process.stderr.write(`queued: column run ${actionRunId}${inspection}\n`);
+    process.stderr.write(`hint: if this process stops, continue with oxygen table-runs wait ${actionRunId}\n`);
+}
+/**
+ * Wait for an auto-backgrounded single-row column run to finish and return the
+ * terminal run merged with its item output (the cell value). On wait timeout
+ * the queued run envelope is returned unchanged, plus the follow-up command -
+ * the run keeps executing server-side either way.
+ */
+async function resolveSingleRowColumnRun(envelope, actionRunId) {
+    const timeoutSeconds = readEnvPositiveInt("OXYGEN_COLUMN_RUN_WAIT_TIMEOUT_SECONDS")
+        ?? SINGLE_ROW_COLUMN_RUN_WAIT_DEFAULT_TIMEOUT_SECONDS;
+    const intervalSeconds = readEnvPositiveInt("OXYGEN_COLUMN_RUN_WAIT_INTERVAL_SECONDS")
+        ?? SINGLE_ROW_COLUMN_RUN_WAIT_DEFAULT_INTERVAL_SECONDS;
+    let waited;
+    try {
+        waited = await waitForTableActionRun(actionRunId, {
+            timeoutSeconds: String(timeoutSeconds),
+            intervalSeconds: String(intervalSeconds),
+        });
+    }
+    catch (error) {
+        if (error instanceof OxygenError && error.code === "table_action_run_wait_timeout") {
+            return {
+                ...envelope,
+                auto_wait_timed_out: true,
+                next_step: `oxygen table-runs wait ${actionRunId}`,
+            };
+        }
+        throw error;
+    }
+    const finalRun = isRecord(waited.actionRun) ? waited.actionRun : envelope;
+    const items = await listColumnRunItems(actionRunId);
+    return {
+        ...finalRun,
+        ...(items ? { items } : {}),
+        auto_waited: {
+            polls: waited.polls,
+            elapsed_ms: waited.elapsedMs,
+        },
+    };
+}
+async function listColumnRunItems(actionRunId) {
+    try {
+        const response = await requestOxygen(`/api/cli/table-action-runs/${encodeURIComponent(actionRunId)}/items?limit=5`);
+        const items = Array.isArray(response.items) ? response.items.filter(isRecord) : [];
+        return items.length > 0 ? items : null;
+    }
+    catch {
+        // The terminal run state is the answer; item output is best-effort.
+        return null;
+    }
+}
+function readEnvPositiveInt(name) {
+    const value = process.env[name]?.trim();
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed >= 1 ? parsed : undefined;
+}
+async function recoverBackgroundColumnRun(table, traceId) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const listed = await requestOxygen(tableRunsListPath({ table, status: "active", limit: "5", traceId }), { timeoutMs: 30_000 });
+        const runs = Array.isArray(listed.runs)
+            ? listed.runs.filter(isRecord)
+            : [];
+        const run = runs[0];
+        if (run) {
+            const actionRunId = readRecordString(run, "action_run_id") ?? readRecordString(run, "id");
+            const workspaceRunId = readRecordString(run, "workspace_run_id") ?? readRecordString(run, "runId");
+            return {
+                ...run,
+                ...(actionRunId ? { action_run_id: actionRunId } : {}),
+                ...(workspaceRunId ? { workspace_run_id: workspaceRunId } : {}),
+                timeout_recovered: true,
+                recovery: {
+                    reason: "columns_run_background_timeout",
+                    trace_id: traceId,
+                    lookup_command: `oxygen table-runs list --table ${table} --status active --json`,
+                },
+            };
+        }
+        if (attempt < 2)
+            await sleep(750);
+    }
+    return null;
+}
+function isNetworkTimeoutError(error) {
+    return error instanceof OxygenError && error.code === "network_timeout";
+}
+// `columns reorder` accepts either an absolute --position or a relative
+// --before/--after naming a sibling column. The relative form is resolved
+// client-side into an absolute index against the table's current column order
+// (fetched via /api/cli/tables/describe — the same describe the other column
+// commands read) so the server only ever receives a single numeric position.
+// Exactly one of the three flags must be supplied.
+async function resolveColumnReorderPosition(table, column, options) {
+    const before = readOption(options.before);
+    const after = readOption(options.after);
+    const explicit = readNonNegativeInt(options.position);
+    const provided = [explicit !== undefined, Boolean(before), Boolean(after)].filter(Boolean).length;
+    if (provided === 0) {
+        throw new OxygenError("invalid_request", "Provide --position <n>, --before <column>, or --after <column>.", { exitCode: 1 });
+    }
+    if (provided > 1) {
+        throw new OxygenError("invalid_request", "Pass only one of --position, --before, or --after.", { exitCode: 1 });
+    }
+    if (explicit !== undefined)
+        return explicit;
+    const reference = (before ?? after);
+    const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table } });
+    const columns = describe.columns ?? [];
+    const index = columns.findIndex((candidate) => candidate.id === reference || candidate.key === reference);
+    if (index < 0) {
+        throw new OxygenError("invalid_request", `Column "${reference}" was not found on table "${table}".`, { details: { table, column: reference }, exitCode: 1 });
+    }
+    // --before lands the column at the reference's index; --after lands it one slot later.
+    const target = before ? index : index + 1;
+    // The server removes the source column before splicing it back in at `target`.
+    // When the source currently sits before the reference, that removal shifts the
+    // reference (and everything after it) down one slot, so decrement to compensate.
+    const sourceIndex = columns.findIndex((candidate) => candidate.id === column || candidate.key === column);
+    if (sourceIndex >= 0 && sourceIndex < index) {
+        return target - 1;
+    }
+    return target;
+}
+export function registerColumnsFamily(program, handleAsyncAction) {
+    program
+        .command("columns")
+        .description("Workspace table column commands. Price first: `tools search --for-table <table>` lists every enrichment this table's columns support with its credit cost per row (0 credits). Ready-made templates (pricing pages, job posts, event pages, 10-Ks, website facts, market questions, text extraction, plus free 0-credit cleanups — company names, job titles, email type, text to list; person questions over an enriched LinkedIn profile and person appearances; company research questions — founders, parent company, funding, cloud provider, offers demos, industry, NAICS, HQ and footprint, LinkedIn/Crunchbase/careers page lookups): `columns catalog`, then `columns add <table> --prompt-key <key> --input <name>=<column>`. Column choice guide: the oxygen-tables skill (`oxygen skills get oxygen-tables --json`); enrichment presets and waterfalls: the oxygen-enrichment skill. With --json parse stdout only: the envelope is stdout, and the spend and cost notes (`estimated N credits for a live run`) are stderr, so merging the streams breaks the JSON.")
+        .addCommand(new Command("add")
+        .description("Add a nullable column, a catalog template (--prompt-key) or a multi-column enrichment bundle (--preset) to a workspace table. Writes the definition only — this never runs the column and never spends credits; use `columns run` for that, with --dry-run first to see the cost. For a page, posting or filing the row already links to, or a company fact Oxygen already knows how to research (founders, parent company, funding, cloud provider, offers demos, industry, NAICS, HQ, a LinkedIn or Crunchbase page), pick a template from `columns catalog` (--prompt-key) instead of writing a prompt; or read a URL column with --kind research --research-url. The guide is the oxygen-tables skill (`oxygen skills get oxygen-tables --json`). For ICP fit, use Classify Score: `columns add <table> --label 'ICP fit' --score 'low,medium,high' --prompt 'Assess {{company_name}}: {{description}}, {{employees}} employees' --grounding workspace` (0.075 credits/row). A formula column needs no run at all: it evaluates on read from its current inputs, so `tables query` shows its values immediately. A plain field is --type: text, number, checkbox, date, json, markdown, image, or a choice column — select, multi_select or status, with --options \"Lead,Contacted,Won\". To link another table row to row, use `oxygen tables relate <table> --to <other-table> --live`; to read a value out of one, --lookup-table.")
+        .argument("<table>", "Table id or slug.")
+        .option("--preset <preset>", "Add a pre-built column bundle instead of one column, which is what --prompt-key adds: a preset writes SEVERAL columns at once and needs no --input on a table whose identity column it can find, while --prompt-key adds one template column and binds each input you name. Presets: `person_enrich` (one LinkedIn profile lookup — Blitz first, the LinkedIn Scraper only when Blitz has no match — then first/last/full name, current company and its LinkedIn URL, job title, start date, education, school, headline, bio, location and followers as free stored fields that fill when the lookup runs, followers only on rows the LinkedIn Scraper answers because Blitz publishes none; the person templates in `columns catalog --category people` all read its payload column), `company_enrich` (one company lookup from a domain or LinkedIn URL — Blitz first, the LinkedIn Scraper only when Blitz has no match, about 1 credit a company — keeping the whole profile in its JSON column plus name, domain, LinkedIn URL, headcount, industry, description, founded year and HQ country as free stored fields; no field choices; binds to the person preset's current_company_linkedin_url automatically), `company_tech_stack` (the technologies a company runs, from its website and hiring), `company_funding` (total raised, latest round, number of rounds and investors), `company_revenue` (an annual revenue estimate), `company_hiring` (the roles a company is hiring for, with a count) — each of these four is one paid lookup column that fills its own columns, priced per row in `tools search --for-table` — plus `company_lookalikes` (one managed lookup from --input company_domain=website; keeps similar companies separate from the seed; dry-run for price) — or `domain_check` (1 credit/row for a live/redirect/parked/not_found/dead verdict on every domain, cached 30 days, plus a free label column to filter on). For a single cleaned or classified column, use a template from `columns catalog` instead — that is one column, not a bundle. Name the input column with --input: `url` for person_enrich, `domain` and/or `linkedin_url` for the company presets. Any column works whatever it is called; without --input Oxygen guesses from column names. Creating the columns is free; run them afterwards, --dry-run first.")
+        .option("--input <slot=column...>", "Bind a preset or template input to an exact column, e.g. --input url=pricing_url with --prompt-key, or --input domain=website --input linkedin_url=company_li with --preset. Repeatable. For a preset it is only needed when the automatic match is wrong or missing; for a template it names the column each declared input reads.", collectRepeatable, [])
+        // No preset takes a field list any more (founder, 2026-09-24). Hidden,
+        // not removed: an old script passing them gets the server's refusal,
+        // which names the funding, revenue, hiring and tech-stack presets,
+        // instead of an unknown-option error that explains nothing.
+        .addOption(new Option("--preset-fields <fields>", "Retired: presets take no field list.").hideHelp())
+        .addOption(new Option("--check-technologies <names>", "Retired: presets take no field list.").hideHelp())
+        .option("--kind <kind>", "Column kind: manual, research (the Web Research Agent), ai, formula, enrichment, tool, bind, or lookup. Defaults to manual. Use research for anything you would look up on the web (an AI column cannot search; `columns convert --to agent` turns one into an agent); one research column answers several fields at once when its prompt names them as sections — one row, one read, one charge — so never add a second column for the same page. Enrichment columns always hold a jsonb cell, and --data-type is set for you \u2014 use --capability to seed a ready-to-run one. `lookup` reads a value out of another table; to LINK two tables row-to-row use `oxygen tables relate` instead \u2014 relation columns are two-sided and cannot be added here.")
+        // Research flags sit directly under --kind: agents read help with head/tail,
+        // and the depth choice (and its price) must land on the first screen.
+        .option("--research-depth <depth>", RESEARCH_DEPTH_OPTION_HELP)
+        .option("--research-url <column_key>", "Research columns: read the ONE page whose URL is in this column for each row instead of searching the web — a pricing page, a job posting, an event page, a 10-K. The page's content is the only evidence, the answer cites it as its source, and the row costs the fetch plus the model (see --dry-run). A URL ending in .pdf is read by the PDF-capable fetch lane first.")
+        .option("--capability <capability>", "Seed a ready-to-run enrichment column WITHOUT running it (0 credits): verify_email grades the address a row already holds \u2014 MillionVerifier first, catch-all domains escalate to BounceBan; work_email, mobile_phone and linkedin_url find a value the row is missing through the managed waterfall. For a personal (non-work) email add --include-personal-email to work_email: one column finds both (personal_email alone still works for existing scripts). Sets kind=enrichment and jsonb; label and key default from the capability. Inputs are mapped from this table's columns; the response names any it could not find and the command that maps it. Preview cost with `enrich-column preview --capability <same>` and run later with `enrich-column run --approved --max-credits <n>`.")
+        .option("--include-personal-email", "With --capability work_email: also find the person's personal (non-work) email from their LinkedIn URL, billed only on a hit and graded before it is written, into the same cell's personal_email.")
+        .option("--label <label>", "Display label for the new column. Required unless --prompt-key or --capability supplies a default title.")
+        .option("--key <key>", "Optional stable column key. Defaults to a normalized label.")
+        .option("--data-type <type>", "Column data type: text, numeric, boolean, jsonb, or timestamptz.")
+        .option("--research-query <template>", "Research columns: the per-row web search query, templated like the prompt (e.g. \"{{company_name}} pricing page\"). Omit to derive the query from the row's values and the prompt.")
+        .option("--research-domains <csv>", "Research columns: comma-separated domains to search within, e.g. techcrunch.com,sec.gov. Omit to search the whole web.")
+        .option("--research-exclude-domains <csv>", "Research columns: comma-separated domains to exclude from results.")
+        .option("--research-mode <mode>", "Research columns: how tightly the answer is bound to the sources. Default: summarize and combine what they say. strict: answer only from what a source states verbatim (for figures and identifiers). estimate: reason to a figure from the evidence (for revenue or headcount).")
+        .option("--research-results <n>", "Research columns: how many search results to ground each row on (1-25, default 5). More evidence costs no extra search, but a larger prompt.")
+        .option("--research-engine <engine>", "Research columns: pin the search provider (serper or exa), or with --research-url the page-fetch provider (firecrawl or exa). Defaults to serper for search and firecrawl for fetch, falling back automatically. Most users should not set this.")
+        .option("--type <type>", "Field type, the web picker's names: text, number, checkbox, date, json, markdown, image, select, multi_select or status. Sets kind manual with the matching data and semantic type (multi_select stores jsonb); text/number/checkbox/date/json also work as a data type beside --kind.")
+        .option("--options <choices>", "Choices for a select, multi_select or status column, comma-separated, in display order, e.g. \"Lead,Contacted,Replied,Won\". Each value is what a cell stores; colors are assigned. Use --options-json for labels or colors.")
+        .option("--options-json <json>", "Choices as a JSON array of strings or {value,label?,color?} objects (colors: gray, red, orange, amber, yellow, green, teal, blue, indigo, purple, pink). value is what a cell stores; label is what the grid shows.")
+        .option("--description <text>", "A note on the column, shown in its header and the column editor.")
+        .option("--semantic-type <type>", "Optional semantic type: a display hint such as company.domain or person.email, or a choice type (select, multi_select, status) — --type sets those for you.")
+        .option("--definition-json <json>", "Optional JSON object with column definition metadata. Required for --kind formula as a flat object: {\"expression\":\"trim(company_name)\"}. Check the expression with `formulas validate` first.")
+        .option("--prompt <text-or-file>", "AI or research column prompt, or a path to a prompt file — a value that resolves to a readable file is read as one, matching --prompt everywhere else in this CLI. On its own it sets kind=ai; pair it with --kind research to make it a Web Research Agent that searches the web per row. If the prompt names its output sections — a line reading 'Return the following sections:' followed by 'Score: ...', 'Reasoning: ...' — the column answers in exactly that shape and each section becomes a referenceable sub-column; otherwise it answers in plain text. Use --no-structured-output to keep it plain text either way. Reference other columns inline as {{column_key}} — no --input-mapping needed; unknown keys are rejected here instead of failing per row. Merges into --definition-json (the escape hatch for everything else); a `prompt` in both is an error.")
+        .option("--prompt-key <key>", "Add a column template from `oxygen columns catalog` (e.g. pricing_plan_summary_v1 reads a pricing-page URL column and returns plan count, price range and enterprise plan; company_founders_v1 reads a domain column and returns the founders with sources; person_skill_set_v1 reads the person_enrich payload column with --input profile=person_enrich). Materializes the template's prompt, output schema and grounding and sets its kind (ai, research, formula, or search — a managed web search whose cell is a page URL). Bind each declared input with --input <name>=<column_key>.")
+        .option("--input-mapping <json>", "JSON alternative to --input for --prompt-key: an object mapping template input names to columns, e.g. '{\"url\":{\"column\":\"pricing_url\"}}' (a bare column-key string or {\"literal\": ...} also works). Copy templates (email_draft_v1, subject_line_variants_v1, ...) reject mappings built only from manual name/title/company columns — ground them on a research or enrichment column, or write a freeform prompt with --prompt instead.")
+        .option("--model <openrouter-model-id>", "OpenRouter model id. Managed columns accept allow-listed models and bill by Oxygen tier; --reasoning-level selects a tier. BYOK uses your own key and provider pricing.")
+        .option("--reasoning-level <level>", REASONING_LEVEL_OPTION_HELP)
+        .option("--run-condition <formula>", "Formula expression gating whether the AI column runs per row. A formula over bare column keys (eu_israel = true), not {{tokens}}.")
+        .option("--run-condition-columns <csv>", "Comma-separated column keys referenced by --run-condition.")
+        .option("--structured-output", "Undo --no-structured-output: let the prompt's named sections shape the answer again.")
+        .option("--no-structured-output", "Keep an AI column answering in plain text even when its prompt names output sections. Use this for copy — an email body is one answer, not a set of fields.")
+        .option("--output-schema-json <json>", "AI column output JSON schema as inline JSON.")
+        .option("--output-schema-file <path>", "AI column output JSON schema read from a file path.")
+        .addOption(new Option("--classify <labels>", "Classification column: label every row with one of these comma-separated labels (2-20), answering --prompt. Each cell holds the label, a 0-1 confidence and uncertain:true below --min-confidence (the best guess is kept). Flat ~0.075 credits/row; see `columns run --dry-run`."))
+        .addOption(new Option("--yes-no <question>", "Classification column: answer this yes/no question per row (reference columns as {{column_key}}). Filter on the answer with `tables query --filter-tree-json` and a path leaf, e.g. '{\"type\":\"group\",\"conjunction\":\"and\",\"children\":[{\"type\":\"leaf\",\"columnKey\":\"<column>\",\"path\":\"answer\",\"operator\":\"is\",\"value\":true}]}'."))
+        .addOption(new Option("--score <levels>", "Classification column: rate each row on these comma-separated levels, lowest first (2-10), answering --prompt."))
+        .addOption(new Option("--min-confidence <0-1>", "Classification columns: below this the answer is marked uncertain. Default 0.85 (0.7 for --yes-no)."))
+        .addOption(new Option("--grounding <mode>", "Classification columns: none (default) judges only the row and your question; workspace also sends your workspace knowledge (ICP, positioning), which can pull answers toward your ICP."))
+        .option("--bind-object <slug>", "Bind column CRM object slug (companies, people, deals, ...). Sets kind=bind and resolves rows to CRM records by identity.")
+        .option("--bind-map <pairs>", "Bind identity mapping as identity=column pairs, e.g. domain=website,linkedin_url=li.")
+        .option("--bind-create", "Bind columns: assert a new CRM record for unmatched rows (onNoMatch=create; a truth write, needs --approved on run).")
+        .option("--lookup-table <table>", "Lookup column: source table id or slug to read from (same workspace). Sets kind=lookup. Free; reads resolve current source values and runs materialize them with provenance.")
+        .option("--lookup-match <pair>", "Lookup join as localColumn=sourceColumn, e.g. company_domain=domain.")
+        .option("--lookup-normalize <mode>", "Lookup key normalization: exact, lower-trim (default), email, domain, or linkedin.")
+        .option("--lookup-mode <mode>", "Lookup mode: first-match (default), count, exists, or aggregate.")
+        .option("--lookup-return <csv>", "Lookup first-match: source column keys to pull (single -> scalar cell, multiple -> object).")
+        .option("--lookup-order <column:dir>", "Lookup first-match tie-break when a key matches many source rows, e.g. created_at:desc.")
+        .option("--lookup-aggregate <fn:column>", "Lookup aggregate reducer as fn:column, e.g. sum:amount (fn: sum, avg, min, or max).")
+        .option("--json", "Print a JSON envelope.")
+        // skipcq: JS-R1005 — intentional per-option branching to assemble the columns-add request body
+        .action(async (table, options) => {
+        await handleAsyncAction("columns add", options, async () => {
+            // --capability seeds a COMPLETE enrichment column server-side (kind,
+            // jsonb data type, intent, the default provider order, label and
+            // key), so any flag that authors a different column is a conflict,
+            // not a modifier. Caught here rather than server-side so the user
+            // never gets back a column they did not ask for.
+            const capability = readOption(options.capability);
+            if (capability) {
+                const conflicting = [
+                    readOption(options.preset) ? "--preset" : null,
+                    readOption(options.prompt) ? "--prompt" : null,
+                    readOption(options.promptKey) ? "--prompt-key" : null,
+                    readOption(options.bindObject) ? "--bind-object" : null,
+                    readOption(options.bindMap) ? "--bind-map" : null,
+                    options.bindCreate ? "--bind-create" : null,
+                    readOption(options.lookupTable) ? "--lookup-table" : null,
+                    readOption(options.lookupMatch) ? "--lookup-match" : null,
+                    readOption(options.lookupMode) ? "--lookup-mode" : null,
+                    readOption(options.lookupReturn) ? "--lookup-return" : null,
+                    readOption(options.lookupOrder) ? "--lookup-order" : null,
+                    readOption(options.lookupAggregate) ? "--lookup-aggregate" : null,
+                    readOption(options.lookupNormalize) ? "--lookup-normalize" : null,
+                ].filter((flag) => flag !== null);
+                if (conflicting.length > 0) {
+                    throw new OxygenError("invalid_request", `--capability ${capability} seeds a complete enrichment column, so it cannot be combined with ${conflicting.join(", ")}. Drop one of the two.`, { exitCode: 1 });
+                }
+                const capabilityKind = readOption(options.kind)?.toLowerCase() ?? null;
+                if (capabilityKind && capabilityKind !== "enrichment") {
+                    throw new OxygenError("invalid_request", `--capability authors an enrichment column, but --kind ${capabilityKind} was requested. Drop --kind, or drop --capability.`, { exitCode: 1 });
+                }
+            }
+            // A preset names its own columns, so --label does not apply to it.
+            const preset = readOption(options.preset);
+            if (preset) {
+                if (options.label || options.promptKey || options.definitionJson || options.type || options.options || options.optionsJson) {
+                    throw new OxygenError("invalid_request", "--preset builds its own column set. Drop --label/--prompt-key/--definition-json/--type/--options, or add the column by hand without --preset.", { exitCode: 1 });
+                }
+                // Named only when passed: the classification flags are hidden from help.
+                const classificationFlag = options.classify ? "--classify" : options.yesNo ? "--yes-no" : options.score ? "--score" : null;
+                if (classificationFlag) {
+                    throw new OxygenError("invalid_request", `--preset builds its own column set. Drop ${classificationFlag}, or add the classification column without --preset.`, { exitCode: 1 });
+                }
+                const presetBody = { table, preset };
+                const inputs = parseKeyValuePairs(options.input ?? []);
+                if (Object.keys(inputs).length > 0)
+                    presetBody.inputs = inputs;
+                if (options.key)
+                    presetBody.payload_column = options.key;
+                const presetFields = readCsvOption(options.presetFields);
+                if (presetFields.length > 0)
+                    presetBody.fields = presetFields;
+                const checkTechnologies = readCsvOption(options.checkTechnologies);
+                if (checkTechnologies.length > 0)
+                    presetBody.check_technologies = checkTechnologies;
+                return requestOxygen("/api/cli/tables/columns", {
+                    method: "POST",
+                    body: presetBody,
+                });
+            }
+            // --capability supplies its own label ("Email Verification", ...)
+            // server-side, the same one the web picker writes.
+            if (!options.promptKey && !capability && !options.label) {
+                throw new OxygenError("invalid_request", "--label is required.", { exitCode: 1 });
+            }
+            const templateInputs = options.promptKey ? parseKeyValuePairs(options.input ?? []) : {};
+            if (options.promptKey && !options.inputMapping && Object.keys(templateInputs).length === 0) {
+                throw new OxygenError("missing_input_mapping", `--prompt-key ${options.promptKey} reads named inputs; bind each one to a column with --input <name>=<column_key> (e.g. --input url=pricing_url), or pass --input-mapping <json>. See \`oxygen columns catalog\` for the inputs a template reads.`, { exitCode: 1 });
+            }
+            const promptOption = readAiPromptOption(options.prompt);
+            const decisionFlags = readColumnDecisionFlags(options);
+            if (decisionFlags) {
+                const conflicting = [
+                    capability ? "--capability" : null,
+                    readOption(options.promptKey) ? "--prompt-key" : null,
+                    readOption(options.bindObject) || readOption(options.bindMap) || options.bindCreate ? "--bind-object" : null,
+                    readOption(options.lookupTable) ? "--lookup-table" : null,
+                    readOption(options.model) ? "--model" : null,
+                    readOption(options.outputSchemaJson) || readOption(options.outputSchemaFile) ? "--output-schema-json" : null,
+                    readOption(options.researchQuery) || readOption(options.researchUrl) ? "--research-query/--research-url" : null,
+                    readOption(options.kind) && readOption(options.kind).toLowerCase() !== "ai" ? `--kind ${readOption(options.kind)}` : null,
+                ].filter((flag) => flag !== null);
+                if (conflicting.length > 0) {
+                    throw new OxygenError("invalid_request", `A classification column (--classify, --yes-no or --score) is an AI column answered by the classifier, so it cannot be combined with ${conflicting.join(", ")}.`, { exitCode: 1 });
+                }
+                if (decisionFlags.question !== null && promptOption !== null) {
+                    throw new OxygenError("invalid_request", "--yes-no carries the question itself. Drop --prompt, or use --classify \"yes,no\" with --prompt.", { exitCode: 1 });
+                }
+                if (decisionFlags.question === null && promptOption === null) {
+                    throw new OxygenError("invalid_request", "--classify and --score need the question each row answers. Add --prompt \"<question>\", referencing columns as {{column_key}} — e.g. --prompt \"What kind of company is {{company_name}}?\".", { exitCode: 1 });
+                }
+            }
+            const prompt = decisionFlags?.question ?? promptOption;
+            if (prompt !== null && options.promptKey) {
+                throw new OxygenError("invalid_request", "Pass either --prompt (a freeform prompt) or --prompt-key (a prompt-library entry), not both.", { exitCode: 1 });
+            }
+            const column = {};
+            if (options.label)
+                column.label = options.label;
+            if (options.key)
+                column.key = options.key;
+            if (options.dataType)
+                column.data_type = options.dataType;
+            if (options.kind)
+                column.kind = options.kind;
+            if (options.semanticType)
+                column.semantic_type = options.semanticType;
+            // --description joins --definition-json in one assignment: a second
+            // self-spread of column.definition multiplies the parity scanner's work.
+            const description = readOption(options.description);
+            if (options.definitionJson || description) {
+                column.definition = {
+                    ...(options.definitionJson ? parseJsonObject(options.definitionJson) : {}),
+                    ...(description ? { description } : {}),
+                };
+            }
+            // A field type and its choices travel as themselves; the server
+            // resolves them exactly as the web picker's rows do.
+            if (readOption(options.type))
+                column.type = readOption(options.type);
+            const choices = readColumnOptionsFlags(options);
+            if (choices)
+                column.options = choices;
+            const requestedKind = readOption(options.kind)?.toLowerCase() ?? null;
+            const isResearch = requestedKind === "research";
+            if (capability)
+                column.capability = capability;
+            if (options.includePersonalEmail)
+                column.include_personal_email = true;
+            // An enrichment cell is always the provider envelope, so the server
+            // rejects any other data type ("Enrichment columns must use jsonb
+            // data type."). Default it, the way --bind-object already does,
+            // instead of making the caller bolt on --data-type jsonb.
+            if (requestedKind === "enrichment" && !options.dataType) {
+                column.data_type = "jsonb";
+            }
+            if (prompt !== null) {
+                if (requestedKind && requestedKind !== "ai" && !isResearch) {
+                    throw new OxygenError("invalid_request", `--prompt authors an AI or research column, but --kind ${requestedKind} was requested. Drop --kind, or drop --prompt.`, { exitCode: 1 });
+                }
+                column.kind = isResearch ? "research" : "ai";
+                // A research cell is always the {answer, found, confidence, sources}
+                // envelope, so it is jsonb regardless of --output-schema-*.
+                // An output schema makes an AI cell a structured object, which is only
+                // queryable/materializable as jsonb; a bare prompt returns prose. The
+                // runner serializes structured output into a text cell too, so this
+                // only picks the more useful shape — it can never make the column fail.
+                if (!options.dataType) {
+                    column.data_type = isResearch
+                        || readOption(options.outputSchemaJson)
+                        || readOption(options.outputSchemaFile)
+                        ? "jsonb"
+                        : "text";
+                }
+            }
+            else if (isResearch) {
+                throw new OxygenError("invalid_request", "A research column needs a question to answer. Add --prompt \"<what to look up>\", referencing row values as {{column_key}} — for example --prompt \"What does {{company_name}} sell?\".", { exitCode: 1 });
+            }
+            if (prompt !== null ||
+                readOption(options.model) ||
+                readOption(options.reasoningLevel) ||
+                readOption(options.runCondition) ||
+                readOption(options.outputSchemaJson) ||
+                readOption(options.outputSchemaFile)) {
+                const definition = isRecord(column.definition) ? column.definition : {};
+                if (prompt !== null)
+                    definition.prompt = assertPromptNotAlsoInDefinition(definition, prompt);
+                // normalizeAiColumnDefinition requires inputMapping unconditionally, so
+                // a bare --prompt would 400 on every call without this. It is genuinely
+                // empty and not a placeholder: prompt {{tokens}} resolve straight off the
+                // row in composeAiColumnPrompt, independently of inputMapping — which is
+                // the whole reason --prompt does not make the user restate their columns.
+                // The web AI seed emits the same {} for the same reason.
+                if (!isRecord(definition.inputMapping))
+                    definition.inputMapping = {};
+                column.definition = isResearch
+                    ? applyResearchColumnConfig(applyAiColumnConfig(definition, options), options)
+                    : applyAiColumnConfig(definition, options);
+                if (decisionFlags) {
+                    column.definition.decision = decisionFlags.decision;
+                    // The cell is {answer, confidence, uncertain, reason}: JSON, so it filters.
+                    if (!options.dataType)
+                        column.data_type = "jsonb";
+                }
+            }
+            if (readOption(options.bindObject) || readOption(options.bindMap) || options.bindCreate) {
+                // A column is one kind. --prompt already set kind=ai above, and the
+                // bind/lookup blocks below would silently overwrite it — the same
+                // conflict --kind raises explicitly, so raise it here too rather than
+                // handing back a bind column the user never asked for.
+                assertPromptNotAlsoOtherKind(prompt, "--bind-object");
+                const definition = isRecord(column.definition) ? column.definition : {};
+                column.kind = "bind";
+                // Bind columns write a jsonb status cell; the server rejects any other
+                // data type (invalid_column_definition). Default it so callers don't have
+                // to pass --data-type jsonb by hand alongside --bind-object.
+                if (!options.dataType)
+                    column.data_type = "jsonb";
+                column.definition = applyBindColumnConfig(definition, options);
+            }
+            if (readOption(options.lookupTable)
+                || readOption(options.lookupMatch)
+                || readOption(options.lookupMode)
+                || readOption(options.lookupReturn)
+                || readOption(options.lookupOrder)
+                || readOption(options.lookupAggregate)
+                || readOption(options.lookupNormalize)) {
+                assertPromptNotAlsoOtherKind(prompt, "--lookup-table");
+                const definition = isRecord(column.definition) ? column.definition : {};
+                column.kind = "lookup";
+                const lookupDefinition = applyLookupColumnConfig(definition, options);
+                column.definition = lookupDefinition;
+                // Derive the output data type from the mode so callers don't have to know
+                // it (the bind lesson), with the web editor's rule: count/aggregate ->
+                // numeric, exists -> boolean, first_match -> text for one return column,
+                // jsonb for several. Sent explicitly so an older server agrees too.
+                if (!options.dataType) {
+                    column.data_type = lookupColumnDataType(lookupDefinition.mode ?? "first_match", lookupDefinition.returnColumns);
+                }
+            }
+            const body = { table, column };
+            if (options.promptKey)
+                body.prompt_key = options.promptKey;
+            const researchDepth = readResearchDepthOption(options.researchDepth);
+            if (researchDepth)
+                body.research_depth = researchDepth;
+            if (options.inputMapping) {
+                body.input_mapping = parseJsonObject(options.inputMapping);
+            }
+            else if (Object.keys(templateInputs).length > 0) {
+                // `--input url=pricing_url` → the same typed column refs the JSON form
+                // carries, so the server sees one shape from both spellings.
+                body.input_mapping = Object.fromEntries(Object.entries(templateInputs).map(([name, columnKey]) => [name, { type: "column", columnKey }]));
+            }
+            // Every authoring path, not just --prompt: a definition pasted into
+            // --definition-json used to skip this entirely and fail once per row.
+            await assertColumnDefinitionReferences(table, column.definition);
+            const created = await requestOxygen("/api/cli/tables/columns", {
+                method: "POST",
+                body,
+            });
+            if (!options.json)
+                writeColumnReferenceNotices(created);
+            return created;
+        });
+    }))
+        .addCommand(new Command("run")
+        .description("Run an executable AI, tool, formula, enrichment, bind, lookup, or custom HTTP column for one row or a bounded batch. Paid server-side columns always run durably in the background. Bind create-mode (onNoMatch=create) needs --approved.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column id or key.")
+        .option("--idempotency-key <key>", "Replay key for durable server-side run admission.")
+        .option("--row-id <row_id>", "Workspace row id to run. Get one from `oxygen tables query <table> --limit 1 --json` — the field is `_row_id`, not `id`.")
+        .option("--limit <n>", "Run the next N rows whose target cell is still empty (--force runs the first N regardless). Repeat until rowCount is 0 to page through a table. Defaults to 10; inline deterministic runs have a hard cap of 25.")
+        .option("--all", "Run all rows. Requires --background, except with --dry-run, which previews the background run without queueing it.")
+        .option("--filter-json <json>", "Row selector filter object or array for background runs. Do not combine with --all, --limit, or --row-id.")
+        .option("--formula-values <mode>", "With --filter-json on a formula column, first refresh that selector with `columns run <table> <column> --force` (0 credits), then pass 'materialized'. The run filters the stored snapshot and persists this freshness acknowledgement.")
+        .option("--force", "Run even when the target cell already has a value. Formula columns compute when read, so `tables query` shows their values without a run. Stored fields (definition `fill: \"empty\"`, such as the person_enrich profile fields) keep their own cell instead: it fills when the column they read from runs. A run skips rows that already store a value (existing_value), and --force refreshes them.")
+        .option("--connection-id <connection_id>", "Optional provider integration connection id.")
+        .option("--background", "Create a durable background run for a free deterministic column. Paid AI/tool/enrichment server runs are always backgrounded.")
+        .option("--approved", "Confirm a paid durable run, or a bind create-mode run (onNoMatch=create), after inspecting a dry run or preview.")
+        .option("--approved-effect-unknown", "With --row-id, allow rerunning a cell whose previous external write was dispatched but never confirmed. Verify the destination first: this can apply the same external effect twice.")
+        .option("--max-credits <n>", "Maximum OXYGEN credits for this run, including managed calls, web grounding and own-key provider platform fees. Vendor charges on your own key are outside this ceiling. BYOK model inference is free; managed grounding still counts.")
+        .option("--max-concurrency <n>", "Maximum concurrent row items for a background run (1-1000; a ceiling shared with worker and provider capacity). Defaults to 250 for AI columns and 50 otherwise (160 for Firecrawl scrape columns).")
+        .option("--local", "Run a custom HTTP column in this CLI process, where {env:...} secrets read your own machine's environment. Without it the column runs in the background on Oxygen and the same reference resolves from this workspace's registered custom integration.")
+        .option("--local-concurrency <n>", "Maximum concurrent custom HTTP requests for --local. Defaults to 3.")
+        .option("--dry-run", "Preview the model tier, credit estimate, run-condition posture, and — for an AI column — the prompt rendered with one real row's values, without spending any credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        const limit = readPositiveInt(options.limit);
+        const localConcurrency = readPositiveInt(options.localConcurrency);
+        const maxCredits = readPositiveNumber(options.maxCredits);
+        const maxConcurrency = readPositiveInt(options.maxConcurrency);
+        const filterSelection = readFilterSelectionOption(options.filterJson);
+        const formulaValues = readFormulaValuesOption(options.formulaValues);
+        if (formulaValues && !filterSelection) {
+            throw new OxygenError("invalid_selection", "--formula-values requires --filter-json on columns run.", { exitCode: 1 });
+        }
+        const effectiveFilterSelection = filterSelection
+            ? { ...filterSelection, ...(formulaValues ? { formula_values: formulaValues } : {}) }
+            : undefined;
+        const selectedModes = [
+            Boolean(options.all),
+            limit !== undefined,
+            Boolean(readOption(options.rowId)),
+            Boolean(effectiveFilterSelection),
+        ].filter(Boolean).length;
+        // skipcq: JS-R1005 — intentional branching for local/background/filter column-run modes
+        await handleAsyncAction("columns run", options, async () => {
+            // Selection-shape errors are raised inside the action so --json
+            // callers get the failure envelope, not a bare stack trace.
+            if (selectedModes > 1) {
+                throw new OxygenError("invalid_selection", "Pass only one of --all, --limit, --row-id, or --filter-json.", {
+                    exitCode: 1,
+                });
+            }
+            // A dry run of an all-rows run previews the background run the live
+            // command would create and queues nothing, so demanding --background
+            // for it only teaches a flag with no behavioural basis (blind eval
+            // 2026-09-10: the agent tripped the error, then re-ran with the flag).
+            if (options.all && options.dryRun && !options.background && !options.local) {
+                options.background = true;
+            }
+            if (options.all && !options.background) {
+                throw new OxygenError("invalid_column_run", "--all requires --background.", {
+                    exitCode: 1,
+                });
+            }
+            if (options.local) {
+                if (options.background) {
+                    throw new OxygenError("invalid_column_run", "Pass either --local or --background, not both.", {
+                        exitCode: 1,
+                    });
+                }
+                if (effectiveFilterSelection) {
+                    throw new OxygenError("invalid_column_run", "--filter-json requires --background for columns run.", {
+                        exitCode: 1,
+                    });
+                }
+                return runLocalCustomHttpColumn(table, column, {
+                    rowId: readOption(options.rowId),
+                    force: Boolean(options.force),
+                    ...(limit ? { limit } : {}),
+                    ...(localConcurrency ? { concurrency: localConcurrency } : {}),
+                });
+            }
+            const body = {
+                ...(readOption(options.idempotencyKey) ? { idempotency_key: readOption(options.idempotencyKey) } : {}),
+                table,
+                column,
+                ...(options.all ? { selection: { mode: "all" } } : {}),
+                ...(effectiveFilterSelection ? { selection: effectiveFilterSelection } : {}),
+                ...(!options.all && readOption(options.rowId) ? { row_id: readOption(options.rowId) } : {}),
+                ...(!options.all && !filterSelection && limit ? { limit } : {}),
+                ...(options.force ? { force: true } : {}),
+                ...(readOption(options.connectionId) ? { connection_id: readOption(options.connectionId) } : {}),
+                ...(options.background ? { background: true } : {}),
+                ...(options.approved ? { approved: true } : {}),
+                ...(options.approvedEffectUnknown ? { approved_effect_unknown: true } : {}),
+                ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                ...(maxConcurrency ? { max_concurrency: maxConcurrency } : {}),
+                ...(options.dryRun ? { dry_run: true } : {}),
+            };
+            const data = await requestColumnsRun(body, table, {
+                background: Boolean(options.background),
+            });
+            if (!options.json)
+                writeAiPromptPreviewNotice(data);
+            return data;
+        });
+    }))
+        .addCommand(new Command("rerun")
+        .description("Re-run a single AI column cell, optionally threading a prior message review's feedback into the prompt.")
+        .requiredOption("--table <table>", "Table id or slug.")
+        .requiredOption("--column <column>", "Column id or key.")
+        .requiredOption("--row <row_id>", "Row UUID.")
+        .option("--from-review-id <review_id>", "Prior message review whose feedback to thread into the regeneration prompt.")
+        .option("--dry-run", "Preview the single-row credit estimate and posture without spending credits or writing a review.")
+        .option("--max-credits <n>", "Required managed-credit ceiling for a live AI rerun; inspect --dry-run first.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        const maxCredits = readNonNegativeNumber(options.maxCredits);
+        await handleAsyncAction("columns rerun", options, () => requestOxygen("/api/cli/columns/rerun", {
+            method: "POST",
+            body: {
+                table: options.table,
+                column: options.column,
+                row_id: options.row,
+                ...(readOption(options.fromReviewId) ? { from_review_id: readOption(options.fromReviewId) } : {}),
+                ...(options.dryRun ? { dry_run: true } : {}),
+                ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("materialize")
+        .description("Copy JSON paths from a result column into existing or new target columns. Without --mappings-json, the fixed work_email preset creates email, email_provider, email_status, and email_enriched_at; it does not target a column named work_email.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<source_column>", "JSONB source column id or key.")
+        .option("--preset <preset>", "Fixed companion-column bundle. work_email creates email, email_provider, email_status, and email_enriched_at; it never binds to an existing work_email column.")
+        .option("--mappings-json <json>", "JSON array of {source_path,target_column,label?,data_type?,semantic_type?} mappings. Use this form to write into an existing column such as work_email.")
+        .option("--no-create-if-missing", "Require target companion columns to already exist.")
+        .option("--overwrite-existing", "Replace target values when the materialized source differs. By default only empty targets are filled.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, sourceColumn, options) => {
+        const mappings = options.mappingsJson ? parseJsonArray(options.mappingsJson) : undefined;
+        const preset = readOption(options.preset);
+        await handleAsyncAction("columns materialize", options, () => requestOxygen(`/api/cli/tables/${encodeURIComponent(table)}/columns/${encodeURIComponent(sourceColumn)}/materialize`, {
+            method: "POST",
+            body: {
+                ...(mappings ? { mappings } : {}),
+                ...(!mappings ? { preset: preset ?? "work_email" } : preset ? { preset } : {}),
+                create_if_missing: options.createIfMissing !== false,
+                overwrite_existing: options.overwriteExisting === true,
+            },
+        }));
+    }))
+        .addCommand(new Command("rename")
+        .description("Rename a workspace column's stable key (requires --key), optionally updating its display label. Free (0 credits). For a label-only change, use columns update <table> <column> --label <label>. Warns when another column reads the old key; a rename does not rewrite those references.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column id or key.")
+        .requiredOption("--key <key>", "Required new stable column key.")
+        .option("--label <label>", "Optional new display label.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        await handleAsyncAction("columns rename", options, async () => {
+            const renamed = await requestOxygen("/api/cli/tables/columns/rename", {
+                method: "POST",
+                body: {
+                    table,
+                    column,
+                    key: options.key,
+                    ...(readOption(options.label) ? { label: readOption(options.label) } : {}),
+                },
+            });
+            if (!options.json)
+                writeColumnReferenceNotices(renamed);
+            return renamed;
+        });
+    }))
+        .addCommand(new Command("update")
+        .description("Update a workspace column: label, note, position and visibility; a choice column's options; a lookup or bind column's source, join and mode; and for AI/research columns the prompt, named inputs, model, reasoning level, run condition, output schema, and web-research settings.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column id or key.")
+        .option("--label <label>", "New display label.")
+        .option("--semantic-type <type>", "New semantic type: a display hint such as company.domain, or a choice type (select, multi_select, status) to give a column options.")
+        .option("--clear-semantic-type", "Clear the column's semantic type.")
+        .option("--options <choices>", "Replace a select, multi_select or status column's choices, comma-separated in display order. Cells keep the values they hold; keep a value in the list to keep it selectable.")
+        .option("--options-json <json>", "Replacement choices as a JSON array of strings or {value,label?,color?}. Rename a choice by giving the same value a new label.")
+        .option("--description <text>", "Replace the column's note.")
+        .option("--lookup-table <table>", "Lookup columns: read from this source table instead; pass --lookup-match with it, since the join column belongs to the source.")
+        .option("--lookup-match <pair>", "Lookup columns: new join as localColumn=sourceColumn.")
+        .option("--lookup-normalize <mode>", "Lookup columns: key normalization exact, lower-trim, email, domain, or linkedin.")
+        .option("--lookup-mode <mode>", "Lookup columns: first-match, count, exists, or aggregate. The column's data type follows the mode.")
+        .option("--lookup-return <csv>", "Lookup columns: the source columns first-match returns.")
+        .option("--lookup-order <column:dir>", "Lookup columns: first-match tie-break, e.g. created_at:desc.")
+        .option("--lookup-aggregate <fn:column>", "Lookup columns: aggregate reducer as fn:column (sum, avg, min or max).")
+        .option("--bind-object <slug>", "Bind columns: resolve rows to this CRM object instead (companies, people, deals, ...).")
+        .option("--bind-map <pairs>", "Bind columns: identity=column pairs to add or change, e.g. domain=website.")
+        .option("--bind-create", "Bind columns: create a CRM record for unmatched rows (a truth write; runs need --approved).")
+        .option("--no-bind-create", "Bind columns: leave unmatched rows unbound.")
+        .option("--position <n>", "Move the column to this zero-based position.")
+        .option("--definition-json <json>", "Definition metadata to shallow-merge into the column; arrays are replaced wholesale and missing keys leave existing fields unchanged.")
+        .option("--definition-unset <keys>", "Comma-separated definition keys to REMOVE after the merge (e.g. outputSchema,model) — a merge can only add or overwrite. Lifecycle and provenance keys are rejected.")
+        .option("--data-type <type>", "New output data type for a lookup column (text, numeric, boolean, jsonb, timestamptz). Discards the cached cells; other column kinds use `oxygen columns retype`.")
+        .option("--prompt <text-or-file>", "Replacement AI column prompt, or a path to a prompt file. Reference other columns inline as {{column_key}}; unknown keys are rejected here instead of failing per row. Merges into --definition-json; a `prompt` in both is an error.")
+        .option("--input-mapping <json>", "Replace the column's named inputs wholesale. Row columns belong in the prompt as {{column_key}}; use this for the inputs a prompt cannot name on its own — literals and workspace context ({\"icp\":{\"type\":\"context_profile\",\"path\":\"icp\"}}), which the prompt then reads as {{icp}}. Pass {} to clear it; --definition-json can only add mapping keys, never remove one.")
+        .option("--model <openrouter-model-id>", "OpenRouter model id. Managed columns accept allow-listed models and bill by Oxygen tier; --reasoning-level selects a tier. BYOK uses your own key and provider pricing.")
+        .option("--reasoning-level <level>", REASONING_LEVEL_OPTION_HELP)
+        .option("--run-condition <formula>", "Formula expression gating whether the AI column runs per row. A formula over bare column keys (eu_israel = true), not {{tokens}}.")
+        .option("--run-condition-columns <csv>", "Comma-separated column keys referenced by --run-condition.")
+        // Positive first keeps omission undefined; negative first defaults true
+        // and silently overwrites a saved prose choice on an unrelated update.
+        .option("--structured-output", "Restore the prompt's named JSON fields. Existing AI columns must store jsonb; for a text column, add a new AI column with --data-type jsonb.")
+        .option("--no-structured-output", "Keep an AI column answering in plain text even when its prompt names output sections. Use this for copy — an email body is one answer, not a set of fields.")
+        .option("--output-schema-json <json>", "AI column output JSON schema as inline JSON.")
+        .option("--output-schema-file <path>", "AI column output JSON schema read from a file path.")
+        .option("--research-query <template>", "Research columns: replace the per-row web search query template, e.g. \"{{company_name}} pricing page\".")
+        .option("--research-domains <csv>", "Research columns: replace the comma-separated list of domains to search within.")
+        .option("--research-exclude-domains <csv>", "Research columns: replace the comma-separated list of domains to exclude.")
+        .option("--research-mode <mode>", "Research columns: strict (answer only from the sources) or estimate (reason to a figure from them).")
+        .option("--research-results <n>", "Research columns: how many search results to ground each row on (1-25).")
+        .option("--research-engine <engine>", "Research columns: pin the search provider (serper or exa).")
+        .option("--research-depth <depth>", RESEARCH_DEPTH_OPTION_HELP)
+        // Declaring BOTH forms leaves the default undefined (Commander only
+        // defaults to true when --no- is declared alone), so an update that
+        // doesn't mention visibility leaves it untouched.
+        .option("--always-show", "Keep this column visible even when it holds no values.")
+        .option("--no-always-show", "Stop pinning this column, so it collapses again while empty.")
+        .option("--hidden-by-default", "Leave this column out of the grid on first open. It stays readable everywhere else, and anyone can reveal it from the column menu.")
+        .option("--no-hidden-by-default", "Show this column in the grid on first open. Read the current opening set with `oxygen tables describe <table>` — every column reports its hiddenByDefault state.")
+        .option("--dry-run", "Return the would-be merged definition without writing.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        await handleAsyncAction("columns update", options, async () => {
+            const prompt = readAiPromptOption(options.prompt);
+            const hasAiConfig = prompt !== null ||
+                readOption(options.model) ||
+                readOption(options.reasoningLevel) ||
+                readOption(options.runCondition) ||
+                readOption(options.outputSchemaJson) ||
+                readOption(options.outputSchemaFile) ||
+                typeof options.structuredOutput === "boolean";
+            let definition = options.definitionJson
+                ? parseJsonObject(options.definitionJson)
+                : undefined;
+            const hasResearchConfig = Boolean(readOption(options.researchQuery)
+                || readOption(options.researchDomains)
+                || readOption(options.researchExcludeDomains)
+                || readOption(options.researchMode)
+                || readOption(options.researchResults)
+                || readOption(options.researchEngine));
+            if (hasAiConfig || hasResearchConfig) {
+                const merged = definition ?? {};
+                if (prompt !== null)
+                    merged.prompt = assertPromptNotAlsoInDefinition(merged, prompt);
+                definition = applyAiColumnConfig(merged, options);
+                // The server shallow-merges `definition`, so webSearch is replaced
+                // wholesale; applyResearchColumnConfig carries the untouched keys over
+                // from --definition-json rather than dropping them.
+                if (hasResearchConfig)
+                    definition = applyResearchColumnConfig(definition, options);
+            }
+            const definitionUnset = readCsvOption(options.definitionUnset);
+            // --input-mapping is the only way to repair a bad mapping in place:
+            // the server SHALLOW-merges `definition`, so a nested inputMapping
+            // sent through --definition-json adds keys and can never remove one.
+            // This replaces the object wholesale.
+            // Every flag below adds whole keys, merged into `definition` ONCE. The
+            // surface-parity scanner re-reads each assignment that spreads a
+            // variable into itself, so stacking `definition = { ...definition }`
+            // assignments multiplied its work 13x and timed the gate out (#5086).
+            const additions = {};
+            const inputMapping = readOption(options.inputMapping);
+            if (inputMapping)
+                additions.inputMapping = parseJsonObject(inputMapping);
+            const description = readOption(options.description);
+            if (description)
+                additions.description = description;
+            // Lookup and bind flags edit the STORED configuration: the server merges
+            // `definition` one level deep, so a partial `match` would replace the
+            // whole join. Read the column, apply the flags over it, send the result.
+            const editsLookup = hasLookupColumnFlags(options);
+            const editsBind = Boolean(readOption(options.bindObject) || readOption(options.bindMap))
+                || typeof options.bindCreate === "boolean";
+            if (editsLookup || editsBind) {
+                const stored = await readStoredColumnForUpdate(table, column);
+                if (editsLookup)
+                    Object.assign(additions, lookupDefinitionEdit(stored, options));
+                if (editsBind)
+                    Object.assign(additions, bindDefinitionEdit(stored, options));
+            }
+            if (Object.keys(additions).length > 0)
+                definition = { ...(definition ?? {}), ...additions };
+            const choices = readColumnOptionsFlags(options);
+            await assertColumnDefinitionReferences(table, definition);
+            // Sent beside `definition`, never inside it: the server merges the
+            // depth into the column's STORED search block, so it cannot drop a
+            // query template or domains the way a partial webSearch would.
+            const researchDepth = readResearchDepthOption(options.researchDepth);
+            const updated = await requestOxygen("/api/cli/tables/columns/update", {
+                method: "POST",
+                body: {
+                    table,
+                    column,
+                    ...(choices ? { options: choices } : {}),
+                    ...(researchDepth ? { research_depth: researchDepth } : {}),
+                    ...(readOption(options.label) ? { label: readOption(options.label) } : {}),
+                    ...(options.clearSemanticType ? { semantic_type: null } : readOption(options.semanticType) ? { semantic_type: readOption(options.semanticType) } : {}),
+                    ...(readOption(options.position) !== null ? { position: readNonNegativeInt(options.position) } : {}),
+                    ...(definition ? { definition } : {}),
+                    ...(definitionUnset.length > 0 ? { definition_unset: definitionUnset } : {}),
+                    ...(readOption(options.dataType) ? { data_type: readOption(options.dataType) } : {}),
+                    ...(typeof options.alwaysShow === "boolean" ? { always_show: options.alwaysShow } : {}),
+                    ...(typeof options.hiddenByDefault === "boolean"
+                        ? { hidden_by_default: options.hiddenByDefault }
+                        : {}),
+                    ...(options.dryRun ? { dry_run: true } : {}),
+                },
+            });
+            if (!options.json)
+                writeColumnReferenceNotices(updated);
+            return updated;
+        });
+    }))
+        .addCommand(new Command("convert")
+        .description("Convert a column between an AI column and a Web Research Agent column (--to agent or --to ai), or switch an agent to Keyword search and back. Keyword search returns a raw search-result list, not a sourced answer; the saved search question becomes its query. Conversion keeps the key, label and position, clears results, and needs --yes; without it this prints what would change.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column id or key.")
+        .requiredOption("--to <target>", "agent (Web Research Agent), ai (AI column, no web access) or keyword (Keyword search).")
+        .option("--prompt <text>", "Keyword search to agent only: the question the agent answers for each row. Defaults to the column's saved search, as the web's mode switch does.")
+        .option("--yes", "Convert, clearing the column's current results.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        await handleAsyncAction("columns convert", options, async () => {
+            const to = readOption(options.to)?.toLowerCase() ?? "";
+            if (!["agent", "ai", "keyword"].includes(to)) {
+                throw new OxygenError("invalid_request", `--to must be agent, ai or keyword (got ${to || "nothing"}).`, { exitCode: 1 });
+            }
+            const prompt = readOption(options.prompt);
+            const body = { table, column, to, ...(prompt ? { prompt } : {}) };
+            if (!options.yes) {
+                const plan = await requestOxygen("/api/cli/tables/columns/convert", {
+                    method: "POST",
+                    body: { ...body, dry_run: true },
+                });
+                if (plan.effect_outcome === "no_change" && plan.results_cleared !== true)
+                    return plan;
+                throw new OxygenError("confirmation_required", `Converting ${column} to ${String(plan.to_label ?? to)} clears its current results. Re-run with --yes to convert.`, { details: plan, exitCode: 2 });
+            }
+            return requestOxygen("/api/cli/tables/columns/convert", {
+                method: "POST",
+                body: { ...body, confirm: true },
+            });
+        });
+    }))
+        .addCommand(new Command("retype")
+        .description("Convert a manual text column to a stronger data type, migrating stored values.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column id or key.")
+        .requiredOption("--data-type <type>", "Target data type: text, numeric, boolean, jsonb, or timestamptz (the web's Data type choices).")
+        .option("--dry-run", "Preview the conversion (row counts and samples) without writing.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        await handleAsyncAction("columns retype", options, () => requestOxygen(`/api/cli/tables/${encodeURIComponent(table)}/columns/${encodeURIComponent(column)}/retype`, {
+            method: "POST",
+            body: {
+                data_type: options.dataType,
+                ...(options.dryRun ? { dry_run: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("archive")
+        .description("Archive a workspace column without dropping physical data. Hides it indefinitely with no purge timer; for cleanup with a restorable deadline use `columns delete`.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column id or key.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        await handleAsyncAction("columns archive", options, () => requestOxygen(`/api/cli/tables/${encodeURIComponent(table)}/columns/${encodeURIComponent(column)}/archive`, {
+            method: "POST",
+            body: {},
+        }));
+    }))
+        .addCommand(new Command("delete")
+        .description("Delete workspace columns: archives now, frees the key for reuse, and schedules the physical purge (default 14 days; restorable via `columns restore` until then). --now purges immediately and permanently — it previews and refuses without --yes.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<columns...>", "Column ids or keys.")
+        .option("--now", "Purge immediately instead of scheduling. Irreversible; single column only.")
+        .option("--yes", "Approve the immediate purge previewed by --now.")
+        .option("--purge-after <days>", "Days until the scheduled purge runs. Defaults to 14; 0 purges on the next background sweep (sweeps visit each workspace every few minutes).")
+        .option("--reason <text>", "Recorded with the delete for the audit trail.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, columns, options) => {
+        await handleAsyncAction("columns delete", options, () => {
+            const purgeAfter = readOption(options.purgeAfter) ?? undefined;
+            const purgeAfterDays = purgeAfter === undefined ? undefined : Number.parseInt(purgeAfter, 10);
+            if (purgeAfterDays !== undefined && (!Number.isFinite(purgeAfterDays) || purgeAfterDays < 0)) {
+                throw new OxygenError("invalid_request", "--purge-after must be a non-negative number of days.", {
+                    exitCode: 2,
+                });
+            }
+            return requestOxygen("/api/cli/tables/columns/delete", {
+                method: "POST",
+                body: {
+                    table,
+                    ...(columns.length === 1 ? { column: columns[0] } : { columns }),
+                    ...(options.now ? { now: true } : {}),
+                    ...(options.yes ? { approved: true } : {}),
+                    ...(purgeAfterDays !== undefined ? { purge_after_days: purgeAfterDays } : {}),
+                    ...(readOption(options.reason) ? { reason: readOption(options.reason) } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("restore")
+        .description("Restore an archived or delete-scheduled column: cancels the purge timer and reclaims its key.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column id or key (the pre-delete key works).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        await handleAsyncAction("columns restore", options, () => requestOxygen("/api/cli/tables/columns/restore", {
+            method: "POST",
+            body: { table, column },
+        }));
+    }))
+        .addCommand(new Command("reorder")
+        .description("Move a workspace column to a new position, by absolute index or relative to another column.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column id or key to move.")
+        .option("--position <n>", "Target zero-based index for the column.")
+        .option("--before <column>", "Place the column immediately before this column id or key.")
+        .option("--after <column>", "Place the column immediately after this column id or key.")
+        .option("--dry-run", "Return the would-be position without persisting the reorder.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        await handleAsyncAction("columns reorder", options, async () => {
+            const position = await resolveColumnReorderPosition(table, column, options);
+            return requestOxygen("/api/cli/tables/columns/reorder", {
+                method: "POST",
+                body: {
+                    table,
+                    column,
+                    position,
+                    ...(options.dryRun ? { dry_run: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("catalog")
+        .description("List column templates and native Classify; multi-column enrichment bundles (presets such as person_enrich and company_enrich) are listed by `oxygen enrichment catalog`. For ICP fit, Classify Score (0.075 credits/row) appears in `data.native`, including with `--family classification`; `data.entries` lists separate prompt templates. Templates can be added with `columns add <table> --prompt-key <key>`: the extract templates (pricing-page, job-posting, event, 10-K, website-fact, market and text extractors) and the company research questions (founders, parent company, subsidiaries, funding rounds, market cap, cloud provider, is SaaS, offers demos, industry, NAICS, HQ / states / cities, competitors, LinkedIn / Crunchbase / Glassdoor / careers page lookups) and the person templates (--category people: skill set, grad school, location, job fit and current company read from the person_enrich payload for 15 credits; events, keynotes, podcasts and GitHub profile searched by name), each with the input it reads (bind it with --input <name>=<column_key>), the providers behind it, the answer fields, and the credits per row. Read-only and free. Website contacts (emails and phones from each row's site) is here as `--kind tool`; other tool-backed columns that read a page or call a provider are found with `oxygen tools search <words>`. Provider waterfalls and enrichment bundles are a different list with their own per-row prices: `oxygen enrichment catalog`.")
+        .option("--category <category>", "Only templates in one picker section: extract (page and text extraction), normalize, organize, summarize (free cleanups and classifications), people (person questions and appearances) or company (company research questions); comma-separate to combine (extract,people). The outreach prompts sit under copy, scoring, qa, research.")
+        .option("--family <family>", "Only one family. Extract: pricing, job_posting, events, filings, site_facts, market, portfolio, text_extraction. Cleanups: company, person, email, lists, classification. Company: web_presence, corporate_structure, funding, footprint, business_model, tech, market. People: profile, appearances.")
+        .option("--kind <kind>", "Only one column kind: research (reads the web or a page, answer with sources), search (a managed web search whose cell is a page URL or the result list, fixed price), ai (reads row text), formula (free), or tool (a native fetch over a website, such as website contacts).")
+        .option("--search <term>", "Match a word against template keys, titles and descriptions, e.g. pricing or 10-K.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("columns catalog", options, async () => {
+            const params = new URLSearchParams();
+            for (const [name, value] of [
+                ["category", readOption(options.category)],
+                ["family", readOption(options.family)],
+                ["kind", readOption(options.kind)],
+                ["search", readOption(options.search)],
+            ]) {
+                if (value)
+                    params.set(name, value);
+            }
+            const query = params.toString();
+            const result = await requestOxygen(`/api/cli/tables/columns/catalog${query ? `?${query}` : ""}`, { method: "GET" });
+            if (!options.json)
+                printColumnCatalog(result);
+            return result;
+        });
+    }))
+        .addCommand(new Command("deps")
+        .description("Show the column dependency graph: which columns feed which (formulas, input mappings, run conditions, waterfall targets), transitive up/downstream, and cycles. Read-only.")
+        .argument("<table>", "Table id or slug.")
+        .option("--column <key>", "Focus on one column: its upstream inputs, downstream dependents, and edges.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("columns deps", options, () => {
+            const params = new URLSearchParams({ table });
+            const column = readOption(options.column);
+            if (column)
+                params.set("column", column);
+            return requestOxygen(`/api/cli/tables/columns/deps?${params.toString()}`, { method: "GET" });
+        });
+    }))
+        .addCommand(new Command("fields")
+        .description("List what a column's output exposes: every field you can reference as {{column.field}}, filter on, sort by, or promote to its own column with `columns materialize`. Works before the column has ever run. Read-only and free.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column key or id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        await handleAsyncAction("columns fields", options, () => {
+            const params = new URLSearchParams({ table, column });
+            return requestOxygen(`/api/cli/tables/columns/fields?${params.toString()}`, { method: "GET" });
+        });
+    }));
+}