@oxygen-agent/cli 1.948.1 → 1.982.3

package/node_modules/@oxygen/shared/dist/knowledge-repository.js

@@ -0,0 +1,121 @@
+import { OxygenError } from "./cli-result.js";
+export const KNOWLEDGE_REPOSITORY_FILE_LIMIT = 25_000;
+export const KNOWLEDGE_REPOSITORY_POLL_MS = 5 * 60_000;
+export const KNOWLEDGE_REPOSITORY_IDLE_MS = 15_000;
+export const KNOWLEDGE_REPOSITORY_MAX_WAIT_MS = 60_000;
+function isCredentialFile(name) {
+    if (name === ".env" ||
+        name.startsWith(".env.") ||
+        [
+            ".git-credentials",
+            ".git_credentials_input",
+            ".netrc",
+            ".npmrc",
+            ".pypirc",
+            "credentials",
+        ].includes(name) ||
+        /^(?:id_rsa|id_ed25519|id_ecdsa)(?:\.|$)/.test(name) ||
+        /\.(?:jks|kdbx|keystore|pem|p12|pfx|key)$/.test(name)) {
+        return true;
+    }
+    const extension = name.match(/\.([^.]+)$/)?.[1] ?? "";
+    return ([
+        "json",
+        "yaml",
+        "yml",
+        "toml",
+        "ini",
+        "cfg",
+        "conf",
+        "properties",
+    ].includes(extension) &&
+        /(?:^|[._-])(?:credentials?|secrets?)(?:[._-]|$)/.test(name));
+}
+/** Files may be preserved without being executed. Credentials and machine state are never imported. */
+export function knowledgeRepositoryExclusion(path, mode = "100644") {
+    if (mode === "120000")
+        return "Symbolic link";
+    if (mode === "160000")
+        return "Submodule";
+    if (!path ||
+        path.startsWith("/") ||
+        path.includes("\\") ||
+        /[\x00-\x1f\x7f]/.test(path) ||
+        path.split("/").some((p) => p === "." || p === ".." || !p))
+        return "Unsafe path";
+    const parts = path.toLowerCase().split("/");
+    if (parts.some((p) => [".git", "node_modules", ".venv", "venv", ".ssh"].includes(p)))
+        return "Machine or dependency files";
+    const name = parts.at(-1);
+    if (isCredentialFile(name))
+        return "Credential file";
+    if (path.startsWith(".github/workflows/"))
+        return "GitHub automation";
+    if (/^\.obsidian\/(?:workspace(?:-mobile)?\.json|cache\/)/.test(path))
+        return "Device layout or cache";
+    return null;
+}
+export function normalizeKnowledgeRepositoryRoot(root) {
+    if (root === "" || root === "/")
+        return "";
+    const value = root.replace(/\/$/, "");
+    if (knowledgeRepositoryExclusion(`${value}/file.md`)) {
+        throw new OxygenError("invalid_knowledge_repository_root", "Choose a relative repository folder without parent paths or excluded directories.");
+    }
+    return value;
+}
+export function knowledgeRepositoryRelativePath(path, root) {
+    if (!root)
+        return path;
+    return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : null;
+}
+/** Conservative three-way merge: identical changes and disjoint line edits are safe.
+ * Overlap, edit/delete and binary changes retain both versions for an explicit decision. */
+export function mergeKnowledgeText(base, local, remote) {
+    if (local === remote)
+        return { kind: "merged", text: local };
+    if (base === local)
+        return { kind: "merged", text: remote };
+    if (base === remote)
+        return { kind: "merged", text: local };
+    if (base === null || local === null || remote === null)
+        return { kind: "conflict" };
+    const lines = (s) => s.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+    const original = lines(base);
+    const change = (s) => {
+        const updated = lines(s);
+        let start = 0, tail = 0;
+        while (start < original.length &&
+            start < updated.length &&
+            original[start] === updated[start])
+            start++;
+        while (tail < original.length - start &&
+            tail < updated.length - start &&
+            original[original.length - tail - 1] ===
+                updated[updated.length - tail - 1])
+            tail++;
+        return {
+            start,
+            end: original.length - tail,
+            insert: updated.slice(start, updated.length - tail),
+        };
+    };
+    const a = change(local), b = change(remote);
+    const safelyBefore = (first, second) => first.end < second.start ||
+        (first.end === second.start && first.start < first.end);
+    if (!(safelyBefore(a, b) || safelyBefore(b, a)))
+        return { kind: "conflict" };
+    const result = [...original];
+    for (const c of [a, b].sort((x, y) => y.start - x.start))
+        result.splice(c.start, c.end - c.start, ...c.insert);
+    return { kind: "merged", text: result.join("") };
+}
+export function parseKnowledgeLfsPointer(text) {
+    const match = /^version https:\/\/git-lfs.github.com\/spec\/v1\r?\noid sha256:([a-f0-9]{64})\r?\nsize (\d+)\r?\n?$/.exec(text);
+    if (!match)
+        return null;
+    const size = Number(match[2]);
+    if (!Number.isSafeInteger(size) || size < 0)
+        return null;
+    return { oid: match[1], size };
+}

package/node_modules/@oxygen/shared/dist/knowledge-vault-markdown.d.ts

@@ -0,0 +1,20 @@
+export declare const KNOWLEDGE_VAULT_MARKDOWN_MAX_BYTES = 1500000;
+export declare const KNOWLEDGE_VAULT_PATH_MAX_BYTES = 1024;
+export type KnowledgeVaultMarkdown = {
+    prefix: string;
+    body: string;
+};
+export type ParsedKnowledgeVaultMarkdown = KnowledgeVaultMarkdown & {
+    properties: Record<string, unknown>;
+    hasFrontmatter: boolean;
+    frontmatterError: string | null;
+};
+/** Paths are identities. Reject unsafe paths; never trim, lowercase or normalize them. */
+export declare function assertKnowledgeVaultPath(path: string): string;
+/** Fatal UTF-8 decoding and a roundtrip check prevent silent replacement of invalid bytes. */
+export declare function decodeKnowledgeVaultMarkdown(input: string | Uint8Array): string;
+export declare function parseKnowledgeVaultMarkdown(input: string | Uint8Array): ParsedKnowledgeVaultMarkdown;
+/** No renderer normalization, generated metadata, or implicit trailing newline. */
+export declare function renderKnowledgeVaultMarkdown(input: KnowledgeVaultMarkdown): string;
+/** Change one property without reserializing unrelated YAML or the Markdown body. */
+export declare function setKnowledgeVaultProperty(input: KnowledgeVaultMarkdown, key: string, value: unknown): KnowledgeVaultMarkdown;

package/node_modules/@oxygen/shared/dist/knowledge-vault-markdown.js

@@ -0,0 +1,155 @@
+import { isMap, parseDocument, stringify } from "yaml";
+import { OxygenError } from "./cli-result.js";
+export const KNOWLEDGE_VAULT_MARKDOWN_MAX_BYTES = 1_500_000;
+export const KNOWLEDGE_VAULT_PATH_MAX_BYTES = 1_024;
+function invalid(message) {
+    return new OxygenError("invalid_knowledge_file", message, { exitCode: 1 });
+}
+/** Paths are identities. Reject unsafe paths; never trim, lowercase or normalize them. */
+export function assertKnowledgeVaultPath(path) {
+    if (typeof path !== "string" ||
+        !path ||
+        new TextEncoder().encode(path).length > KNOWLEDGE_VAULT_PATH_MAX_BYTES ||
+        /[\x00-\x1f\x7f\\]/u.test(path) ||
+        path.startsWith("/") ||
+        /^[A-Za-z]:/.test(path) ||
+        path.split("/").some((part) => !part || part === "." || part === "..")) {
+        throw invalid("File path must be a relative path without empty, dot, parent or control-character segments.");
+    }
+    if (new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(new TextEncoder().encode(path)) !== path) {
+        throw invalid("File path must contain valid Unicode characters.");
+    }
+    return path;
+}
+/** Fatal UTF-8 decoding and a roundtrip check prevent silent replacement of invalid bytes. */
+export function decodeKnowledgeVaultMarkdown(input) {
+    const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+    if (bytes.byteLength > KNOWLEDGE_VAULT_MARKDOWN_MAX_BYTES)
+        throw invalid("Markdown file exceeds 1.5 MB.");
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw invalid("Markdown must contain valid UTF-8. Preserve other encodings as an attachment.");
+    }
+    if (text.includes("\0") || (typeof input === "string" && text !== input)) {
+        throw invalid("Markdown cannot contain NUL or invalid Unicode characters.");
+    }
+    return text;
+}
+function splitPrefix(text) {
+    const bom = text.startsWith("\ufeff") ? "\ufeff" : "";
+    const rest = text.slice(bom.length);
+    const open = /^---[ \t]*(?:\r\n|\n)/.exec(rest);
+    if (!open)
+        return { prefix: bom, body: rest, yaml: null, yamlOffset: bom.length };
+    const close = /^(?:---|\.\.\.)[ \t]*(?:\r\n|\n|$)/gm;
+    close.lastIndex = open[0].length;
+    const match = close.exec(rest);
+    if (!match)
+        return { prefix: bom, body: rest, yaml: null, yamlOffset: bom.length };
+    const end = match.index + match[0].length;
+    return {
+        prefix: bom + rest.slice(0, end),
+        body: rest.slice(end),
+        yaml: rest.slice(open[0].length, match.index),
+        yamlOffset: bom.length + open[0].length,
+    };
+}
+export function parseKnowledgeVaultMarkdown(input) {
+    const split = splitPrefix(decodeKnowledgeVaultMarkdown(input));
+    let properties = {};
+    let frontmatterError = null;
+    if (split.yaml !== null) {
+        try {
+            const doc = parseDocument(split.yaml, {
+                keepSourceTokens: true,
+                uniqueKeys: true,
+            });
+            if (doc.errors.length || doc.warnings.length)
+                throw new Error(doc.errors[0]?.message ?? doc.warnings[0]?.message);
+            const value = doc.toJS({ maxAliasCount: 50 });
+            if (value !== null && (typeof value !== "object" || Array.isArray(value)))
+                throw new Error("Frontmatter must be a YAML mapping.");
+            if (value)
+                properties = value;
+        }
+        catch (error) {
+            frontmatterError =
+                error instanceof Error ? error.message : "Invalid YAML frontmatter.";
+        }
+    }
+    return {
+        prefix: split.prefix,
+        body: split.body,
+        properties,
+        hasFrontmatter: split.yaml !== null,
+        frontmatterError,
+    };
+}
+/** No renderer normalization, generated metadata, or implicit trailing newline. */
+export function renderKnowledgeVaultMarkdown(input) {
+    return decodeKnowledgeVaultMarkdown(input.prefix + input.body);
+}
+/** Change one property without reserializing unrelated YAML or the Markdown body. */
+export function setKnowledgeVaultProperty(input, key, value) {
+    if (!key ||
+        /[\x00-\x1f\x7f]/u.test(key) ||
+        ["__proto__", "constructor", "prototype"].includes(key)) {
+        throw invalid("A valid frontmatter property name is required.");
+    }
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch {
+        throw invalid("Frontmatter value must be JSON-compatible.");
+    }
+    if (json === undefined)
+        throw invalid("Frontmatter value must be JSON-compatible.");
+    const full = renderKnowledgeVaultMarkdown(input);
+    const parsed = parseKnowledgeVaultMarkdown(full);
+    if (parsed.frontmatterError)
+        throw invalid("Fix invalid YAML frontmatter before editing its properties.");
+    const split = splitPrefix(full);
+    const newline = input.prefix.includes("\r\n") || input.body.includes("\r\n")
+        ? "\r\n"
+        : "\n";
+    const line = stringify({ [key]: JSON.parse(json) }).replace(/\n/g, newline);
+    if (split.yaml === null) {
+        const prefix = `${split.prefix}---${newline}${line}---${newline}`;
+        return { prefix, body: split.body };
+    }
+    const doc = parseDocument(split.yaml, {
+        keepSourceTokens: true,
+        uniqueKeys: true,
+    });
+    if (!isMap(doc.contents) && doc.contents !== null)
+        throw invalid("Frontmatter must be a YAML mapping.");
+    const pair = isMap(doc.contents)
+        ? doc.contents.items.find((entry) => String(entry.key) === key)
+        : undefined;
+    if (pair) {
+        const range = pair.value
+            ?.range;
+        if (!range)
+            throw invalid("This empty YAML value must be edited in the Markdown source.");
+        const start = split.yamlOffset + range[0];
+        const end = split.yamlOffset + range[1];
+        const old = split.prefix.slice(start, end);
+        const replacement = (split.prefix[start - 1] === ":" ? " " : "") +
+            json +
+            (split.prefix[end] === "#" ? " " : "") +
+            (old.endsWith("\n") ? newline : "");
+        return {
+            prefix: split.prefix.slice(0, start) + replacement + split.prefix.slice(end),
+            body: split.body,
+        };
+    }
+    const insertion = split.yamlOffset + split.yaml.length;
+    return {
+        prefix: split.prefix.slice(0, insertion) + line + split.prefix.slice(insertion),
+        body: split.body,
+    };
+}

package/node_modules/@oxygen/shared/dist/mailbox-import.d.ts

@@ -8,6 +8,16 @@ export type NormalizedMailboxImportRow = {
     infrastructure_platform?: "google_workspace" | "microsoft_365" | "microsoft_azure";
     tenant_id?: string;
     app_password?: string;
+    /**
+     * WHO the inbox sends as (v1.954.0 — an inbox always belongs to a sender).
+     * Non-secret identity, so it rides the same whitelist as the address: a vendor
+     * export that already knows the person spares the customer a guessed profile
+     * named from the address local part.
+     */
+    first_name?: string;
+    last_name?: string;
+    display_name?: string;
+    sender_profile_id?: string;
 };
 export type MailboxImportValidationSummary = {
     valid: true;

package/node_modules/@oxygen/shared/dist/mailbox-import.js

@@ -49,6 +49,27 @@ const MAILBOX_TENANT_HEADERS = new Set([
     "microsofttenantid",
     "tenantid",
 ]);
+const MAILBOX_FIRST_NAME_HEADERS = new Set([
+    "first",
+    "firstname",
+    "givenname",
+]);
+const MAILBOX_LAST_NAME_HEADERS = new Set([
+    "familyname",
+    "last",
+    "lastname",
+    "surname",
+]);
+const MAILBOX_DISPLAY_NAME_HEADERS = new Set([
+    "displayname",
+    "fromname",
+    "name",
+    "sendername",
+]);
+const MAILBOX_SENDER_PROFILE_HEADERS = new Set([
+    "senderprofile",
+    "senderprofileid",
+]);
 const MAILBOX_NON_TRANSFERABLE_SECRET_HEADERS = new Set([
     "accesstoken",
     "applicationsecret",
@@ -328,6 +349,17 @@ function normalizeMailboxExportRow(row, index, mode) {
             ? "microsoft_azure"
             : null);
     const infrastructurePlatform = normalizeMailboxInfrastructurePlatform(infrastructurePlatformRaw, provider, index);
+    // WHO the inbox sends as. Carried through because an inbox always belongs to a
+    // sender (v1.954.0): a file that already names the person is the difference
+    // between a real sender profile and one OXYGEN guesses from the address.
+    const firstName = readMailboxIdentityName(byHeader, MAILBOX_FIRST_NAME_HEADERS, index, "first_name");
+    const lastName = readMailboxIdentityName(byHeader, MAILBOX_LAST_NAME_HEADERS, index, "last_name");
+    const displayName = readMailboxIdentityName(byHeader, MAILBOX_DISPLAY_NAME_HEADERS, index, "display_name");
+    const senderProfileId = readUniqueMailboxExportString(byHeader, MAILBOX_SENDER_PROFILE_HEADERS, index, "sender_profile_id", (value) => value.trim().toLowerCase());
+    if (senderProfileId &&
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(senderProfileId)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].sender_profile_id must be a sender profile id (UUID). List them with \`oxygen senders profiles list\`, or drop the column and let the row's first/last name name the sender.`, { exitCode: 1 });
+    }
     return {
         email_address: email.trim().toLowerCase(),
         provider,
@@ -338,6 +370,10 @@ function normalizeMailboxExportRow(row, index, mode) {
             ? { infrastructure_platform: infrastructurePlatform }
             : {}),
         ...(tenantId ? { tenant_id: tenantId.trim().toLowerCase() } : {}),
+        ...(firstName ? { first_name: firstName } : {}),
+        ...(lastName ? { last_name: lastName } : {}),
+        ...(displayName ? { display_name: displayName } : {}),
+        ...(senderProfileId ? { sender_profile_id: senderProfileId } : {}),
         ...(mode === "credential" &&
             provider === "google" &&
             distinctPasswords[0] !== undefined
@@ -345,6 +381,23 @@ function normalizeMailboxExportRow(row, index, mode) {
             : {}),
     };
 }
+/**
+ * One identity half off an export row. Header-bound (the From name rides an SMTP
+ * header), so a CR/LF is refused by field name rather than silently stripped — the
+ * caller is usually holding hundreds of rows and needs to know which one.
+ */
+function readMailboxIdentityName(byHeader, headers, index, field) {
+    const value = readUniqueMailboxExportString(byHeader, headers, index, field, (raw) => raw.trim());
+    if (!value)
+        return null;
+    if (value.length > 200) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].${field} must be at most 200 characters.`, { exitCode: 1 });
+    }
+    if (/[\r\n]/.test(value)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].${field} must be a single line.`, { exitCode: 1 });
+    }
+    return value;
+}
 function normalizeMailboxExportHeader(value) {
     return value
         .replace(/^\uFEFF/, "")

package/node_modules/@oxygen/shared/dist/plan-limits.d.ts

@@ -78,6 +78,14 @@ export type PlanLimits = {
  */
 export declare const TABLE_IMPORT_ROW_LIMIT: 3000000;
 export { VERCEL_REQUEST_BODY_LIMIT_BYTES } from "./import-limits.js";
+/**
+ * OXYGEN's own JSON-body ceiling for every `/api/cli/*` route (enforced by
+ * `assertCliJsonBodyWithinLimit` on the content-length header). Shared so the CLI
+ * pre-splits a row batch by measured bytes instead of learning the number from a
+ * 413. Must stay below VERCEL_REQUEST_BODY_LIMIT_BYTES, and must never be raised
+ * in the CLI alone — an older server would still 413 at the old number.
+ */
+export declare const MAX_CLI_JSON_BODY_BYTES = 2000000;
 /**
  * The per-rung limit matrix. `ai_live` deliberately equals `tool_live` at every
  * rung — one "live actions" mental model; the per-call cost asymmetry between

package/node_modules/@oxygen/shared/dist/plan-limits.js

@@ -21,6 +21,14 @@ export const TABLE_IMPORT_ROW_LIMIT = WORKSPACE_TABLE_CAPACITY.tableRowLimit;
 // ceilings below ("how big can an import be"), but it must stay importable from a
 // browser bundle, so it is defined in ./import-limits and re-exported here.
 export { VERCEL_REQUEST_BODY_LIMIT_BYTES } from "./import-limits.js";
+/**
+ * OXYGEN's own JSON-body ceiling for every `/api/cli/*` route (enforced by
+ * `assertCliJsonBodyWithinLimit` on the content-length header). Shared so the CLI
+ * pre-splits a row batch by measured bytes instead of learning the number from a
+ * 413. Must stay below VERCEL_REQUEST_BODY_LIMIT_BYTES, and must never be raised
+ * in the CLI alone — an older server would still 413 at the old number.
+ */
+export const MAX_CLI_JSON_BODY_BYTES = 2_000_000;
 /**
  * The per-rung limit matrix. `ai_live` deliberately equals `tool_live` at every
  * rung — one "live actions" mental model; the per-call cost asymmetry between

package/node_modules/@oxygen/shared/dist/pricing-sheet.d.ts

@@ -176,7 +176,7 @@ export declare const ENRICHMENT_CREDITS: {
     readonly company_enrich_typical: 99;
     readonly web_search: 5;
     readonly page_scrape: 40;
-    readonly linkedin_profile_scrape: 25.5;
+    readonly linkedin_profile_scrape: 10;
 };
 /** Editable calculator default: blended credits per fully-enriched row. */
 export declare const ENRICHMENT_CREDITS_PER_ROW_TYPICAL = 100;

package/node_modules/@oxygen/shared/dist/pricing-sheet.js

@@ -163,7 +163,7 @@ export const ENRICHMENT_CREDITS = {
     company_enrich_typical: 99,
     web_search: 5, // Serper
     page_scrape: 40, // Firecrawl (wedge price)
-    linkedin_profile_scrape: 25.5, // HarvestAPI Basic full-profile job, exactly 5x COGS
+    linkedin_profile_scrape: 10, // Managed profile credit at $0.002 COGS, exactly 5x
 };
 /** Editable calculator default: blended credits per fully-enriched row. */
 export const ENRICHMENT_CREDITS_PER_ROW_TYPICAL = SNAPSHOT_ENRICHMENT_CREDITS_PER_ROW_TYPICAL;

package/node_modules/@oxygen/shared/dist/product-analytics-events.d.ts

@@ -77,6 +77,30 @@ export declare const PRODUCT_EVENTS: {
     readonly TRIAL_CANCEL_SCHEDULED: "trial_cancel_scheduled";
     readonly TRIAL_CANCEL_RESUMED: "trial_cancel_resumed";
     readonly TRIAL_ENDED_UNCONVERTED: "trial_ended_unconverted";
+    /**
+     * Marketing site. The public hero lookup on oxygen-agent.com: an ANONYMOUS
+     * visitor types their website and OXYGEN spends its own credits profiling it.
+     *
+     * Deliberately absent from the web's KPI_TYPE_TO_EVENT. These describe a
+     * pre-signup funnel step, not a lifecycle moment the company reports, and
+     * mapping one onto a `company_kpi_events` type would redefine a headline
+     * number without anyone editing that number's definition.
+     *
+     * Properties are enums, numbers and the domain HASH only — never the raw
+     * domain. The visitor has no account and never consented to their employer's
+     * name landing in an analytics warehouse (ADR 0021: PostHog stays sanitized).
+     * `hero_lookup_cached` is what says whether the lookup cache is paying for
+     * itself, which is the whole economics of the surface.
+     */
+    readonly HERO_LOOKUP_STARTED: "hero_lookup_started";
+    readonly HERO_PROFILE_COMPLETED: "hero_profile_completed";
+    readonly HERO_LEADS_COMPLETED: "hero_leads_completed";
+    readonly HERO_LOOKUP_CACHED: "hero_lookup_cached";
+    readonly HERO_LOOKUP_DEGRADED: "hero_lookup_degraded";
+    /** Browser-side hero events; props are enums, booleans and counts only. */
+    readonly HERO_LOOKUP_SUBMITTED: "hero_lookup_submitted";
+    readonly HERO_LOOKUP_RENDERED: "hero_lookup_rendered";
+    readonly HERO_SIGNUP_CLICKED: "hero_signup_clicked";
     /** Pipeline heartbeat: proves ingestion is alive when the product is quiet. */
     readonly POSTHOG_CANARY: "posthog_canary";
 };

package/node_modules/@oxygen/shared/dist/product-analytics-events.js

@@ -77,6 +77,30 @@ export const PRODUCT_EVENTS = {
     TRIAL_CANCEL_SCHEDULED: "trial_cancel_scheduled",
     TRIAL_CANCEL_RESUMED: "trial_cancel_resumed",
     TRIAL_ENDED_UNCONVERTED: "trial_ended_unconverted",
+    /**
+     * Marketing site. The public hero lookup on oxygen-agent.com: an ANONYMOUS
+     * visitor types their website and OXYGEN spends its own credits profiling it.
+     *
+     * Deliberately absent from the web's KPI_TYPE_TO_EVENT. These describe a
+     * pre-signup funnel step, not a lifecycle moment the company reports, and
+     * mapping one onto a `company_kpi_events` type would redefine a headline
+     * number without anyone editing that number's definition.
+     *
+     * Properties are enums, numbers and the domain HASH only — never the raw
+     * domain. The visitor has no account and never consented to their employer's
+     * name landing in an analytics warehouse (ADR 0021: PostHog stays sanitized).
+     * `hero_lookup_cached` is what says whether the lookup cache is paying for
+     * itself, which is the whole economics of the surface.
+     */
+    HERO_LOOKUP_STARTED: "hero_lookup_started",
+    HERO_PROFILE_COMPLETED: "hero_profile_completed",
+    HERO_LEADS_COMPLETED: "hero_leads_completed",
+    HERO_LOOKUP_CACHED: "hero_lookup_cached",
+    HERO_LOOKUP_DEGRADED: "hero_lookup_degraded",
+    /** Browser-side hero events; props are enums, booleans and counts only. */
+    HERO_LOOKUP_SUBMITTED: "hero_lookup_submitted",
+    HERO_LOOKUP_RENDERED: "hero_lookup_rendered",
+    HERO_SIGNUP_CLICKED: "hero_signup_clicked",
     /** Pipeline heartbeat: proves ingestion is alive when the product is quiet. */
     POSTHOG_CANARY: "posthog_canary",
 };

package/node_modules/@oxygen/shared/dist/recipes.d.ts

@@ -16,4 +16,10 @@ export type RecipePrerequisiteKind = typeof RECIPE_PREREQUISITE_KINDS[number];
 export declare const RECIPE_BODY_SECTIONS: readonly ["The Play", "What You Get", "When To Run (And When Not To)", "Before You Start", "Steps", "Ready Assets", "Calibrate", "Troubleshooting", "Operator Notes", "Related"];
 export declare const RECIPE_SLUG_PATTERN: RegExp;
 export declare function recipeWikiSlug(recipeSlug: string): string;
+export declare const RECIPE_KIT_MAX_STAGES = 6;
+export declare const RECIPE_KIT_TABLE_REF_PATTERN: RegExp;
+export declare const RECIPE_KIT_STAGE_STATUSES: readonly ["planned", "installed", "reused", "skipped_active", "blocked", "failed"];
+export type RecipeKitStageStatus = typeof RECIPE_KIT_STAGE_STATUSES[number];
+export type RecipeKitStatus = "not_applied" | "partial" | "applied";
+export declare function recipeKitSourceRef(recipeSlug: string, version: number): string;
 export declare const RECIPE_TRIAL_SAFE_PILOT_CREDIT_CAP = 100;

package/node_modules/@oxygen/shared/dist/recipes.js

@@ -87,6 +87,29 @@ export const RECIPE_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,119}$/;
 export function recipeWikiSlug(recipeSlug) {
     return `playbook-${recipeSlug}`;
 }
+// ── Kits (ADR 0025) ─────────────────────────────────────────────────────────
+// A recipe carries an ORDERED kit of Blueprint stages. `oxygen recipes apply`
+// preflights every stage into one forecast and installs them all under one
+// approval — 0 credits, no provider call, every installed Workflow disabled.
+// A stage may bind a table created by an earlier stage through a
+// `$stages.<index>.tables.<ref>` reference so later stages graft onto it
+// instead of creating a second table.
+export const RECIPE_KIT_MAX_STAGES = 6;
+export const RECIPE_KIT_TABLE_REF_PATTERN = /^\$stages\.(\d)\.tables\.([a-z][a-z0-9_]*)$/;
+export const RECIPE_KIT_STAGE_STATUSES = [
+    "planned",
+    "installed",
+    "reused",
+    "skipped_active",
+    "blocked",
+    "failed",
+];
+// page_sources ref an apply writes on the recipe's playbook page — one per
+// recipe version, ON CONFLICT DO NOTHING, so first-apply provenance survives
+// reapplies.
+export function recipeKitSourceRef(recipeSlug, version) {
+    return `https://oxygen-agent.com/recipes/${recipeSlug}@v${version}#kit`;
+}
 // trial_safe recipes must keep their pilot path within 10% of the 7-day
 // card-required trial's 1,000 managed credits.
 export const RECIPE_TRIAL_SAFE_PILOT_CREDIT_CAP = 100;