@oxygen-agent/cli 1.888.6 → 1.893.0

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

@@ -0,0 +1,255 @@
+/**
+ * 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.
+ *
+ * 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
+ * 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.
+ *   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
+ *                    entry. Nothing about the spend is invisible.
+ *   4. KILL-SWITCHED — `OXYGEN_KNOWLEDGE_BOOTSTRAP_DISABLED` stops it fleet-wide at
+ *                    the worker with no deploy, matching the other OXYGEN_KNOWLEDGE_*
+ *                    switches.
+ *   5. REVERSIBLE  — the marker is a single jsonb key; clearing it (the `--force`
+ *                    path) re-arms the pass, and the pages/profile it wrote are
+ *                    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.
+ *
+ * CAP ARITHMETIC (prices re-read from packages/integrations/src/cogs-rates.ts —
+ * confirm them there rather than trusting this comment after a re-pricing):
+ *
+ *   serper.search           5 cr per call   (cogs-rates: serper.customerOxygen…search)
+ *   exa.contents            5 cr per CALL   (not per URL — this is the whole trick)
+ *   AI column, medium tier 75 cr per run    (pricing-sheet: AI_COLUMN_CREDITS.medium)
+ *
+ *   Happy path  = 1 serper.search (5) + 1 exa.contents over <= 5 URLs (5)
+ *                 + 1 medium synthesis pass (75)                        =  85 cr
+ *   Enrichment sub-cap  60 cr  — ~6x the 10 cr the happy path needs, so a waterfall
+ *                                retry or a second search fits, and a runaway
+ *                                per-URL fetch loop is stopped long before the
+ *                                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.
+ *
+ *   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
+ *   is priced per call and is built for fetching text at known URLs; that is why the
+ *   read budget is a page COUNT (`KNOWLEDGE_BOOTSTRAP_MAX_PAGES_READ`) inside one
+ *   call rather than a call count.
+ *
+ * This module is a leaf: constants and types only, no DB and no provider imports, so
+ * the worker, tenant-db, CLI, and API surfaces all bind to one contract.
+ */
+import type { HostedAiLevel } from "./hosted-ai.js";
+/** Hard ceiling on managed credits ONE workspace bootstrap may spend, all phases. */
+export declare const KNOWLEDGE_BOOTSTRAP_MAX_CREDITS = 300;
+/**
+ * Tighter sub-ceiling on the provider/enrichment half (search + page fetch), i.e.
+ * the external-money phase. Reaching it degrades the pass to `partial` — synthesize
+ * from what was read — rather than failing it.
+ */
+export declare const KNOWLEDGE_BOOTSTRAP_ENRICHMENT_MAX_CREDITS = 60;
+/**
+ * Reasoning tier the synthesis pass runs at. `medium` ("Oxygen Balanced") is the
+ * deliberate middle: `low` cannot hold a company profile's structure together, and
+ * `high` triples the cost of a pass nobody asked for.
+ */
+export declare const KNOWLEDGE_BOOTSTRAP_SYNTHESIS_TIER: HostedAiLevel;
+/**
+ * Most URLs whose text the pass may read — inside ONE `exa.contents` call, which is
+ * priced per call. Raising this raises latency and prompt size, not provider spend;
+ * it is a quality/latency knob, and the credit ceilings above remain the money guard.
+ */
+export declare const KNOWLEDGE_BOOTSTRAP_MAX_PAGES_READ = 5;
+/** Fleet-wide kill switch, matching OXYGEN_KNOWLEDGE_RETRIEVAL/AUTO_SOURCES_DISABLED. */
+export declare const KNOWLEDGE_BOOTSTRAP_DISABLED_ENV_VAR = "OXYGEN_KNOWLEDGE_BOOTSTRAP_DISABLED";
+/**
+ * Is the automatic bootstrap disabled by operator env?
+ *
+ * Unset = ENABLED (this is a fail-OPEN switch, unlike the free-grant flag): the
+ * feature is meant to run for every eligible workspace, and the kill switch exists to
+ * stop it fleet-wide in an incident with no deploy. `"1"` or `"true"` disables it;
+ * any other value is treated as unset, exactly like the sibling knowledge switches.
+ */
+export declare function knowledgeBootstrapDisabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * Lifecycle of the once-ever marker.
+ *
+ *   queued    — reserved: a surface claimed the slot but has not started work.
+ *   running   — claimed by a worker replica; the pass is in flight.
+ *   completed — profile + wiki page written.
+ *   partial   — some evidence gathered and written, but a cap, a provider failure, or
+ *               a thin domain stopped it short. Deliberately TERMINAL.
+ *   skipped   — never attempted for a policy reason (no domain, personal-email
+ *               signup, kill switch, zero spendable balance). `reason` says which.
+ *   failed    — attempted and errored. Also TERMINAL.
+ *
+ * Every one of these blocks a second claim: "once per workspace, ever" means the
+ * marker's mere EXISTENCE is the lock, not its value. A human re-arms the pass with
+ * `--force` (`POST /api/cli/knowledge/bootstrap`, which calls tenant-db's
+ * `requeueKnowledgeBootstrap`) — the one deliberate way to spend a second time. It
+ * overwrites every status above EXCEPT a `running` marker that is still LIVE, i.e.
+ * whose `started_at` is inside {@link KNOWLEDGE_BOOTSTRAP_STUCK_AFTER_MS}; a `running`
+ * marker older than that window is stale and IS re-armable, which is how a wedged pass
+ * is recovered without hand-written SQL.
+ */
+export declare const KNOWLEDGE_BOOTSTRAP_STATUSES: readonly ["queued", "running", "completed", "partial", "skipped", "failed"];
+export type KnowledgeBootstrapStatus = (typeof KNOWLEDGE_BOOTSTRAP_STATUSES)[number];
+export declare function isKnowledgeBootstrapStatus(value: unknown): value is KnowledgeBootstrapStatus;
+/**
+ * The marker itself, stored VERBATIM at `knowledge_state.watermarks -> 'bootstrap'`.
+ * Field names are snake_case because this type IS the on-disk jsonb shape — keeping
+ * them identical means a human reading the row and an agent reading the type see the
+ * same thing.
+ */
+export type KnowledgeBootstrapMarker = {
+    status: KnowledgeBootstrapStatus;
+    /** ISO timestamp the claim was won. */
+    started_at: string | null;
+    /** ISO timestamp a terminal status was written; null while `queued`/`running`. */
+    completed_at: string | null;
+    /** `ox_runs.runs` id (source_type `system`) carrying the observable run. */
+    run_id: string | null;
+    /** Managed credits actually spent, across every phase. Never exceeds the cap. */
+    credits_used: number;
+    /** The workspace domain researched (from organizations.iconDomain). */
+    domain: string | null;
+    /** Why a pass was skipped/partial/failed — a short machine-ish token, not prose. */
+    reason: string | null;
+    /** Slugs of the wiki pages this pass created or updated (the URLs it READ are in
+     *  page_sources — see recordKnowledgeUrlSources). */
+    pages: string[];
+    /**
+     * The credit ceiling the REQUESTER authorized, when a surface reserved this slot
+     * (`POST /api/cli/knowledge/bootstrap`, mode `live`, which requires `max_credits`).
+     *
+     * Absent/null means the automatic pass, which is authorized by signup consent and
+     * bounded by `KNOWLEDGE_BOOTSTRAP_MAX_CREDITS` instead. It rides the marker because
+     * the surface that takes the authorization is not the process that spends: a
+     * request that says "up to 100" and a worker that spends up to 300 is not a capped
+     * pass, it is an uncapped one with a friendly form. Always clamped to the platform
+     * cap on the way in — a marker can lower the ceiling, never raise it.
+     */
+    max_credits?: number | null;
+    /**
+     * Canonical company LinkedIn URL the requester supplied, when they supplied one.
+     * The same hint `/setup` stores at KNOWLEDGE_BOOTSTRAP_LINKEDIN_METADATA_KEY, but
+     * carried per-request so a one-off `--linkedin` never mutates the workspace's
+     * recorded answer.
+     */
+    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.
+ *
+ * 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
+ * workspace its bootstrap forever, or (far worse) make the reader see consent that
+ * nobody recorded.
+ */
+export declare const KNOWLEDGE_BOOTSTRAP_CONSENT_METADATA_KEY = "knowledge_bootstrap_consent";
+/** The recorded consent, exactly as stored under the key above. */
+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. */
+    source: string | null;
+    /** Clerk user who accepted, when the surface knows. Informational. */
+    granted_by_clerk_user_id: string | null;
+};
+/**
+ * Read consent out of an organization's control-DB metadata blob, FAIL-CLOSED.
+ *
+ * Absent, malformed, non-object, or carrying an unparseable `granted_at` all read as
+ * "not consented" — a workspace is never researched on the strength of a truthy-looking
+ * value. This is deliberately stricter than the kill switch beside it: the switch is
+ * fail-OPEN because an operator flips it, while consent is fail-CLOSED because its
+ * absence is the default state of every workspace that predates the feature, and
+ * spending a stranger's credits on a guess is the one outcome the exception cannot
+ * survive.
+ */
+export declare function readKnowledgeBootstrapConsent(metadata: unknown): KnowledgeBootstrapConsent | null;
+/**
+ * Control-DB `organizations.metadata` key carrying the company LinkedIn page the
+ * workspace typed at signup, when it typed one.
+ *
+ * It sits beside the consent key for the same reason: the setup surface writes it and
+ * the worker reads it, and two spellings of the key would silently drop a hint the
+ * customer took the trouble to give us. The stored value is the canonical form
+ * produced by `normalizeLinkedinCompanyUrl` (./dnc-identities.js) — normalize on the
+ * way in AND on the way out, never trust the raw string, and never let a personal
+ * `/in/` profile through: this is the COMPANY page, and researching a founder's
+ * personal profile as if it were the company is exactly the confidently-wrong write
+ * the bootstrap's domain gate exists to prevent.
+ *
+ * Optional by design. Its absence is normal and costs nothing: the research pass
+ * resolves the company from the domain and pays for a LinkedIn lookup only when it
+ * has a page worth looking up.
+ */
+export declare const KNOWLEDGE_BOOTSTRAP_LINKEDIN_METADATA_KEY = "company_linkedin_url";
+/**
+ * How long a `running` marker may sit before the workspace is reported as STUCK.
+ *
+ * Nothing retries it automatically. An unattended retry on a paid path is how a founder
+ * gets billed twice for one pass, so a crashed bootstrap stays visibly unfinished until
+ * a human re-arms it with `--force` (tenant-db's `requeueKnowledgeBootstrap`).
+ *
+ * This bound does two things, and the second is load-bearing: it decides when the
+ * worker starts SAYING a pass is stuck, AND it is the exact window after which
+ * `--force` may re-arm over a `running` marker. Inside the window the re-arm is
+ * refused, because the pass may still be spending; outside it the marker is presumed
+ * dead and the workspace is recoverable through the product.
+ */
+export declare const KNOWLEDGE_BOOTSTRAP_STUCK_AFTER_MS: number;
+/**
+ * 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`.
+ *
+ * It lives here rather than in the worker because it is a PROMISE the preview surface
+ * makes before anything runs (`POST /api/cli/knowledge/bootstrap` returns it inside
+ * `would_write`, with a deep-link). Two copies of a promised slug is how a dry run
+ * starts lying about which page it is going to write.
+ */
+export declare const KNOWLEDGE_BOOTSTRAP_RESEARCH_PAGE_SLUG = "company-research";
+/**
+ * The typed `company_profile` sections a bootstrap may write — and the exact set the
+ * "never clobber a profile a human already filled" gate inspects.
+ *
+ * `gtm_stack` and `custom` are structurally excluded: research of a company's public
+ * web presence says nothing about which tools it has connected here, and a workspace
+ * that filled only those has told us nothing about its company and must still be
+ * bootstrapped. Same reasoning as the slug above — the preview promises this list.
+ */
+export declare const KNOWLEDGE_BOOTSTRAP_PROFILE_SECTIONS: readonly ["company", "offering", "icp", "market"];
+/**
+ * Mirrors the four `CONTEXT_PROFILE_SECTIONS` members above. Declared locally because
+ * this module is a leaf (no tenant-db import); the union stays assignable to
+ * `ContextProfileSection`, so the worker keeps its real type with no cast.
+ */
+export type KnowledgeBootstrapProfileSection = "company" | "offering" | "icp" | "market";

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

@@ -0,0 +1,238 @@
+/**
+ * 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.
+ *
+ * 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
+ * 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.
+ *   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
+ *                    entry. Nothing about the spend is invisible.
+ *   4. KILL-SWITCHED — `OXYGEN_KNOWLEDGE_BOOTSTRAP_DISABLED` stops it fleet-wide at
+ *                    the worker with no deploy, matching the other OXYGEN_KNOWLEDGE_*
+ *                    switches.
+ *   5. REVERSIBLE  — the marker is a single jsonb key; clearing it (the `--force`
+ *                    path) re-arms the pass, and the pages/profile it wrote are
+ *                    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.
+ *
+ * CAP ARITHMETIC (prices re-read from packages/integrations/src/cogs-rates.ts —
+ * confirm them there rather than trusting this comment after a re-pricing):
+ *
+ *   serper.search           5 cr per call   (cogs-rates: serper.customerOxygen…search)
+ *   exa.contents            5 cr per CALL   (not per URL — this is the whole trick)
+ *   AI column, medium tier 75 cr per run    (pricing-sheet: AI_COLUMN_CREDITS.medium)
+ *
+ *   Happy path  = 1 serper.search (5) + 1 exa.contents over <= 5 URLs (5)
+ *                 + 1 medium synthesis pass (75)                        =  85 cr
+ *   Enrichment sub-cap  60 cr  — ~6x the 10 cr the happy path needs, so a waterfall
+ *                                retry or a second search fits, and a runaway
+ *                                per-URL fetch loop is stopped long before the
+ *                                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.
+ *
+ *   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
+ *   is priced per call and is built for fetching text at known URLs; that is why the
+ *   read budget is a page COUNT (`KNOWLEDGE_BOOTSTRAP_MAX_PAGES_READ`) inside one
+ *   call rather than a call count.
+ *
+ * This module is a leaf: constants and types only, no DB and no provider imports, so
+ * the worker, tenant-db, CLI, and API surfaces all bind to one contract.
+ */
+/** Hard ceiling on managed credits ONE workspace bootstrap may spend, all phases. */
+export const KNOWLEDGE_BOOTSTRAP_MAX_CREDITS = 300;
+/**
+ * Tighter sub-ceiling on the provider/enrichment half (search + page fetch), i.e.
+ * the external-money phase. Reaching it degrades the pass to `partial` — synthesize
+ * from what was read — rather than failing it.
+ */
+export const KNOWLEDGE_BOOTSTRAP_ENRICHMENT_MAX_CREDITS = 60;
+/**
+ * Reasoning tier the synthesis pass runs at. `medium` ("Oxygen Balanced") is the
+ * deliberate middle: `low` cannot hold a company profile's structure together, and
+ * `high` triples the cost of a pass nobody asked for.
+ */
+export const KNOWLEDGE_BOOTSTRAP_SYNTHESIS_TIER = "medium";
+/**
+ * Most URLs whose text the pass may read — inside ONE `exa.contents` call, which is
+ * priced per call. Raising this raises latency and prompt size, not provider spend;
+ * it is a quality/latency knob, and the credit ceilings above remain the money guard.
+ */
+export const KNOWLEDGE_BOOTSTRAP_MAX_PAGES_READ = 5;
+/** Fleet-wide kill switch, matching OXYGEN_KNOWLEDGE_RETRIEVAL/AUTO_SOURCES_DISABLED. */
+export const KNOWLEDGE_BOOTSTRAP_DISABLED_ENV_VAR = "OXYGEN_KNOWLEDGE_BOOTSTRAP_DISABLED";
+/**
+ * Is the automatic bootstrap disabled by operator env?
+ *
+ * Unset = ENABLED (this is a fail-OPEN switch, unlike the free-grant flag): the
+ * feature is meant to run for every eligible workspace, and the kill switch exists to
+ * stop it fleet-wide in an incident with no deploy. `"1"` or `"true"` disables it;
+ * any other value is treated as unset, exactly like the sibling knowledge switches.
+ */
+export function knowledgeBootstrapDisabled(env) {
+    const value = (env ?? process.env)[KNOWLEDGE_BOOTSTRAP_DISABLED_ENV_VAR];
+    return value === "1" || value === "true";
+}
+/**
+ * Lifecycle of the once-ever marker.
+ *
+ *   queued    — reserved: a surface claimed the slot but has not started work.
+ *   running   — claimed by a worker replica; the pass is in flight.
+ *   completed — profile + wiki page written.
+ *   partial   — some evidence gathered and written, but a cap, a provider failure, or
+ *               a thin domain stopped it short. Deliberately TERMINAL.
+ *   skipped   — never attempted for a policy reason (no domain, personal-email
+ *               signup, kill switch, zero spendable balance). `reason` says which.
+ *   failed    — attempted and errored. Also TERMINAL.
+ *
+ * Every one of these blocks a second claim: "once per workspace, ever" means the
+ * marker's mere EXISTENCE is the lock, not its value. A human re-arms the pass with
+ * `--force` (`POST /api/cli/knowledge/bootstrap`, which calls tenant-db's
+ * `requeueKnowledgeBootstrap`) — the one deliberate way to spend a second time. It
+ * overwrites every status above EXCEPT a `running` marker that is still LIVE, i.e.
+ * whose `started_at` is inside {@link KNOWLEDGE_BOOTSTRAP_STUCK_AFTER_MS}; a `running`
+ * marker older than that window is stale and IS re-armable, which is how a wedged pass
+ * is recovered without hand-written SQL.
+ */
+export const KNOWLEDGE_BOOTSTRAP_STATUSES = [
+    "queued",
+    "running",
+    "completed",
+    "partial",
+    "skipped",
+    "failed",
+];
+export function isKnowledgeBootstrapStatus(value) {
+    return (typeof value === "string" &&
+        KNOWLEDGE_BOOTSTRAP_STATUSES.includes(value));
+}
+// ---------------------------------------------------------------------------
+// Consent (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.
+ *
+ * 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
+ * workspace its bootstrap forever, or (far worse) make the reader see consent that
+ * nobody recorded.
+ */
+export const KNOWLEDGE_BOOTSTRAP_CONSENT_METADATA_KEY = "knowledge_bootstrap_consent";
+/**
+ * Read consent out of an organization's control-DB metadata blob, FAIL-CLOSED.
+ *
+ * Absent, malformed, non-object, or carrying an unparseable `granted_at` all read as
+ * "not consented" — a workspace is never researched on the strength of a truthy-looking
+ * value. This is deliberately stricter than the kill switch beside it: the switch is
+ * fail-OPEN because an operator flips it, while consent is fail-CLOSED because its
+ * absence is the default state of every workspace that predates the feature, and
+ * spending a stranger's credits on a guess is the one outcome the exception cannot
+ * survive.
+ */
+export function readKnowledgeBootstrapConsent(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+        return null;
+    const raw = metadata[KNOWLEDGE_BOOTSTRAP_CONSENT_METADATA_KEY];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const record = raw;
+    const grantedAt = record.granted_at;
+    if (typeof grantedAt !== "string" || grantedAt.length === 0)
+        return null;
+    if (!Number.isFinite(Date.parse(grantedAt)))
+        return null;
+    return {
+        granted_at: grantedAt,
+        source: typeof record.source === "string" && record.source.length > 0 ? record.source : null,
+        granted_by_clerk_user_id: typeof record.granted_by_clerk_user_id === "string" && record.granted_by_clerk_user_id.length > 0
+            ? record.granted_by_clerk_user_id
+            : null,
+    };
+}
+/**
+ * Control-DB `organizations.metadata` key carrying the company LinkedIn page the
+ * workspace typed at signup, when it typed one.
+ *
+ * It sits beside the consent key for the same reason: the setup surface writes it and
+ * the worker reads it, and two spellings of the key would silently drop a hint the
+ * customer took the trouble to give us. The stored value is the canonical form
+ * produced by `normalizeLinkedinCompanyUrl` (./dnc-identities.js) — normalize on the
+ * way in AND on the way out, never trust the raw string, and never let a personal
+ * `/in/` profile through: this is the COMPANY page, and researching a founder's
+ * personal profile as if it were the company is exactly the confidently-wrong write
+ * the bootstrap's domain gate exists to prevent.
+ *
+ * Optional by design. Its absence is normal and costs nothing: the research pass
+ * resolves the company from the domain and pays for a LinkedIn lookup only when it
+ * has a page worth looking up.
+ */
+export const KNOWLEDGE_BOOTSTRAP_LINKEDIN_METADATA_KEY = "company_linkedin_url";
+/**
+ * How long a `running` marker may sit before the workspace is reported as STUCK.
+ *
+ * Nothing retries it automatically. An unattended retry on a paid path is how a founder
+ * gets billed twice for one pass, so a crashed bootstrap stays visibly unfinished until
+ * a human re-arms it with `--force` (tenant-db's `requeueKnowledgeBootstrap`).
+ *
+ * This bound does two things, and the second is load-bearing: it decides when the
+ * worker starts SAYING a pass is stuck, AND it is the exact window after which
+ * `--force` may re-arm over a `running` marker. Inside the window the re-arm is
+ * refused, because the pass may still be spending; outside it the marker is presumed
+ * dead and the workspace is recoverable through the product.
+ */
+export const KNOWLEDGE_BOOTSTRAP_STUCK_AFTER_MS = 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Write targets (what a bootstrap actually changes)
+// ---------------------------------------------------------------------------
+/**
+ * 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`.
+ *
+ * It lives here rather than in the worker because it is a PROMISE the preview surface
+ * makes before anything runs (`POST /api/cli/knowledge/bootstrap` returns it inside
+ * `would_write`, with a deep-link). Two copies of a promised slug is how a dry run
+ * starts lying about which page it is going to write.
+ */
+export const KNOWLEDGE_BOOTSTRAP_RESEARCH_PAGE_SLUG = "company-research";
+/**
+ * The typed `company_profile` sections a bootstrap may write — and the exact set the
+ * "never clobber a profile a human already filled" gate inspects.
+ *
+ * `gtm_stack` and `custom` are structurally excluded: research of a company's public
+ * web presence says nothing about which tools it has connected here, and a workspace
+ * that filled only those has told us nothing about its company and must still be
+ * bootstrapped. Same reasoning as the slug above — the preview promises this list.
+ */
+export const KNOWLEDGE_BOOTSTRAP_PROFILE_SECTIONS = [
+    "company",
+    "offering",
+    "icp",
+    "market",
+];

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

@@ -37,4 +37,7 @@ export declare const KNOWLEDGE_GRAPH_MAX_NODES = 2000;
 export declare const KNOWLEDGE_GRAPH_DEFAULT_DEPTH = 1;
 export declare const KNOWLEDGE_GRAPH_MAX_DEPTH = 3;
 export declare const KNOWLEDGE_SYNC_MAX_PAGE_BATCH = 200;
+export declare const KNOWLEDGE_STUB_MARKER = "Stub \u2014 fill me.";
+export declare const KNOWLEDGE_BOOTSTRAP_COMMAND = "oxygen knowledge bootstrap";
+export declare const KNOWLEDGE_BOOTSTRAP_AVAILABLE = true;
 export declare const RESERVED_KNOWLEDGE_FRONTMATTER_KEYS: readonly ["oxygen_page", "id", "slug", "type", "title", "status", "tags", "canonical", "summary", "revision", "updated_at", "web_url"];

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

@@ -123,6 +123,25 @@ export const KNOWLEDGE_GRAPH_MAX_NODES = 2_000;
 export const KNOWLEDGE_GRAPH_DEFAULT_DEPTH = 1;
 export const KNOWLEDGE_GRAPH_MAX_DEPTH = 3;
 export const KNOWLEDGE_SYNC_MAX_PAGE_BATCH = 200;
+// The domain-grounded scaffold-fill command. KNOWLEDGE_BOOTSTRAP_AVAILABLE is the
+// single gate: while it is false, `oxygen knowledge lint` reports researchable stubs
+// as FACTS (which stubs are still empty, and whether the workspace has a domain a
+// research pass could use) but never names a command that would 404 — the repo's
+// "no placeholder commands" rule. The bootstrap slice flips this one constant and
+// every surface lights up unchanged. NOT dead code: do not delete it in a cleanup pass.
+// The literal line every seeded stub body opens with. It is load-bearing in TWO places,
+// which is why it lives here rather than being inlined:
+//   - retrieval (knowledge-retrieval.ts) refuses any page still carrying it, so
+//     scaffolding text can never reach a customer's cold email;
+//   - lint (knowledge-lint.ts) counts such a page as an unfilled stub.
+// Both used to key off `revision = 1` instead, which a status-only flip defeats:
+// `page upsert <slug> --status active` bumps the revision without touching the body, so
+// the page became simultaneously RETRIEVABLE and invisible to lint — the one state a
+// draft stub exists to prevent. The marker survives that flip; the revision does not.
+// Changing this string means changing every seeded body in knowledge-seed-content.ts.
+export const KNOWLEDGE_STUB_MARKER = "Stub — fill me.";
+export const KNOWLEDGE_BOOTSTRAP_COMMAND = "oxygen knowledge bootstrap";
+export const KNOWLEDGE_BOOTSTRAP_AVAILABLE = true;
 // Frontmatter keys the deterministic renderer owns; user `data` keys colliding
 // with these are skipped at render time (the stored jsonb keeps them).
 export const RESERVED_KNOWLEDGE_FRONTMATTER_KEYS = [

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

@@ -1,7 +1,9 @@
 import type { KnowledgePageType, KnowledgePageStatus } from "./knowledge-constants.js";
 /** Monotonic scaffold cursor stored in knowledge_state.scaffold_version. Bump to ship a
- *  new wave of starter pages (tag them with a higher minScaffoldVersion). */
-export declare const KNOWLEDGE_SCAFFOLD_VERSION = 1;
+ *  new wave of starter pages (tag them with a higher minScaffoldVersion).
+ *  v1: the 9-page core. v2: twelve GTM stubs (voice/brand/messaging/objections, three
+ *  motion playbooks + qualification, and the personas/customers/research/metrics hubs). */
+export declare const KNOWLEDGE_SCAFFOLD_VERSION = 2;
 export type KnowledgeScaffoldPage = {
     /** Immutable slug; must be valid kebab grammar and NOT a reserved slug. */
     slug: string;
@@ -14,11 +16,26 @@ export type KnowledgeScaffoldPage = {
     body: string;
     /** The first scaffold version that includes this page — seeded when current < this <= target. */
     minScaffoldVersion: number;
+    /** True when a research pass over the company's PUBLIC web presence could draft a real
+     *  first version of this page (what they sell, who they say they sell to, how they
+     *  sound, who bought). Internal-only pages (playbooks, qualification, metrics, research
+     *  notes) are never researchable — the public web does not know them. Consumed by
+     *  `oxygen knowledge lint`'s researchable check. */
+    researchable?: boolean;
 };
 /**
- * The 9-page starter pack. Two active nav pages first (start-here + the conventions schema
- * page), then the seven draft stub hubs (tag `seed`). `positioning` seeds as a NON-canonical
- * draft so it writes freely — pinning canonical positioning stays a separate human-approved
- * act. All at minScaffoldVersion 1 (the first wave).
+ * The 21-page starter pack. Two active nav pages first (start-here + the conventions
+ * schema page), then nineteen draft stub hubs (tag `seed`) — seven from wave 1 and
+ * twelve from wave 2. `positioning` seeds as a NON-canonical draft so it writes freely;
+ * pinning canonical positioning stays a separate human-approved act. Wave 2 adds ZERO
+ * active pages, per the binding rule at the top of this file.
  */
 export declare const KNOWLEDGE_SEED_PAGES: readonly KnowledgeScaffoldPage[];
+/**
+ * Seed slugs a domain-grounded research pass could genuinely draft from the company's
+ * PUBLIC web presence — what they sell, who they say they sell to, how they sound, who
+ * bought. Derived from the manifest's `researchable` flag (never a second hand-kept list),
+ * and consumed by `oxygen knowledge lint`'s researchable check, which reports the ones
+ * still sitting unfilled at revision 1 on a workspace that has a company domain.
+ */
+export declare const KNOWLEDGE_RESEARCHABLE_SEED_SLUGS: readonly string[];