thevoidforge 21.0.0

package/dist/wizard/lib/kongo/types.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Kongo Engine API types — matched to the real Kongo API surface at kongo.io/api/v1.
+ *
+ * These types represent the actual API request/response shapes, not abstract
+ * interfaces. Kongo is a first-party integration (ADR-036): the user owns both
+ * VoidForge and Kongo, so no adapter abstraction is needed.
+ *
+ * Base URL: https://kongo.io/api/v1
+ * Auth: Bearer token with ke_live_ prefix
+ */
+export type PageStatus = 'GENERATING' | 'READY' | 'ERROR';
+export type PageTemplate = 'PITCH' | 'landing-page' | 'company-overview' | 'product-launch' | 'event-page' | 'one-pager';
+export interface PageStyle {
+    readonly colors?: {
+        primary?: string;
+        secondary?: string;
+        accent?: string;
+    };
+    readonly fonts?: {
+        heading?: string;
+        body?: string;
+    };
+    readonly designSystem?: Record<string, unknown>;
+}
+export interface AccessGate {
+    readonly password?: string;
+    readonly emailCapture?: boolean;
+}
+export interface CreatePageRequest {
+    readonly companyName: string;
+    readonly content: string;
+    readonly brief?: Record<string, unknown>;
+    readonly template?: PageTemplate;
+    readonly style?: PageStyle;
+    readonly hosted?: boolean;
+    readonly callbackUrl?: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly accessGate?: AccessGate;
+    readonly seoTitle?: string;
+    readonly seoDescription?: string;
+}
+export interface CreatePageResponse {
+    readonly pageId: string;
+    readonly status: 'GENERATING';
+    readonly statusUrl: string;
+    readonly createdAt: string;
+}
+export interface PageGenerationStats {
+    readonly durationSec: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly costUsd: number;
+    readonly promptVersion?: string;
+}
+export interface PageProgressStep {
+    readonly step: string;
+    readonly status: string;
+    readonly timestamp?: string;
+}
+export interface PageErrorDetail {
+    readonly code: string;
+    readonly message: string;
+}
+export interface PageDetail {
+    readonly pageId: string;
+    readonly status: PageStatus;
+    readonly companyName: string;
+    readonly html?: string;
+    readonly hostedUrl?: string;
+    readonly progress?: PageProgressStep[];
+    readonly generation?: PageGenerationStats;
+    readonly error?: PageErrorDetail;
+    readonly createdAt: string;
+    readonly updatedAt?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface ListPagesOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly status?: PageStatus;
+    readonly sort?: 'createdAt' | 'updatedAt';
+    readonly order?: 'asc' | 'desc';
+}
+export interface PaginatedResponse<T> {
+    readonly items: T[];
+    readonly cursor?: string;
+    readonly hasMore: boolean;
+}
+export interface BatchPageConfig {
+    readonly companyName: string;
+    readonly content: string;
+    readonly brief?: Record<string, unknown>;
+    readonly template?: PageTemplate;
+    readonly style?: PageStyle;
+    readonly hosted?: boolean;
+    readonly callbackUrl?: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly accessGate?: AccessGate;
+    readonly seoTitle?: string;
+    readonly seoDescription?: string;
+}
+export interface BatchGenerateRequest {
+    readonly pages: BatchPageConfig[];
+}
+export interface BatchPageResult {
+    readonly pageId: string;
+    readonly status: 'GENERATING';
+    readonly statusUrl: string;
+    readonly createdAt: string;
+}
+export type RotationStrategy = 'weighted' | 'equal' | 'bandit';
+export interface SourceRule {
+    readonly source: string;
+    readonly variantId: string;
+}
+export interface CreateCampaignRequest {
+    readonly name: string;
+    readonly templateId: string;
+    readonly slug: string;
+    readonly rotationStrategy?: RotationStrategy;
+    readonly trackingEnabled?: boolean;
+    readonly accessGate?: AccessGate;
+    readonly metadata?: Record<string, unknown>;
+    readonly sourceRules?: SourceRule[];
+}
+export interface CampaignDetail {
+    readonly campaignId: string;
+    readonly name: string;
+    readonly templateId: string;
+    readonly slug: string;
+    readonly rotationStrategy: RotationStrategy;
+    readonly isPublished: boolean;
+    readonly trackingEnabled: boolean;
+    readonly accessGate?: {
+        passwordProtected: boolean;
+        emailCapture: boolean;
+    };
+    readonly metadata?: Record<string, unknown>;
+    readonly sourceRules?: SourceRule[];
+    readonly createdAt: string;
+    readonly updatedAt?: string;
+}
+export interface UpdateCampaignRequest {
+    readonly rotationStrategy?: RotationStrategy;
+    readonly trackingEnabled?: boolean;
+    readonly accessGate?: AccessGate;
+    readonly metadata?: Record<string, unknown>;
+    readonly sourceRules?: SourceRule[];
+}
+export interface PublishResult {
+    readonly campaignId: string;
+    readonly slug: string;
+    readonly domain: string;
+    readonly publishedAt: string;
+}
+export interface ListCampaignsOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly published?: boolean;
+    readonly search?: string;
+}
+export interface CreateVariantRequest {
+    readonly label: string;
+    readonly slotValues: Record<string, string>;
+    readonly weight?: number;
+    readonly source?: string;
+}
+export interface VariantDetail {
+    readonly variantId: string;
+    readonly label: string;
+    readonly order: number;
+    readonly slotCount: number;
+    readonly slotValues?: Record<string, string>;
+    readonly compiledHtml?: string;
+    readonly weight: number;
+    readonly source?: string;
+    readonly isActive: boolean;
+    readonly views: number;
+    readonly conversions: number;
+    readonly cvr: number;
+    readonly createdAt: string;
+    readonly updatedAt?: string;
+}
+export interface UpdateVariantRequest {
+    readonly label?: string;
+    readonly slotValues?: Record<string, string>;
+    readonly weight?: number;
+    readonly isActive?: boolean;
+}
+export interface GenerateVariantsRequest {
+    readonly count: number;
+    readonly vary: string[];
+    readonly baseValues?: Record<string, string>;
+    readonly context?: string;
+    readonly sources?: string[];
+}
+export interface GenerateVariantsResult {
+    readonly variants: Array<{
+        variantId: string;
+        label: string;
+        order: number;
+        slotCount: number;
+        source?: string;
+        createdAt: string;
+    }>;
+    readonly generation: {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+        durationMs: number;
+    };
+}
+export interface RegenerateVariantRequest {
+    readonly slots: string[];
+    readonly direction?: string;
+}
+export type AnalyticsPeriod = '7d' | '30d' | '90d' | 'all';
+export interface CampaignAnalytics {
+    readonly period: AnalyticsPeriod;
+    readonly summary: {
+        totalViews: number;
+        totalConversions: number;
+        cvr: number;
+    };
+    readonly byVariant: Array<{
+        variantId: string;
+        label: string;
+        order: number;
+        views: number;
+        conversions: number;
+        cvr: number;
+        weight: number;
+    }>;
+    readonly bySource: Array<{
+        source: string;
+        views: number;
+        conversions: number;
+        cvr: number;
+    }>;
+    readonly byDay: Array<{
+        date: string;
+        views: number;
+        conversions: number;
+    }>;
+}
+export type GrowthRecommendation = 'scale' | 'iterate' | 'kill' | 'wait';
+export interface ComputedGrowthSignal {
+    readonly campaignId: string;
+    readonly timestamp: string;
+    readonly winningVariantId: string | null;
+    readonly confidence: number;
+    readonly conversionRateDelta: number;
+    readonly recommendation: GrowthRecommendation;
+    readonly reasoning: string;
+    readonly sampleSize: {
+        control: number;
+        variant: number;
+    };
+}
+export type ConversionEventType = 'view' | 'click' | 'form_submit' | 'purchase';
+export interface ConversionEvent {
+    readonly campaignId: string;
+    readonly variantId: string;
+    readonly visitorId: string;
+    readonly type: ConversionEventType;
+    readonly eventName?: string;
+    readonly value?: number;
+    readonly utmSource?: string;
+    readonly utmMedium?: string;
+    readonly utmCampaign?: string;
+    readonly scrollDepth?: number;
+    readonly durationSec?: number;
+}
+export type WebhookEventType = 'page.completed' | 'page.failed';
+export interface WebhookPayload {
+    readonly event: WebhookEventType;
+    readonly pageId: string;
+    readonly data: {
+        companyName: string;
+        status: 'READY' | 'ERROR';
+        durationSec?: number;
+        costUsd?: number;
+        htmlLength?: number;
+        error?: string;
+    };
+}
+export interface KongoSuccessResponse<T> {
+    readonly success: true;
+    readonly data: T;
+}
+export interface KongoErrorResponse {
+    readonly success: false;
+    readonly error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+export type KongoResponse<T> = KongoSuccessResponse<T> | KongoErrorResponse;
+export type KongoErrorCode = 'UNAUTHORIZED' | 'TIER_RESTRICTED' | 'PERMISSION_DENIED' | 'RATE_LIMITED' | 'MONTHLY_LIMIT' | 'CONCURRENT_LIMIT' | 'SERVICE_BUSY' | 'VALIDATION_ERROR' | 'CONTENT_BLOCKED' | 'NOT_FOUND' | 'NOT_READY';
+export interface KongoClientConfig {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+    readonly timeoutMs?: number;
+    readonly rateLimitPerMinute?: number;
+}
+export interface PrdSeedContent {
+    readonly projectName: string;
+    readonly headline: string;
+    readonly subheadline: string;
+    readonly valueProps: string[];
+    readonly ctaText: string;
+    readonly ctaUrl: string;
+    readonly brandColors: {
+        primary: string;
+        secondary: string;
+        accent: string;
+    };
+    readonly logoUrl?: string;
+    readonly socialProof?: string[];
+    readonly campaignId?: string;
+    readonly platform?: string;
+}

package/dist/wizard/lib/kongo/types.js

@@ -0,0 +1,11 @@
+/**
+ * Kongo Engine API types — matched to the real Kongo API surface at kongo.io/api/v1.
+ *
+ * These types represent the actual API request/response shapes, not abstract
+ * interfaces. Kongo is a first-party integration (ADR-036): the user owns both
+ * VoidForge and Kongo, so no adapter abstraction is needed.
+ *
+ * Base URL: https://kongo.io/api/v1
+ * Auth: Bearer token with ke_live_ prefix
+ */
+export {};

package/dist/wizard/lib/kongo/variants.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Kongo Variants — Variant lifecycle and AI generation.
+ *
+ * Create, list, update, delete variants within campaigns.
+ * AI-powered bulk variant generation and slot regeneration.
+ *
+ * Real Kongo API endpoints:
+ * - POST /engine/campaigns/:campaignId/variants — create variant
+ * - GET /engine/campaigns/:campaignId/variants — list variants
+ * - GET /engine/campaigns/:campaignId/variants/:variantId — get variant
+ * - PATCH /engine/campaigns/:campaignId/variants/:variantId — update
+ * - DELETE /engine/campaigns/:campaignId/variants/:variantId — deactivate
+ * - POST /engine/campaigns/:campaignId/variants/generate — AI generate N variants
+ * - POST /engine/campaigns/:campaignId/variants/:variantId/regenerate — regen slots
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.2
+ */
+import { KongoClient } from './client.js';
+import type { CreateVariantRequest, VariantDetail, UpdateVariantRequest, GenerateVariantsRequest, GenerateVariantsResult, RegenerateVariantRequest } from './types.js';
+/**
+ * Create a single variant with explicit slot values.
+ */
+export declare function createVariant(client: KongoClient, campaignId: string, config: CreateVariantRequest): Promise<VariantDetail>;
+/**
+ * List all variants for a campaign.
+ * Returns view counts, conversions, CVR, weights, and direct URLs.
+ */
+export declare function listVariants(client: KongoClient, campaignId: string): Promise<VariantDetail[]>;
+/**
+ * Get a single variant with full details including slotValues and compiledHtml.
+ */
+export declare function getVariant(client: KongoClient, campaignId: string, variantId: string): Promise<VariantDetail>;
+/**
+ * Update a variant's label, slot values, weight, or active status.
+ * Slot value updates are merged (existing preserved, new override).
+ */
+export declare function updateVariant(client: KongoClient, campaignId: string, variantId: string, updates: UpdateVariantRequest): Promise<VariantDetail>;
+/**
+ * Deactivate a variant (soft delete).
+ */
+export declare function deleteVariant(client: KongoClient, campaignId: string, variantId: string): Promise<void>;
+/**
+ * AI-generate multiple variants in a single call.
+ * Uses Claude Sonnet to produce N variants varying specified slots.
+ * ~$0.01, ~3s for 5 variants.
+ */
+export declare function generateVariants(client: KongoClient, campaignId: string, config: GenerateVariantsRequest): Promise<GenerateVariantsResult>;
+/**
+ * Regenerate specific slots of an existing variant using AI.
+ * Merged values are recompiled into HTML.
+ */
+export declare function regenerateVariantSlots(client: KongoClient, campaignId: string, variantId: string, config: RegenerateVariantRequest): Promise<VariantDetail>;
+/**
+ * Set rotation strategy for a campaign.
+ * Convenience wrapper around updateCampaign — updates only rotationStrategy.
+ */
+export declare function setRotation(client: KongoClient, campaignId: string, strategy: 'weighted' | 'equal' | 'bandit'): Promise<void>;

package/dist/wizard/lib/kongo/variants.js

@@ -0,0 +1,88 @@
+/**
+ * Kongo Variants — Variant lifecycle and AI generation.
+ *
+ * Create, list, update, delete variants within campaigns.
+ * AI-powered bulk variant generation and slot regeneration.
+ *
+ * Real Kongo API endpoints:
+ * - POST /engine/campaigns/:campaignId/variants — create variant
+ * - GET /engine/campaigns/:campaignId/variants — list variants
+ * - GET /engine/campaigns/:campaignId/variants/:variantId — get variant
+ * - PATCH /engine/campaigns/:campaignId/variants/:variantId — update
+ * - DELETE /engine/campaigns/:campaignId/variants/:variantId — deactivate
+ * - POST /engine/campaigns/:campaignId/variants/generate — AI generate N variants
+ * - POST /engine/campaigns/:campaignId/variants/:variantId/regenerate — regen slots
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.2
+ */
+import { KongoApiError } from './client.js';
+// ── Variant Operations ───────────────────────────────────
+function campaignVariantsPath(campaignId) {
+    return `/engine/campaigns/${encodeURIComponent(campaignId)}/variants`;
+}
+function variantPath(campaignId, variantId) {
+    return `${campaignVariantsPath(campaignId)}/${encodeURIComponent(variantId)}`;
+}
+/**
+ * Create a single variant with explicit slot values.
+ */
+export async function createVariant(client, campaignId, config) {
+    return client.post(campaignVariantsPath(campaignId), config);
+}
+/**
+ * List all variants for a campaign.
+ * Returns view counts, conversions, CVR, weights, and direct URLs.
+ */
+export async function listVariants(client, campaignId) {
+    return client.get(campaignVariantsPath(campaignId));
+}
+/**
+ * Get a single variant with full details including slotValues and compiledHtml.
+ */
+export async function getVariant(client, campaignId, variantId) {
+    return client.get(variantPath(campaignId, variantId));
+}
+/**
+ * Update a variant's label, slot values, weight, or active status.
+ * Slot value updates are merged (existing preserved, new override).
+ */
+export async function updateVariant(client, campaignId, variantId, updates) {
+    return client.patch(variantPath(campaignId, variantId), updates);
+}
+/**
+ * Deactivate a variant (soft delete).
+ */
+export async function deleteVariant(client, campaignId, variantId) {
+    await client.delete(variantPath(campaignId, variantId));
+}
+/**
+ * AI-generate multiple variants in a single call.
+ * Uses Claude Sonnet to produce N variants varying specified slots.
+ * ~$0.01, ~3s for 5 variants.
+ */
+export async function generateVariants(client, campaignId, config) {
+    if (config.count < 1 || config.count > 20) {
+        throw new KongoApiError('VALIDATION_ERROR', `Variant count must be 1-20, got ${config.count}`, 400);
+    }
+    if (config.vary.length === 0) {
+        throw new KongoApiError('VALIDATION_ERROR', 'At least one slot name must be specified in vary', 400);
+    }
+    return client.post(`${campaignVariantsPath(campaignId)}/generate`, config);
+}
+/**
+ * Regenerate specific slots of an existing variant using AI.
+ * Merged values are recompiled into HTML.
+ */
+export async function regenerateVariantSlots(client, campaignId, variantId, config) {
+    if (config.slots.length === 0) {
+        throw new KongoApiError('VALIDATION_ERROR', 'At least one slot name must be specified', 400);
+    }
+    return client.post(`${variantPath(campaignId, variantId)}/regenerate`, config);
+}
+/**
+ * Set rotation strategy for a campaign.
+ * Convenience wrapper around updateCampaign — updates only rotationStrategy.
+ */
+export async function setRotation(client, campaignId, strategy) {
+    await client.put(`/engine/campaigns/${encodeURIComponent(campaignId)}`, { rotationStrategy: strategy });
+}

package/dist/wizard/lib/kongo/webhooks.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Kongo Webhooks — Signature verification and event routing.
+ *
+ * Kongo sends webhooks for page.completed and page.failed events
+ * via the callbackUrl specified on page creation.
+ *
+ * Signature format: X-Kongo-Signature: t=timestamp,v1=signature
+ * Verification: HMAC-SHA256 of "timestamp.body" with webhook signing secret.
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.3, §11
+ */
+import type { WebhookPayload, WebhookEventType } from './types.js';
+export interface WebhookVerificationResult {
+    readonly valid: boolean;
+    readonly reason?: string;
+}
+/**
+ * Verify a Kongo webhook signature.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ * Rejects replayed webhooks older than 5 minutes.
+ *
+ * @param rawBody - The raw request body as a string (must not be parsed)
+ * @param signature - The X-Kongo-Signature header value
+ * @param secret - The webhook signing secret from vault
+ */
+export declare function verifyWebhookSignature(rawBody: string, signature: string, secret: string): WebhookVerificationResult;
+/**
+ * Parse a verified webhook body into a typed payload.
+ */
+export declare function parseWebhookPayload(rawBody: string): WebhookPayload;
+export type WebhookHandler = (payload: WebhookPayload) => Promise<void>;
+export interface WebhookRouter {
+    readonly handlers: Map<WebhookEventType, WebhookHandler>;
+    on(event: WebhookEventType, handler: WebhookHandler): void;
+    handle(rawBody: string, signature: string, secret: string): Promise<void>;
+}
+/**
+ * Create a webhook router that verifies signatures and routes events to handlers.
+ */
+export declare function createWebhookRouter(): WebhookRouter;

package/dist/wizard/lib/kongo/webhooks.js

@@ -0,0 +1,112 @@
+/**
+ * Kongo Webhooks — Signature verification and event routing.
+ *
+ * Kongo sends webhooks for page.completed and page.failed events
+ * via the callbackUrl specified on page creation.
+ *
+ * Signature format: X-Kongo-Signature: t=timestamp,v1=signature
+ * Verification: HMAC-SHA256 of "timestamp.body" with webhook signing secret.
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.3, §11
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+// ── Signature Verification ───────────────────────────────
+// Maximum age for webhook timestamp (5 minutes)
+const MAX_WEBHOOK_AGE_MS = 5 * 60 * 1000;
+// Maximum webhook body size (1 MB — defense in depth, HTTP layer should also limit)
+const MAX_WEBHOOK_BODY_BYTES = 1 * 1024 * 1024;
+/**
+ * Verify a Kongo webhook signature.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ * Rejects replayed webhooks older than 5 minutes.
+ *
+ * @param rawBody - The raw request body as a string (must not be parsed)
+ * @param signature - The X-Kongo-Signature header value
+ * @param secret - The webhook signing secret from vault
+ */
+export function verifyWebhookSignature(rawBody, signature, secret) {
+    if (!signature || !rawBody || !secret) {
+        return { valid: false, reason: 'Missing signature, body, or secret' };
+    }
+    if (Buffer.byteLength(rawBody) > MAX_WEBHOOK_BODY_BYTES) {
+        return { valid: false, reason: 'Webhook body too large' };
+    }
+    // Parse signature: t=timestamp,v1=hash
+    const parts = signature.split(',');
+    if (parts.length !== 2) {
+        return { valid: false, reason: 'Invalid signature format' };
+    }
+    const tPart = parts[0];
+    const vPart = parts[1];
+    if (!tPart.startsWith('t=') || !vPart.startsWith('v1=')) {
+        return { valid: false, reason: 'Invalid signature format: missing t= or v1= prefix' };
+    }
+    const timestamp = tPart.slice(2);
+    const providedHash = vPart.slice(3);
+    // Check timestamp freshness
+    const timestampMs = parseInt(timestamp, 10) * 1000;
+    if (isNaN(timestampMs)) {
+        return { valid: false, reason: 'Invalid timestamp' };
+    }
+    const age = Date.now() - timestampMs;
+    if (age < -60_000) {
+        return { valid: false, reason: 'Webhook timestamp is in the future' };
+    }
+    if (age > MAX_WEBHOOK_AGE_MS) {
+        return { valid: false, reason: `Webhook too old: ${Math.round(age / 1000)}s (max ${MAX_WEBHOOK_AGE_MS / 1000}s)` };
+    }
+    // Compute expected signature
+    const payload = `${timestamp}.${rawBody}`;
+    const expectedHash = createHmac('sha256', secret)
+        .update(payload)
+        .digest('hex');
+    // Timing-safe comparison
+    const providedBuf = Buffer.from(providedHash, 'hex');
+    const expectedBuf = Buffer.from(expectedHash, 'hex');
+    if (providedBuf.length !== expectedBuf.length) {
+        return { valid: false, reason: 'Signature length mismatch' };
+    }
+    const valid = timingSafeEqual(providedBuf, expectedBuf);
+    return valid ? { valid: true } : { valid: false, reason: 'Signature mismatch' };
+}
+// ── Event Parsing ────────────────────────────────────────
+/**
+ * Parse a verified webhook body into a typed payload.
+ */
+export function parseWebhookPayload(rawBody) {
+    const parsed = JSON.parse(rawBody);
+    if (!parsed.event || !parsed.pageId || !parsed.data) {
+        throw new Error('Invalid webhook payload: missing event, pageId, or data');
+    }
+    const validEvents = ['page.completed', 'page.failed'];
+    if (!validEvents.includes(parsed.event)) {
+        throw new Error(`Unknown webhook event type: ${parsed.event}`);
+    }
+    return parsed;
+}
+/**
+ * Create a webhook router that verifies signatures and routes events to handlers.
+ */
+export function createWebhookRouter() {
+    const handlers = new Map();
+    return {
+        handlers,
+        on(event, handler) {
+            handlers.set(event, handler);
+        },
+        async handle(rawBody, signature, secret) {
+            const verification = verifyWebhookSignature(rawBody, signature, secret);
+            if (!verification.valid) {
+                throw new Error(`Webhook verification failed: ${verification.reason}`);
+            }
+            const payload = parseWebhookPayload(rawBody);
+            const handler = handlers.get(payload.event);
+            if (!handler) {
+                // Log but don't throw — unknown event types should be ignored gracefully
+                return;
+            }
+            await handler(payload);
+        },
+    };
+}

package/dist/wizard/lib/marker.d.ts

@@ -0,0 +1,28 @@
+/**
+ * .voidforge marker file — project identity and CLI detection.
+ *
+ * Every VoidForge project has a `.voidforge` JSON file at root.
+ * The CLI walks up from cwd to find it, determining the project root.
+ */
+export interface VoidForgeMarker {
+    id: string;
+    version: string;
+    created: string;
+    tier: 'full' | 'methodology';
+    extensions: string[];
+}
+export declare const MARKER_FILE = ".voidforge";
+export declare function readMarker(dir: string): Promise<VoidForgeMarker | null>;
+export declare function writeMarker(dir: string, marker: VoidForgeMarker): Promise<void>;
+export declare function createMarker(version: string, tier?: VoidForgeMarker['tier'], extensions?: string[]): VoidForgeMarker;
+/**
+ * Walk up from `startDir` to find the nearest `.voidforge` marker.
+ * Returns the directory containing the marker, or null if none found.
+ */
+export declare function findProjectRoot(startDir?: string): string | null;
+/**
+ * Like findProjectRoot but throws with a user-friendly message.
+ */
+export declare function requireProjectRoot(startDir?: string): string;
+export declare function getGlobalDir(): string;
+export declare function getVaultPath(): string;