crewly 1.6.4 → 1.6.5

package/dist/backend/backend/src/services/orchestrator/onboarding/recommend-team.js

@@ -0,0 +1,299 @@
+/**
+ * Recommend-Team Logic (Onboarding v3, v0)
+ *
+ * Pure function: turns a business-context payload (collected during the
+ * onboarding conversation) into a concrete team recommendation
+ * (template + agents + responsibilities).
+ *
+ * v0 strategy: 5 hardcoded heuristic mappings that cover the ~80% case
+ * Steve and Sam expect to see during the Mon 5/4 EOD demo, plus a
+ * generic 2-agent fallback for everything else. Real RAG over Mia's
+ * spec v3 + doc 69 + the live template registry lands Wed–Fri.
+ *
+ * Importantly, the function is **pure** (no FS, no API, no clock) —
+ * tests exercise the mapping logic directly without mocks.
+ *
+ * @module services/orchestrator/onboarding/recommend-team
+ */
+/**
+ * Build a recommendation given a key + template + agents + rationale.
+ * Internal helper to avoid repeating the source/reasoning shape.
+ */
+function build(key, templateId, agents, reasoning) {
+    return {
+        templateId,
+        agents,
+        reasoning,
+        source: `hardcoded:${key}`,
+    };
+}
+/**
+ * The 5 hardcoded mappings — ordered most-specific first.
+ *
+ * Each mapping is keyed off a small lowercase keyword set; the
+ * highest-scoring mapping wins. If no mapping scores ≥1, the generic
+ * fallback fires.
+ */
+const HARDCODED_MAPPINGS = [
+    // --- 1. E-commerce + content + customer support (Steve's anchor demo)
+    {
+        key: 'ecommerce-content-support',
+        keywords: [
+            'shopify',
+            'e-commerce',
+            'ecommerce',
+            'dtc',
+            'skincare',
+            'apparel',
+            'retail',
+            'storefront',
+            'support',
+            'content',
+        ],
+        build: (ctx) => build('ecommerce-content-support', 'dtc-viral-content-team', [
+            {
+                role: 'content-drafter',
+                responsibilities: 'Drafts weekly blog + social content tuned to your storefront and audience.',
+                skillIds: ['content-drafter', 'content-calendar'],
+            },
+            {
+                role: 'support-triage',
+                responsibilities: 'Triages incoming customer messages and prepares first-draft replies for your approval.',
+                skillIds: ['support-triage'],
+            },
+        ], `You named e-commerce + content + support. The content drafter handles your weekly publishing cadence; the support triage agent keeps inbound from piling up while leaving the send button to you. ${ctx.scale === 'solo' ? 'Sized 2-agent because solo founders should not babysit a big team.' : ''}`.trim()),
+    },
+    // --- 2. Solo content creator / social-first
+    {
+        key: 'solo-creator',
+        keywords: [
+            'creator',
+            'youtube',
+            'tiktok',
+            'instagram',
+            'newsletter',
+            'blog',
+            'podcast',
+            'video',
+            'social',
+        ],
+        build: () => build('solo-creator', 'ai-video-social-team', [
+            {
+                role: 'content-drafter',
+                responsibilities: 'Plans + drafts your content schedule across platforms.',
+                skillIds: ['content-drafter', 'content-calendar', 'content-repurposer'],
+            },
+            {
+                role: 'trend-monitor',
+                responsibilities: 'Watches the trends and topic signals in your niche so your drafts ride the wave.',
+                skillIds: ['trend-monitor'],
+            },
+        ], 'Your work centres on content production. Drafting + trend monitoring is the smallest team that meaningfully removes the daily-content treadmill.'),
+    },
+    // --- 3. Engineering / SaaS dev team
+    {
+        key: 'engineering',
+        keywords: [
+            'saas',
+            'software',
+            'engineering',
+            'dev',
+            'developer',
+            'startup',
+            'product',
+            'b2b',
+            'platform',
+            'mvp',
+        ],
+        build: (ctx) => build('engineering', ctx.scale === 'solo' ? 'pragmatic-mvp-dev-team' : 'web-dev-team', [
+            {
+                role: 'code-reviewer',
+                responsibilities: 'Reviews pull requests for style, obvious bugs, and missing tests.',
+                skillIds: ['code-reviewer'],
+            },
+            {
+                role: 'data-analyst',
+                responsibilities: 'Pulls product metrics into a daily report so you do not lose signal in the build cycle.',
+                skillIds: ['data-summarizer', 'scheduled-reporter'],
+            },
+        ], `For a ${ctx.scale === 'solo' ? 'solo MVP push' : 'small engineering team'}, the highest-leverage agents are code review + a data summariser that surfaces the metrics you forget to check.`),
+    },
+    // --- 4. Customer support / ops focus
+    {
+        key: 'support-ops',
+        keywords: [
+            'support',
+            'helpdesk',
+            'tickets',
+            'customer service',
+            'cs',
+            'ops',
+            'operations',
+            'feedback',
+        ],
+        build: () => build('support-ops', 'customer-ops-team', [
+            {
+                role: 'support-triage',
+                responsibilities: 'Triages inbound and drafts replies; you stay in the loop on send.',
+                skillIds: ['support-triage'],
+            },
+            {
+                role: 'data-analyst',
+                responsibilities: 'Summarises ticket trends so the same issue does not surprise you twice.',
+                skillIds: ['feedback-analyzer', 'data-summarizer'],
+            },
+        ], 'Your time-sinks are on the support side. A triage agent removes the inbox sprint; a feedback analyst catches the patterns under the noise.'),
+    },
+    // --- 5. Growth / marketing-heavy
+    {
+        key: 'growth-marketing',
+        keywords: [
+            'marketing',
+            'growth',
+            'seo',
+            'ads',
+            'paid',
+            'distribution',
+            'pipeline',
+            'lead gen',
+            'leadgen',
+            'agency',
+        ],
+        build: () => build('growth-marketing', 'growth-marketing-team', [
+            {
+                role: 'content-drafter',
+                responsibilities: 'Drafts the content side of your growth pipeline (blog / social / newsletter).',
+                skillIds: ['content-drafter', 'content-calendar'],
+            },
+            {
+                role: 'data-analyst',
+                responsibilities: 'Tracks growth metrics across channels and flags drops before they compound.',
+                skillIds: ['data-summarizer', 'scheduled-reporter'],
+            },
+            {
+                role: 'trend-monitor',
+                responsibilities: 'Surfaces topic + competitor signals so your distribution stays current.',
+                skillIds: ['trend-monitor', 'competitor-content-tracker'],
+            },
+        ], 'You named growth / distribution as the core. Three agents — drafting + analytics + trend-watching — cover the production / measurement / sensing loop.'),
+    },
+];
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Map a {@link BusinessContext} to a {@link TeamRecommendation}.
+ *
+ * Strategy (v0):
+ *   1. Score every hardcoded mapping by counting keyword hits across
+ *      `industry` + each task name.
+ *   2. Highest-scoring mapping wins (ties broken by declaration order).
+ *   3. If no mapping scores ≥1, fire the generic 2-agent fallback.
+ *
+ * The function never throws — invalid input degrades to the fallback so
+ * the conversation can keep moving even if discovery captured nothing
+ * useful.
+ *
+ * @param ctx - Business context collected during phases 1–3.
+ * @returns A team recommendation ready for phase 4.
+ *
+ * @example
+ * ```ts
+ * recommendTeam({
+ *   industry: 'small Shopify skincare shop',
+ *   scale: 'solo',
+ *   tasks: [
+ *     { name: 'weekly blog content', tier: 'yes-today' },
+ *     { name: 'customer support replies', tier: 'yes-today' },
+ *   ],
+ * });
+ * // → templateId: 'dtc-viral-content-team', 2 agents, …
+ * ```
+ */
+export function recommendTeam(ctx) {
+    const haystack = buildHaystack(ctx);
+    let bestScore = 0;
+    let best = null;
+    for (const mapping of HARDCODED_MAPPINGS) {
+        const score = scoreMapping(mapping, haystack);
+        if (score > bestScore) {
+            bestScore = score;
+            best = mapping;
+        }
+    }
+    if (best && bestScore > 0) {
+        return best.build(ctx);
+    }
+    return genericFallback(ctx);
+}
+/**
+ * Generic 2-agent fallback when no hardcoded mapping fires. Picks
+ * `startup-team` (the most general template) and a content + analyst
+ * pair, which has been the highest-utility default in our discovery
+ * data.
+ *
+ * @param ctx - Original business context (used only for rationale).
+ * @returns A safe, neutral recommendation.
+ */
+function genericFallback(ctx) {
+    const tasksLine = ctx.tasks.length
+        ? `you mentioned ${ctx.tasks.map((t) => t.name).join(' / ')}`
+        : 'we did not nail the time-sinks down yet';
+    return {
+        templateId: 'startup-team',
+        agents: [
+            {
+                role: 'content-drafter',
+                responsibilities: 'Drafts written content (blog / social / internal updates) on a schedule.',
+                skillIds: ['content-drafter'],
+            },
+            {
+                role: 'data-analyst',
+                responsibilities: 'Summarises whatever data feed you connect (sheets / API / CSV) into a daily report.',
+                skillIds: ['data-summarizer', 'scheduled-reporter'],
+            },
+        ],
+        reasoning: `I did not match a precise mapping for your shape — ${tasksLine} — so I am proposing a safe 2-agent default. We can adjust before I create anything.`,
+        source: 'fallback',
+    };
+}
+// =============================================================================
+// Internals
+// =============================================================================
+/**
+ * Build a single lowercase haystack string from the context's industry
+ * + task names. Keyword matches are checked against this string.
+ */
+function buildHaystack(ctx) {
+    const parts = [];
+    parts.push(ctx.industry ?? '');
+    for (const t of ctx.tasks) {
+        parts.push(t.name);
+    }
+    return parts.join(' ').toLowerCase();
+}
+/**
+ * Count how many of a mapping's keywords appear in the haystack.
+ */
+function scoreMapping(mapping, haystack) {
+    let score = 0;
+    for (const kw of mapping.keywords) {
+        if (haystack.includes(kw))
+            score += 1;
+    }
+    return score;
+}
+// =============================================================================
+// Exports for tests / wiring
+// =============================================================================
+/**
+ * Exposed for test introspection — the count is asserted against the
+ * spec ("5 hardcoded mappings cover 80% of users").
+ */
+export const HARDCODED_MAPPING_COUNT = HARDCODED_MAPPINGS.length;
+/**
+ * Exposed for test introspection — list of mapping keys, useful for
+ * asserting coverage without opening the array.
+ */
+export const HARDCODED_MAPPING_KEYS = HARDCODED_MAPPINGS.map((m) => m.key);
+//# sourceMappingURL=recommend-team.js.map

package/dist/backend/backend/src/services/orchestrator/onboarding/recommend-team.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend-team.js","sourceRoot":"","sources":["../../../../../../../backend/src/services/orchestrator/onboarding/recommend-team.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/orchestrator/onboarding-bootstrap.service.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Onboarding Bootstrap Service (Onboarding v3 — B1).
+ *
+ * Detects whether a freshly-launched Crewly OSS instance should enter
+ * onboarding mode. Two AND-ed signals are required:
+ *
+ * 1. **Project marker** — `Project.firstLaunchedAt` is unset (or no project
+ *    record exists yet). Set on first successful orc bootstrap and never
+ *    overwritten thereafter; defends the cold-start signal against the
+ *    edge case where chat-v2 is wiped accidentally on an existing install.
+ *
+ * 2. **Chat-v2 emptiness** — `ChatV2Service.countAllMessages() === 0`.
+ *    Captures "user has not spoken to Crewly yet" — Steve's exact phrasing.
+ *
+ * If EITHER signal says "user has been here before", onboarding does NOT
+ * trigger. This intentional belt-and-braces design follows Sam's substrate
+ * note 2026-05-03.
+ *
+ * Hook point: `crewly-agent-runtime.service.initializeInProcess()` calls
+ * `shouldEnterOnboardingMode()` before composing the system prompt and
+ * branches on the result (B3). After bootstrap success, the orc bootstrap
+ * also calls `markProjectAsLaunched()` to set the marker.
+ *
+ * @module services/orchestrator/onboarding-bootstrap.service
+ */
+import type { StorageService } from '../core/storage.service.js';
+/**
+ * Minimal contract for the chat-v2 emptiness probe.
+ *
+ * Decoupled from the concrete `ChatV2Service` so tests can inject a fake
+ * counter without bringing up sqlite. Production wiring resolves to
+ * `getChatV2Service().countAllMessages.bind(...)`.
+ */
+export interface ChatMessageCounter {
+    /** @returns Total count of persisted chat messages across all channels */
+    countAllMessages(): number;
+}
+/**
+ * Constructor dependencies for `OnboardingBootstrapService`.
+ */
+export interface OnboardingBootstrapDependencies {
+    /** Source of project records (provides `getProjects` + `saveProject`). */
+    storage: StorageService;
+    /** Source of chat-v2 emptiness signal. */
+    chat: ChatMessageCounter;
+}
+/**
+ * Cold-start detector for the orchestrator's onboarding mode.
+ *
+ * The two helpers are called from the orc bootstrap path:
+ * - `shouldEnterOnboardingMode()` — branch on this BEFORE composing the
+ *   system prompt; if true, load `ONBOARDING_MODE_SYSTEM_PROMPT` instead
+ *   of the role prompt.
+ * - `markProjectAsLaunched(projectId)` — call AFTER bootstrap succeeds,
+ *   regardless of mode, to write the per-project first-launch marker.
+ *
+ * @example
+ * ```typescript
+ * const detector = new OnboardingBootstrapService({ storage, chat });
+ * if (await detector.shouldEnterOnboardingMode()) {
+ *   stateService.setMode('onboarding');
+ * }
+ * // ... orc init succeeds ...
+ * if (currentProjectId) {
+ *   await detector.markProjectAsLaunched(currentProjectId);
+ * }
+ * ```
+ */
+export declare class OnboardingBootstrapService {
+    private readonly storage;
+    private readonly chat;
+    private readonly logger;
+    constructor(deps: OnboardingBootstrapDependencies);
+    /**
+     * Decide whether the orchestrator should enter onboarding mode.
+     *
+     * Both signals must agree on "this is a cold start":
+     *
+     * 1. The targeted project's `firstLaunchedAt` marker is unset. When
+     *    `projectId` is omitted, the check broadens to "no project at all
+     *    has the marker set" — appropriate for the orc bootstrap path,
+     *    which runs before any user has bound a project.
+     * 2. Chat-v2 has zero persisted messages.
+     *
+     * Errors in either probe are treated as "user has been here before"
+     * (returns false) — failing closed avoids false-triggering onboarding
+     * on a transient storage hiccup.
+     *
+     * @param projectId - Optional project to scope the marker check to.
+     *   Omit during orc bootstrap (no project context yet).
+     * @returns True iff this looks like a fresh OSS install
+     */
+    shouldEnterOnboardingMode(projectId?: string): Promise<boolean>;
+    /**
+     * Set `firstLaunchedAt` on the named project record.
+     *
+     * Idempotent: a no-op if the marker is already set (logged at debug),
+     * preserving the original launch timestamp. No-op (warn) if the project
+     * record cannot be located. Errors are caught and logged so the
+     * bootstrap path is not destabilised by a marker-write failure.
+     *
+     * @param projectId - Target project ID
+     */
+    markProjectAsLaunched(projectId: string): Promise<void>;
+}
+/**
+ * Wire (or replace) the process-wide `OnboardingBootstrapService`.
+ *
+ * Called once during server bootstrap after `StorageService` and
+ * `ChatV2Service` are constructed. Subsequent calls overwrite the binding
+ * (used by tests and graceful-restart paths).
+ *
+ * @param service - The configured service instance
+ */
+export declare function setOnboardingBootstrapService(service: OnboardingBootstrapService | null): void;
+/**
+ * Resolve the process-wide `OnboardingBootstrapService`.
+ *
+ * Returns null when not yet wired — callers must tolerate that case
+ * (the orc bootstrap path does, because cold-start detection is a "best
+ * effort, default to normal mode" probe).
+ *
+ * @returns The shared service instance, or null if not wired
+ */
+export declare function getOnboardingBootstrapService(): OnboardingBootstrapService | null;
+/** Reset the singleton — test-only helper. */
+export declare function resetOnboardingBootstrapServiceForTesting(): void;
+//# sourceMappingURL=onboarding-bootstrap.service.d.ts.map

package/dist/backend/backend/src/services/orchestrator/onboarding-bootstrap.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-bootstrap.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/orchestrator/onboarding-bootstrap.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGjE;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,gBAAgB,IAAI,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,0EAA0E;IAC1E,OAAO,EAAE,cAAc,CAAC;IACxB,0CAA0C;IAC1C,IAAI,EAAE,kBAAkB,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,IAAI,EAAE,+BAA+B;IAMjD;;;;;;;;;;;;;;;;;;OAkBG;IACG,yBAAyB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA8CrE;;;;;;;;;OASG;IACG,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA+B9D;AAQD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,0BAA0B,GAAG,IAAI,GAAG,IAAI,CAE9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,IAAI,0BAA0B,GAAG,IAAI,CAEjF;AAED,8CAA8C;AAC9C,wBAAgB,yCAAyC,IAAI,IAAI,CAEhE"}

package/dist/backend/backend/src/services/orchestrator/onboarding-bootstrap.service.js

@@ -0,0 +1,195 @@
+/**
+ * Onboarding Bootstrap Service (Onboarding v3 — B1).
+ *
+ * Detects whether a freshly-launched Crewly OSS instance should enter
+ * onboarding mode. Two AND-ed signals are required:
+ *
+ * 1. **Project marker** — `Project.firstLaunchedAt` is unset (or no project
+ *    record exists yet). Set on first successful orc bootstrap and never
+ *    overwritten thereafter; defends the cold-start signal against the
+ *    edge case where chat-v2 is wiped accidentally on an existing install.
+ *
+ * 2. **Chat-v2 emptiness** — `ChatV2Service.countAllMessages() === 0`.
+ *    Captures "user has not spoken to Crewly yet" — Steve's exact phrasing.
+ *
+ * If EITHER signal says "user has been here before", onboarding does NOT
+ * trigger. This intentional belt-and-braces design follows Sam's substrate
+ * note 2026-05-03.
+ *
+ * Hook point: `crewly-agent-runtime.service.initializeInProcess()` calls
+ * `shouldEnterOnboardingMode()` before composing the system prompt and
+ * branches on the result (B3). After bootstrap success, the orc bootstrap
+ * also calls `markProjectAsLaunched()` to set the marker.
+ *
+ * @module services/orchestrator/onboarding-bootstrap.service
+ */
+import { LoggerService } from '../core/logger.service.js';
+/**
+ * Cold-start detector for the orchestrator's onboarding mode.
+ *
+ * The two helpers are called from the orc bootstrap path:
+ * - `shouldEnterOnboardingMode()` — branch on this BEFORE composing the
+ *   system prompt; if true, load `ONBOARDING_MODE_SYSTEM_PROMPT` instead
+ *   of the role prompt.
+ * - `markProjectAsLaunched(projectId)` — call AFTER bootstrap succeeds,
+ *   regardless of mode, to write the per-project first-launch marker.
+ *
+ * @example
+ * ```typescript
+ * const detector = new OnboardingBootstrapService({ storage, chat });
+ * if (await detector.shouldEnterOnboardingMode()) {
+ *   stateService.setMode('onboarding');
+ * }
+ * // ... orc init succeeds ...
+ * if (currentProjectId) {
+ *   await detector.markProjectAsLaunched(currentProjectId);
+ * }
+ * ```
+ */
+export class OnboardingBootstrapService {
+    storage;
+    chat;
+    logger;
+    constructor(deps) {
+        this.storage = deps.storage;
+        this.chat = deps.chat;
+        this.logger = LoggerService.getInstance().createComponentLogger('OnboardingBootstrap');
+    }
+    /**
+     * Decide whether the orchestrator should enter onboarding mode.
+     *
+     * Both signals must agree on "this is a cold start":
+     *
+     * 1. The targeted project's `firstLaunchedAt` marker is unset. When
+     *    `projectId` is omitted, the check broadens to "no project at all
+     *    has the marker set" — appropriate for the orc bootstrap path,
+     *    which runs before any user has bound a project.
+     * 2. Chat-v2 has zero persisted messages.
+     *
+     * Errors in either probe are treated as "user has been here before"
+     * (returns false) — failing closed avoids false-triggering onboarding
+     * on a transient storage hiccup.
+     *
+     * @param projectId - Optional project to scope the marker check to.
+     *   Omit during orc bootstrap (no project context yet).
+     * @returns True iff this looks like a fresh OSS install
+     */
+    async shouldEnterOnboardingMode(projectId) {
+        // --- Signal 1: project firstLaunchedAt marker ---
+        let projectMarkerIsCold;
+        try {
+            const projects = await this.storage.getProjects();
+            if (projectId !== undefined) {
+                const target = projects.find((p) => p.id === projectId);
+                // Missing project (deleted under us) and absent marker both count
+                // as "cold". Any value (string, even empty string) means the user
+                // has been here before — only `undefined` clears the gate.
+                projectMarkerIsCold = !target || target.firstLaunchedAt === undefined;
+            }
+            else {
+                projectMarkerIsCold = !projects.some((p) => p.firstLaunchedAt !== undefined);
+            }
+        }
+        catch (err) {
+            this.logger.warn('Failed to read project marker; failing closed (no onboarding)', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return false;
+        }
+        if (!projectMarkerIsCold) {
+            this.logger.debug('Project firstLaunchedAt is set — skipping onboarding', { projectId });
+            return false;
+        }
+        // --- Signal 2: chat-v2 emptiness ---
+        let chatIsEmpty;
+        try {
+            chatIsEmpty = this.chat.countAllMessages() === 0;
+        }
+        catch (err) {
+            this.logger.warn('Failed to read chat-v2 count; failing closed (no onboarding)', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return false;
+        }
+        if (!chatIsEmpty) {
+            this.logger.debug('Chat-v2 has prior messages — skipping onboarding');
+            return false;
+        }
+        this.logger.info('Cold-start detected — entering onboarding mode', { projectId });
+        return true;
+    }
+    /**
+     * Set `firstLaunchedAt` on the named project record.
+     *
+     * Idempotent: a no-op if the marker is already set (logged at debug),
+     * preserving the original launch timestamp. No-op (warn) if the project
+     * record cannot be located. Errors are caught and logged so the
+     * bootstrap path is not destabilised by a marker-write failure.
+     *
+     * @param projectId - Target project ID
+     */
+    async markProjectAsLaunched(projectId) {
+        try {
+            const projects = await this.storage.getProjects();
+            const target = projects.find((p) => p.id === projectId);
+            if (!target) {
+                this.logger.warn('markProjectAsLaunched: project not found', { projectId });
+                return;
+            }
+            if (target.firstLaunchedAt) {
+                this.logger.debug('markProjectAsLaunched: marker already set, no-op', {
+                    projectId,
+                    existingValue: target.firstLaunchedAt,
+                });
+                return;
+            }
+            const now = new Date().toISOString();
+            const updated = {
+                ...target,
+                firstLaunchedAt: now,
+                updatedAt: now,
+            };
+            await this.storage.saveProject(updated);
+            this.logger.info('Project marked as launched', { projectId, firstLaunchedAt: now });
+        }
+        catch (err) {
+            this.logger.error('markProjectAsLaunched: storage write failed', {
+                projectId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Singleton accessor — wired by the bootstrap layer once dependencies exist
+// ---------------------------------------------------------------------------
+let onboardingBootstrapInstance = null;
+/**
+ * Wire (or replace) the process-wide `OnboardingBootstrapService`.
+ *
+ * Called once during server bootstrap after `StorageService` and
+ * `ChatV2Service` are constructed. Subsequent calls overwrite the binding
+ * (used by tests and graceful-restart paths).
+ *
+ * @param service - The configured service instance
+ */
+export function setOnboardingBootstrapService(service) {
+    onboardingBootstrapInstance = service;
+}
+/**
+ * Resolve the process-wide `OnboardingBootstrapService`.
+ *
+ * Returns null when not yet wired — callers must tolerate that case
+ * (the orc bootstrap path does, because cold-start detection is a "best
+ * effort, default to normal mode" probe).
+ *
+ * @returns The shared service instance, or null if not wired
+ */
+export function getOnboardingBootstrapService() {
+    return onboardingBootstrapInstance;
+}
+/** Reset the singleton — test-only helper. */
+export function resetOnboardingBootstrapServiceForTesting() {
+    onboardingBootstrapInstance = null;
+}
+//# sourceMappingURL=onboarding-bootstrap.service.js.map

package/dist/backend/backend/src/services/orchestrator/onboarding-bootstrap.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-bootstrap.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/orchestrator/onboarding-bootstrap.service.ts"],"names":[],"mappings":"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"}