@oxygen-agent/cli 1.922.14 → 1.948.1

package/node_modules/@oxygen/shared/dist/email-warmup-readiness.d.ts

@@ -0,0 +1,64 @@
+/**
+ * PURE warm-up readiness rule: what daily cold volume a sending mailbox can
+ * actually carry, given its warm-up age rather than a provider's opinion of it.
+ *
+ * WHY it lives in @oxygen/shared and not next to the other email-health rules in
+ * @oxygen/integrations: the tenant rollup computes this per mailbox, and
+ * @oxygen/tenant-db must never import @oxygen/integrations (integrations depends
+ * on tenant-db). Duplicating the thresholds so each package could own a copy is
+ * exactly how two surfaces start recommending different numbers, so the rule is
+ * defined once here and re-exported from
+ * packages/integrations/src/email-health/health-state.ts, which stays the
+ * email-health surface every caller reads.
+ *
+ * DIRECTIONAL, like everything else in the deliverability cluster: it produces a
+ * recommendation and a launch-preview warning. It never clamps a cap, never
+ * pauses a mailbox, and never changes what a sequence sends.
+ */
+/** Below this warm-up day a mailbox should carry only the starter cold volume. */
+export declare const WARMUP_EARLY_DAY_LIMIT = 14;
+/** Below this warm-up day a mailbox should stay at the reduced cold volume. */
+export declare const WARMUP_ESTABLISHED_DAY_LIMIT = 28;
+/** Recommended cold sends/day before day 14 (and for an un-warmed young mailbox). */
+export declare const WARMUP_EARLY_DAILY_CAP = 5;
+/** Recommended cold sends/day between day 14 and day 28. */
+export declare const WARMUP_ESTABLISHED_DAILY_CAP = 10;
+/** A warm-up health score under this is treated as "not ready for volume". */
+export declare const WARMUP_HEALTH_SCORE_FLOOR = 60;
+/** Hard-bounce rate above which a fleet is burning its domains, not just its list. */
+export declare const HARD_BOUNCE_RATE_CEILING = 0.03;
+/** Below this send volume a bounce rate is noise, not a signal. */
+export declare const HARD_BOUNCE_RATE_MIN_SENDS = 20;
+/**
+ * The DIRECTIONAL per-mailbox daily cold-send ceiling warm-up readiness supports,
+ * or null when nothing in the evidence argues for holding volume back.
+ *
+ * Pure — the caller resolves `mailboxAgeDays` from created_at, so this stays
+ * clock-free and identical on every surface.
+ *
+ *   - warm-up day < 14                                    -> 5/day
+ *   - mailbox younger than 28 days, with either no active
+ *     warm-up or no warm-up day reported at all           -> 5/day
+ *   - warm-up day < 28                                    -> 10/day
+ *   - warm-up health score < 60                           -> at most 5/day
+ *   - otherwise                                           -> null (no advice)
+ *
+ * The second rule is the one that matters for a freshly provisioned fleet: a
+ * mailbox whose warm-up never started (state "unknown") reports no day at all,
+ * and a rule keyed only on the day number would have said nothing about the exact
+ * mailboxes most likely to get blocked.
+ */
+export declare function recommendedDailyCapForWarmup(input: {
+    warmupState?: string | null;
+    warmupDay?: number | null;
+    warmupHealthScore?: number | null;
+    mailboxAgeDays?: number | null;
+}): number | null;
+/**
+ * True when a hard-bounce count is high enough, over enough sends, to be a real
+ * reputation problem rather than list noise.
+ */
+export declare function hardBounceRateIsHigh(input: {
+    hardBounces: number;
+    coldSends: number;
+}): boolean;

package/node_modules/@oxygen/shared/dist/email-warmup-readiness.js

@@ -0,0 +1,90 @@
+/**
+ * PURE warm-up readiness rule: what daily cold volume a sending mailbox can
+ * actually carry, given its warm-up age rather than a provider's opinion of it.
+ *
+ * WHY it lives in @oxygen/shared and not next to the other email-health rules in
+ * @oxygen/integrations: the tenant rollup computes this per mailbox, and
+ * @oxygen/tenant-db must never import @oxygen/integrations (integrations depends
+ * on tenant-db). Duplicating the thresholds so each package could own a copy is
+ * exactly how two surfaces start recommending different numbers, so the rule is
+ * defined once here and re-exported from
+ * packages/integrations/src/email-health/health-state.ts, which stays the
+ * email-health surface every caller reads.
+ *
+ * DIRECTIONAL, like everything else in the deliverability cluster: it produces a
+ * recommendation and a launch-preview warning. It never clamps a cap, never
+ * pauses a mailbox, and never changes what a sequence sends.
+ */
+/** Below this warm-up day a mailbox should carry only the starter cold volume. */
+export const WARMUP_EARLY_DAY_LIMIT = 14;
+/** Below this warm-up day a mailbox should stay at the reduced cold volume. */
+export const WARMUP_ESTABLISHED_DAY_LIMIT = 28;
+/** Recommended cold sends/day before day 14 (and for an un-warmed young mailbox). */
+export const WARMUP_EARLY_DAILY_CAP = 5;
+/** Recommended cold sends/day between day 14 and day 28. */
+export const WARMUP_ESTABLISHED_DAILY_CAP = 10;
+/** A warm-up health score under this is treated as "not ready for volume". */
+export const WARMUP_HEALTH_SCORE_FLOOR = 60;
+/** Hard-bounce rate above which a fleet is burning its domains, not just its list. */
+export const HARD_BOUNCE_RATE_CEILING = 0.03;
+/** Below this send volume a bounce rate is noise, not a signal. */
+export const HARD_BOUNCE_RATE_MIN_SENDS = 20;
+/** Warm-up states in which a vendor is actively conditioning the mailbox. */
+const ACTIVE_WARMUP_STATES = new Set(["warming", "active"]);
+function finiteOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * The DIRECTIONAL per-mailbox daily cold-send ceiling warm-up readiness supports,
+ * or null when nothing in the evidence argues for holding volume back.
+ *
+ * Pure — the caller resolves `mailboxAgeDays` from created_at, so this stays
+ * clock-free and identical on every surface.
+ *
+ *   - warm-up day < 14                                    -> 5/day
+ *   - mailbox younger than 28 days, with either no active
+ *     warm-up or no warm-up day reported at all           -> 5/day
+ *   - warm-up day < 28                                    -> 10/day
+ *   - warm-up health score < 60                           -> at most 5/day
+ *   - otherwise                                           -> null (no advice)
+ *
+ * The second rule is the one that matters for a freshly provisioned fleet: a
+ * mailbox whose warm-up never started (state "unknown") reports no day at all,
+ * and a rule keyed only on the day number would have said nothing about the exact
+ * mailboxes most likely to get blocked.
+ */
+export function recommendedDailyCapForWarmup(input) {
+    const day = finiteOrNull(input.warmupDay);
+    const ageDays = finiteOrNull(input.mailboxAgeDays);
+    const healthScore = finiteOrNull(input.warmupHealthScore);
+    const warmingNow = ACTIVE_WARMUP_STATES.has((input.warmupState ?? "").trim().toLowerCase());
+    let cap = null;
+    if (day !== null && day < WARMUP_EARLY_DAY_LIMIT) {
+        cap = WARMUP_EARLY_DAILY_CAP;
+    }
+    else if (ageDays !== null &&
+        ageDays < WARMUP_ESTABLISHED_DAY_LIMIT &&
+        (day === null || !warmingNow)) {
+        // A rail that reports "warming" but no day number proves nothing about how
+        // far the ramp got, so age still governs. Gating this on !warmingNow alone
+        // left exactly that mailbox — enrolled, young, no telemetry — with no advice.
+        cap = WARMUP_EARLY_DAILY_CAP;
+    }
+    else if (day !== null && day < WARMUP_ESTABLISHED_DAY_LIMIT) {
+        cap = WARMUP_ESTABLISHED_DAILY_CAP;
+    }
+    if (healthScore !== null && healthScore < WARMUP_HEALTH_SCORE_FLOOR) {
+        cap = cap === null ? WARMUP_EARLY_DAILY_CAP : Math.min(cap, WARMUP_EARLY_DAILY_CAP);
+    }
+    return cap;
+}
+/**
+ * True when a hard-bounce count is high enough, over enough sends, to be a real
+ * reputation problem rather than list noise.
+ */
+export function hardBounceRateIsHigh(input) {
+    if (!Number.isFinite(input.coldSends) || input.coldSends < HARD_BOUNCE_RATE_MIN_SENDS) {
+        return false;
+    }
+    return input.hardBounces / input.coldSends > HARD_BOUNCE_RATE_CEILING;
+}

package/node_modules/@oxygen/shared/dist/feature-gates.d.ts

@@ -61,6 +61,8 @@ export type FeatureGateResolution = {
  * - OXYGEN_PUBLISHING_ENABLED — (b). Fail-closed production switch for posting
  *   to real provider accounts (`apps/web/src/app/(app)/(dashboard)/publishing/
  *   data.ts`). Wrong "on" = public posts from customer accounts.
+ * - OXYGEN_UGC_ENABLED — (b). Cross-workspace public posting and sponsored
+ *   paid jobs use a local fail-closed switch independent of flag services.
  * - OXYGEN_WORKER_AUTOSCALE — (b). Arms the worker fleet autoscaler, which STOPS
  *   production Machines (`apps/worker/src/fleet-autoscaler.ts`). Its worst wrong
  *   value takes the fleet down while work is queued, so it must never depend on a

package/node_modules/@oxygen/shared/dist/feature-gates.js

@@ -52,6 +52,8 @@
  * - OXYGEN_PUBLISHING_ENABLED — (b). Fail-closed production switch for posting
  *   to real provider accounts (`apps/web/src/app/(app)/(dashboard)/publishing/
  *   data.ts`). Wrong "on" = public posts from customer accounts.
+ * - OXYGEN_UGC_ENABLED — (b). Cross-workspace public posting and sponsored
+ *   paid jobs use a local fail-closed switch independent of flag services.
  * - OXYGEN_WORKER_AUTOSCALE — (b). Arms the worker fleet autoscaler, which STOPS
  *   production Machines (`apps/worker/src/fleet-autoscaler.ts`). Its worst wrong
  *   value takes the fleet down while work is queued, so it must never depend on a
@@ -67,6 +69,7 @@
 export const NEVER_FLAGGABLE = [
     "OXYGEN_WORKER_AUTOSCALE",
     "OXYGEN_PUBLISHING_ENABLED",
+    "OXYGEN_UGC_ENABLED",
     "OXYGEN_AGENTS_ENABLED",
     "OXYGEN_TELEMETRY_ENABLED",
     "OXYGEN_LOG_SHIPPING_ENABLED",

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

@@ -2,8 +2,10 @@ export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_V
 export { WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS, clearWorkflowTriggerAutoPauseMetadata, } from "./workflow-trigger-metadata.js";
 export { WORKFLOW_STATUS_CHANGE_METADATA_KEY, type WorkflowStatusChange, type WorkflowStatusChangeActor, type WorkflowStatusChangeSource, describeWorkflowStatusChange, formatWorkflowStatusChangeTimestamp, parseWorkflowStatusChange, readWorkflowStatusChange, } from "./workflow-status-change.js";
 export * from "./billing.js";
+export * from "./visual-render.js";
 export * from "./billing-anchors.js";
 export * from "./budget-scopes.js";
+export * from "./byok-connect.js";
 export * from "./capability-discovery.js";
 export * from "./user-capability-routing.js";
 export * from "./plan-capabilities.js";
@@ -11,6 +13,7 @@ export * from "./plan-limits.js";
 export * from "./sending-seats.js";
 export * from "./sending-seat-capacity.js";
 export * from "./plain-support-events.js";
+export * from "./provider-balance-signal.js";
 export * from "./provider-funding-errors.js";
 export * from "./publishing-limits.js";
 export * from "./spend-safety.js";
@@ -27,12 +30,17 @@ export * from "./copilot-journeys.js";
 export * from "./copilot-plan.js";
 export * from "./credit-guidance.js";
 export * from "./directory.js";
+export * from "./email-dsn.js";
+export * from "./email-warmup-readiness.js";
 export * from "./email-tracking-token.js";
 export * from "./email-unsubscribe-token.js";
 export * from "./error-redaction.js";
 export * from "./future-signup-events.js";
 export * from "./future-signup-lifecycle-projection.js";
 export * from "./feature-gates.js";
+export * from "./product-analytics-core.js";
+export * from "./product-analytics-environment.js";
+export * from "./product-analytics-events.js";
 export * from "./hosted-ai.js";
 export * from "./identifiers.js";
 export * from "./knowledge-constants.js";
@@ -41,6 +49,7 @@ export * from "./knowledge-links.js";
 export * from "./knowledge-markdown.js";
 export * from "./knowledge-seed-content.js";
 export * from "./langfuse.js";
+export * from "./llm-usage.js";
 export * from "./linkedin-mentions.js";
 export * from "./linkedin-post-url.js";
 export * from "./linkedin-quota-denial.js";
@@ -109,3 +118,4 @@ export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
 export declare function isVersionGreater(a: string, b: string): boolean;
 /** True when `a` is a strictly lesser semantic version than `b`. */
 export declare function isVersionLess(a: string, b: string): boolean;
+export * from "./ugc.js";

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

@@ -2,8 +2,10 @@ export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_V
 export { WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS, clearWorkflowTriggerAutoPauseMetadata, } from "./workflow-trigger-metadata.js";
 export { WORKFLOW_STATUS_CHANGE_METADATA_KEY, describeWorkflowStatusChange, formatWorkflowStatusChangeTimestamp, parseWorkflowStatusChange, readWorkflowStatusChange, } from "./workflow-status-change.js";
 export * from "./billing.js";
+export * from "./visual-render.js";
 export * from "./billing-anchors.js";
 export * from "./budget-scopes.js";
+export * from "./byok-connect.js";
 export * from "./capability-discovery.js";
 export * from "./user-capability-routing.js";
 export * from "./plan-capabilities.js";
@@ -11,6 +13,7 @@ export * from "./plan-limits.js";
 export * from "./sending-seats.js";
 export * from "./sending-seat-capacity.js";
 export * from "./plain-support-events.js";
+export * from "./provider-balance-signal.js";
 export * from "./provider-funding-errors.js";
 export * from "./publishing-limits.js";
 export * from "./spend-safety.js";
@@ -27,12 +30,17 @@ export * from "./copilot-journeys.js";
 export * from "./copilot-plan.js";
 export * from "./credit-guidance.js";
 export * from "./directory.js";
+export * from "./email-dsn.js";
+export * from "./email-warmup-readiness.js";
 export * from "./email-tracking-token.js";
 export * from "./email-unsubscribe-token.js";
 export * from "./error-redaction.js";
 export * from "./future-signup-events.js";
 export * from "./future-signup-lifecycle-projection.js";
 export * from "./feature-gates.js";
+export * from "./product-analytics-core.js";
+export * from "./product-analytics-environment.js";
+export * from "./product-analytics-events.js";
 export * from "./hosted-ai.js";
 export * from "./identifiers.js";
 export * from "./knowledge-constants.js";
@@ -41,6 +49,7 @@ export * from "./knowledge-links.js";
 export * from "./knowledge-markdown.js";
 export * from "./knowledge-seed-content.js";
 export * from "./langfuse.js";
+export * from "./llm-usage.js";
 export * from "./linkedin-mentions.js";
 export * from "./linkedin-post-url.js";
 export * from "./linkedin-quota-denial.js";
@@ -145,3 +154,4 @@ export function isVersionGreater(a, b) {
 export function isVersionLess(a, b) {
     return compareSemver(a, b) < 0;
 }
+export * from "./ugc.js";

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

@@ -2,28 +2,35 @@
  * Knowledge bootstrap — the once-per-workspace, automatic company research pass.
  *
  * WHAT IT IS. Exactly once in a workspace's life, OXYGEN researches the customer's
- * OWN company from the domain we already resolved at org creation
- * (control-DB `organizations.iconDomain`, `iconStatus = 'ok'`), then fills the typed
- * company profile (`ox_context.company_profile`) and writes one cited wiki page.
- * A founder who signs up should not face an empty Knowledge Graph and have to type
- * their own positioning back at us; every grounded AI action downstream (message
- * drafts, AI columns, agent runs) reads that profile, so an empty one degrades the
- * whole product's first hour.
+ * OWN company from the domain the creator typed when the workspace was created
+ * (control-DB `organizations.iconDomain`), then fills the typed company profile
+ * (`ox_context.company_profile`) and writes one cited wiki page. A founder who
+ * signs up should not face an empty Knowledge Graph and have to type their own
+ * positioning back at us; every grounded AI action downstream (message drafts, AI
+ * columns, agent runs) reads that profile, so an empty one degrades the whole
+ * product's first hour.
  *
  * WHY THIS IS NOT A VIOLATION OF THE PAID-ACTIONS RULE. `CLAUDE.md` says never run
  * paid provider actions unless the user explicitly asks. This slice is a deliberate,
- * founder-approved exception: signup IS the standing authorization, the same way an
- * armed table-webhook auto-run configuration is scoped standing permission for the
- * columns it queues. The exception is defensible ONLY because every one of the
- * following properties holds. They are load-bearing — do not drop one for
+ * founder-approved exception: naming the company at workspace creation IS the
+ * standing authorization, the same way an armed table-webhook auto-run
+ * configuration is scoped standing permission for the columns it queues — and
+ * since 2026-09-11 the pass is OXYGEN-funded, so it never draws down the
+ * customer's balance at all. The exception is defensible ONLY because every one of
+ * the following properties holds. They are load-bearing — do not drop one for
  * convenience, and if you remove one, the exception no longer stands:
  *
  *   1. CAPPED      — `KNOWLEDGE_BOOTSTRAP_MAX_CREDITS` is a hard ceiling on the whole
  *                    pass, with `KNOWLEDGE_BOOTSTRAP_ENRICHMENT_MAX_CREDITS` a tighter
- *                    sub-ceiling on the provider (external-money) half.
- *   2. CONSENTED   — it runs only for a workspace whose own domain we already derived
- *                    at signup; a personal-email signup is `skipped_personal_email`
- *                    upstream and never reaches here, so we never research a stranger.
+ *                    sub-ceiling on the provider (external-money) half. The cap bounds
+ *                    OXYGEN's own money now, and it is the same number.
+ *   2. AUTHORIZED  — it runs only for a workspace whose creator typed the company
+ *                    website into the REQUIRED field at workspace creation; that
+ *                    entry is recorded as `knowledge_bootstrap_consent` (source
+ *                    `workspace_creation`) and read FAIL-CLOSED, so a workspace that
+ *                    predates the field is never researched and a personal-email
+ *                    signup with no website never reaches the worker. We never
+ *                    research a stranger.
  *   3. JOURNALLED  — the marker below records status, timing, run id, credits and the
  *                    domain in `knowledge_state.watermarks`; the URLs read land as
  *                    immutable `page_sources` rows plus an `ingest` knowledge_log
@@ -36,6 +43,14 @@
  *                    ordinary revisioned wiki writes a human can revert.
  *   6. EXACTLY-ONCE — the marker is claimed with a conditional UPDATE, so N worker
  *                    replicas polling one tenant produce one run, never N runs.
+ *   7. OXYGEN-FUNDED — the automatic pass meters managed credits through the ordinary
+ *                    tool and AI-column lanes (so the cap, the marker and the run row
+ *                    all stay honest), and the worker then grants exactly the credits
+ *                    it used back to the workspace as an idempotent `bonus` ledger
+ *                    row keyed by the run (`KNOWLEDGE_BOOTSTRAP_COVERAGE_IDEMPOTENCY_PREFIX`).
+ *                    The customer's balance nets to zero and both rows are visible in
+ *                    their ledger. Only the AUTOMATIC pass is covered: a requested
+ *                    `--live --max-credits` re-run is the customer's own paid action.
  *
  * CAP ARITHMETIC (prices re-read from packages/integrations/src/cogs-rates.ts —
  * confirm them there rather than trusting this comment after a re-pricing):
@@ -52,8 +67,9 @@
  *                                overall ceiling.
  *   Hard cap           300 cr  — 85 cr nominal plus room for two retried synthesis
  *                                passes. 3% of the 10,000-credit signup grant
- *                                (FREE_SIGNUP_GRANT_CREDITS, ./billing.ts), so the
- *                                pass can never eat a founder's trial.
+ *                                (FREE_SIGNUP_GRANT_CREDITS, ./billing.ts), which is
+ *                                the headroom the balance gate needs even though the
+ *                                spend is granted back.
  *
  *   The obvious implementation — firecrawl.map + 3x firecrawl.scrape — costs
  *   4 x 40 = 160 cr for the SAME job, because Firecrawl bills per page. exa.contents
@@ -164,9 +180,11 @@ export type KnowledgeBootstrapMarker = {
     linkedin_url?: string | null;
 };
 /**
- * Control-DB `organizations.metadata` key carrying the workspace's recorded consent
- * to the automatic research pass. Written once at signup by the setup surface; read
- * by the worker cycle before anything is spent.
+ * Control-DB `organizations.metadata` key carrying the workspace's recorded
+ * authorization for the automatic research pass. Written once, when the creator
+ * names the company website at workspace creation (`source: "workspace_creation"`;
+ * rows written by the retired `/setup` checkbox carry `source: "signup"` and stay
+ * valid); read by the worker cycle before anything is spent.
  *
  * It lives in shared, not in either caller, so the writer and the reader cannot
  * drift onto two different key names — a silent drift there would either deny every
@@ -178,7 +196,10 @@ export declare const KNOWLEDGE_BOOTSTRAP_CONSENT_METADATA_KEY = "knowledge_boots
 export type KnowledgeBootstrapConsent = {
     /** ISO timestamp consent was recorded. Must parse; a marker that does not is not consent. */
     granted_at: string;
-    /** Where it came from, e.g. `signup`. Informational. */
+    /**
+     * Where it came from: `workspace_creation` (the required website field on the
+     * create-workspace screen) or the retired `signup` checkbox. Informational.
+     */
     source: string | null;
     /** Clerk user who accepted, when the surface knows. Informational. */
     granted_by_clerk_user_id: string | null;
@@ -227,6 +248,14 @@ export declare const KNOWLEDGE_BOOTSTRAP_LINKEDIN_METADATA_KEY = "company_linked
  * dead and the workspace is recoverable through the product.
  */
 export declare const KNOWLEDGE_BOOTSTRAP_STUCK_AFTER_MS: number;
+/**
+ * Idempotency-key prefix for the ledger row that hands an automatic pass's
+ * credits back to the workspace (property 7 above). The key is
+ * `${prefix}:${run_id}`, so one pass is covered exactly once no matter how many
+ * times the worker revisits the outcome, and a `--force` re-run — a different
+ * run — is covered only if it was itself automatic.
+ */
+export declare const KNOWLEDGE_BOOTSTRAP_COVERAGE_IDEMPOTENCY_PREFIX = "knowledge_bootstrap_coverage";
 /**
  * The one wiki page a bootstrap authors. A stable slug is what makes a re-armed pass
  * REVISE the note rather than litter the wiki with `company-research-2`.

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

@@ -2,28 +2,35 @@
  * Knowledge bootstrap — the once-per-workspace, automatic company research pass.
  *
  * WHAT IT IS. Exactly once in a workspace's life, OXYGEN researches the customer's
- * OWN company from the domain we already resolved at org creation
- * (control-DB `organizations.iconDomain`, `iconStatus = 'ok'`), then fills the typed
- * company profile (`ox_context.company_profile`) and writes one cited wiki page.
- * A founder who signs up should not face an empty Knowledge Graph and have to type
- * their own positioning back at us; every grounded AI action downstream (message
- * drafts, AI columns, agent runs) reads that profile, so an empty one degrades the
- * whole product's first hour.
+ * OWN company from the domain the creator typed when the workspace was created
+ * (control-DB `organizations.iconDomain`), then fills the typed company profile
+ * (`ox_context.company_profile`) and writes one cited wiki page. A founder who
+ * signs up should not face an empty Knowledge Graph and have to type their own
+ * positioning back at us; every grounded AI action downstream (message drafts, AI
+ * columns, agent runs) reads that profile, so an empty one degrades the whole
+ * product's first hour.
  *
  * WHY THIS IS NOT A VIOLATION OF THE PAID-ACTIONS RULE. `CLAUDE.md` says never run
  * paid provider actions unless the user explicitly asks. This slice is a deliberate,
- * founder-approved exception: signup IS the standing authorization, the same way an
- * armed table-webhook auto-run configuration is scoped standing permission for the
- * columns it queues. The exception is defensible ONLY because every one of the
- * following properties holds. They are load-bearing — do not drop one for
+ * founder-approved exception: naming the company at workspace creation IS the
+ * standing authorization, the same way an armed table-webhook auto-run
+ * configuration is scoped standing permission for the columns it queues — and
+ * since 2026-09-11 the pass is OXYGEN-funded, so it never draws down the
+ * customer's balance at all. The exception is defensible ONLY because every one of
+ * the following properties holds. They are load-bearing — do not drop one for
  * convenience, and if you remove one, the exception no longer stands:
  *
  *   1. CAPPED      — `KNOWLEDGE_BOOTSTRAP_MAX_CREDITS` is a hard ceiling on the whole
  *                    pass, with `KNOWLEDGE_BOOTSTRAP_ENRICHMENT_MAX_CREDITS` a tighter
- *                    sub-ceiling on the provider (external-money) half.
- *   2. CONSENTED   — it runs only for a workspace whose own domain we already derived
- *                    at signup; a personal-email signup is `skipped_personal_email`
- *                    upstream and never reaches here, so we never research a stranger.
+ *                    sub-ceiling on the provider (external-money) half. The cap bounds
+ *                    OXYGEN's own money now, and it is the same number.
+ *   2. AUTHORIZED  — it runs only for a workspace whose creator typed the company
+ *                    website into the REQUIRED field at workspace creation; that
+ *                    entry is recorded as `knowledge_bootstrap_consent` (source
+ *                    `workspace_creation`) and read FAIL-CLOSED, so a workspace that
+ *                    predates the field is never researched and a personal-email
+ *                    signup with no website never reaches the worker. We never
+ *                    research a stranger.
  *   3. JOURNALLED  — the marker below records status, timing, run id, credits and the
  *                    domain in `knowledge_state.watermarks`; the URLs read land as
  *                    immutable `page_sources` rows plus an `ingest` knowledge_log
@@ -36,6 +43,14 @@
  *                    ordinary revisioned wiki writes a human can revert.
  *   6. EXACTLY-ONCE — the marker is claimed with a conditional UPDATE, so N worker
  *                    replicas polling one tenant produce one run, never N runs.
+ *   7. OXYGEN-FUNDED — the automatic pass meters managed credits through the ordinary
+ *                    tool and AI-column lanes (so the cap, the marker and the run row
+ *                    all stay honest), and the worker then grants exactly the credits
+ *                    it used back to the workspace as an idempotent `bonus` ledger
+ *                    row keyed by the run (`KNOWLEDGE_BOOTSTRAP_COVERAGE_IDEMPOTENCY_PREFIX`).
+ *                    The customer's balance nets to zero and both rows are visible in
+ *                    their ledger. Only the AUTOMATIC pass is covered: a requested
+ *                    `--live --max-credits` re-run is the customer's own paid action.
  *
  * CAP ARITHMETIC (prices re-read from packages/integrations/src/cogs-rates.ts —
  * confirm them there rather than trusting this comment after a re-pricing):
@@ -52,8 +67,9 @@
  *                                overall ceiling.
  *   Hard cap           300 cr  — 85 cr nominal plus room for two retried synthesis
  *                                passes. 3% of the 10,000-credit signup grant
- *                                (FREE_SIGNUP_GRANT_CREDITS, ./billing.ts), so the
- *                                pass can never eat a founder's trial.
+ *                                (FREE_SIGNUP_GRANT_CREDITS, ./billing.ts), which is
+ *                                the headroom the balance gate needs even though the
+ *                                spend is granted back.
  *
  *   The obvious implementation — firecrawl.map + 3x firecrawl.scrape — costs
  *   4 x 40 = 160 cr for the SAME job, because Firecrawl bills per page. exa.contents
@@ -132,12 +148,14 @@ export function isKnowledgeBootstrapStatus(value) {
         KNOWLEDGE_BOOTSTRAP_STATUSES.includes(value));
 }
 // ---------------------------------------------------------------------------
-// Consent (property 2 of the exception above, made explicit)
+// Authorization (property 2 of the exception above, made explicit)
 // ---------------------------------------------------------------------------
 /**
- * Control-DB `organizations.metadata` key carrying the workspace's recorded consent
- * to the automatic research pass. Written once at signup by the setup surface; read
- * by the worker cycle before anything is spent.
+ * Control-DB `organizations.metadata` key carrying the workspace's recorded
+ * authorization for the automatic research pass. Written once, when the creator
+ * names the company website at workspace creation (`source: "workspace_creation"`;
+ * rows written by the retired `/setup` checkbox carry `source: "signup"` and stay
+ * valid); read by the worker cycle before anything is spent.
  *
  * It lives in shared, not in either caller, so the writer and the reader cannot
  * drift onto two different key names — a silent drift there would either deny every
@@ -208,6 +226,14 @@ export const KNOWLEDGE_BOOTSTRAP_LINKEDIN_METADATA_KEY = "company_linkedin_url";
  * dead and the workspace is recoverable through the product.
  */
 export const KNOWLEDGE_BOOTSTRAP_STUCK_AFTER_MS = 60 * 60 * 1000;
+/**
+ * Idempotency-key prefix for the ledger row that hands an automatic pass's
+ * credits back to the workspace (property 7 above). The key is
+ * `${prefix}:${run_id}`, so one pass is covered exactly once no matter how many
+ * times the worker revisits the outcome, and a `--force` re-run — a different
+ * run — is covered only if it was itself automatic.
+ */
+export const KNOWLEDGE_BOOTSTRAP_COVERAGE_IDEMPOTENCY_PREFIX = "knowledge_bootstrap_coverage";
 // ---------------------------------------------------------------------------
 // Write targets (what a bootstrap actually changes)
 // ---------------------------------------------------------------------------

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

@@ -3,7 +3,7 @@ export type KnowledgePageType = typeof KNOWLEDGE_PAGE_TYPES[number];
 export declare const KNOWLEDGE_META_PAGE_TYPES: readonly ["schema", "source_summary", "report"];
 export declare const KNOWLEDGE_PAGE_STATUSES: readonly ["draft", "active", "archived"];
 export type KnowledgePageStatus = typeof KNOWLEDGE_PAGE_STATUSES[number];
-export declare const RESERVED_KNOWLEDGE_SLUGS: readonly ["index", "log", "schema", "company-profile", "readme"];
+export declare const RESERVED_KNOWLEDGE_SLUGS: readonly ["index", "log", "schema", "company-profile", "readme", "new"];
 export declare const KNOWLEDGE_SLUG_MAX_LENGTH = 120;
 export declare const KNOWLEDGE_SLUG_PATTERN: RegExp;
 export declare function isValidKnowledgeSlug(value: string): boolean;

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

@@ -32,17 +32,18 @@ export const KNOWLEDGE_PAGE_TYPES = [
 export const KNOWLEDGE_META_PAGE_TYPES = ["schema", "source_summary", "report"];
 export const KNOWLEDGE_PAGE_STATUSES = ["draft", "active", "archived"];
 // Slugs the write path refuses (the scaffold seeder may create `schema`): they are
-// computed projections or virtual pages, never ordinary rows.
+// computed projections, virtual pages, or static UI routes, never ordinary rows.
 export const RESERVED_KNOWLEDGE_SLUGS = [
     "index",
     "log",
     "schema",
     "company-profile",
     "readme",
+    "new",
 ];
 export const KNOWLEDGE_SLUG_MAX_LENGTH = 120;
 // Flat kebab grammar: lowercase alphanumeric + dashes, no leading/trailing dash,
-// no slashes (pages are a flat namespace; the graph, tags, and types organize).
+// no slashes (slugs are a flat namespace; folders, the graph, tags, and types organize).
 export const KNOWLEDGE_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,119}$/;
 export function isValidKnowledgeSlug(value) {
     return KNOWLEDGE_SLUG_PATTERN.test(value);

package/node_modules/@oxygen/shared/dist/knowledge-seed-content.js

@@ -84,7 +84,7 @@ Index-first → open only relevant pages → answer citing slugs → file durabl
 | \`schema\` | describes the wiki itself (this page) |
 
 ## Slugs
-Flat kebab: lowercase alphanumerics + dashes, no slashes, ≤120 chars. **Immutable once created** — choose the durable name (\`competitor-clay\`, not \`clay-notes-july\`). No folders; types, tags, and wikilinks organize. Reserved (never create): \`index\`, \`log\`, \`schema\`, \`company-profile\`, \`readme\`.
+Flat kebab: lowercase alphanumerics + dashes, no slashes, ≤120 chars. **Immutable once created** — choose the durable name (\`competitor-clay\`, not \`clay-notes-july\`). Nested folders organize pages in the explorer without changing slugs or wikilinks; types and tags provide additional organization. Reserved (never create): \`index\`, \`log\`, \`schema\`, \`company-profile\`, \`readme\`, \`new\`.
 
 ## Wikilinks
 Wrap a slug in double square brackets to link it. Three forms all resolve to the same page — bare (\`slug\`), aliased (\`slug|display text\`), and heading-anchored (\`slug#heading\`) — because the alias and the heading are stripped before lookup. **Linking to a page that doesn't exist yet is good** — the dashed node is a visible to-do. Every page should link out (avoid dead-ends) and be linked to (avoid orphans).

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

@@ -39,6 +39,7 @@ export type LlmSpanBody = {
 };
 export type LlmGenerationBody = LlmSpanBody & {
     model?: string | null;
+    modelParameters?: Record<string, unknown>;
     completionStartTime?: Date | null;
     usageDetails?: Record<string, number>;
     costDetails?: Record<string, number>;
@@ -74,6 +75,7 @@ export type LlmTracingClient = {
     trace(body: LlmTraceBody): void;
     span(body: LlmSpanBody): void;
     generation(body: LlmGenerationBody): void;
+    embedding(body: LlmGenerationBody): void;
     event(body: LlmEventBody): void;
     /**
      * Attach a score to an existing trace.
@@ -90,9 +92,9 @@ export type LlmTracingClient = {
      * describes.
      */
     score(body: LlmScoreBody): Promise<boolean>;
-    /** Never rejects; bounded at ~5s. */
+    /** Never rejects; bounded at 5s on workers, 15s in serverless after(). */
     flush(): Promise<void>;
-    /** Flush + stop background timers. Never rejects; bounded at ~5s. */
+    /** Flush + stop timers. Same worker/serverless bound as flush(). */
     shutdown(): Promise<void>;
 };
 /**
@@ -114,7 +116,7 @@ export declare function resolveLlmTracingEnvironment(env?: EnvMap): string;
  * the SDK's own implementation so the two can never drift.
  */
 export declare function llmTraceIdForSeed(seed: string): string;
-export type LlmEmissionKind = "span" | "generation" | "event";
+export type LlmEmissionKind = "span" | "generation" | "embedding" | "event";
 /** v5 correlating attributes, propagated onto the emitted observation. */
 export type LlmCorrelation = {
     traceName?: string;
@@ -124,6 +126,9 @@ export type LlmCorrelation = {
 };
 export type LlmEmission = {
     kind: LlmEmissionKind;
+    observationId?: string;
+    parentObservationId?: string;
+    isRoot?: boolean;
     /** External seed (turn/run id) — hashed into the W3C trace id. */
     traceSeed: string;
     name: string;