@ever-works/contracts 1.0.0

package/dist/api/index.d.cts

@@ -0,0 +1,2171 @@
+import { ItemData, ItemHealth } from '../item/index.cjs';
+import { M as MergePolicyOverride, O as OrganizationConnectionPolicy, F as FeedNarrationDto } from '../feed.types-BWk3CHqj.cjs';
+
+/**
+ * Method used for item generation
+ */
+declare enum GenerationMethod {
+    CREATE_UPDATE = "create-update",
+    RECREATE = "recreate",
+    IMPORT = "import"
+}
+/**
+ * Method used for website repository creation
+ */
+declare enum WebsiteRepositoryCreationMethod {
+    DUPLICATE = "duplicate",
+    CREATE_USING_TEMPLATE = "create-using-template"
+}
+
+/**
+ * Provider selection for each capability category
+ */
+interface ProvidersDto {
+    /** Search provider plugin ID */
+    search?: string;
+    /** Screenshot provider plugin ID */
+    screenshot?: string;
+    /** AI provider plugin ID */
+    ai?: string;
+    /** Content extractor provider plugin ID */
+    contentExtractor?: string;
+    /** Pipeline provider plugin ID */
+    pipeline?: string;
+}
+
+/**
+ * Minimal core DTO for creating/triggering item generation.
+ * All pipeline-specific configuration is passed via pluginConfig.
+ */
+interface CreateItemsGeneratorDto {
+    /** Work name */
+    name: string;
+    /** Generation prompt */
+    prompt: string;
+    /** Optional AI model override */
+    model?: string;
+    /** Method for generation (create-update or recreate) */
+    generation_method?: GenerationMethod;
+    /** Whether to update with pull request */
+    update_with_pull_request?: boolean;
+    /** Website repository creation method */
+    website_repository_creation_method?: WebsiteRepositoryCreationMethod;
+    /** Provider selection */
+    providers?: ProvidersDto;
+    /** Plugin-specific configuration - structure defined by selected pipeline plugin */
+    pluginConfig?: Record<string, unknown>;
+}
+/**
+ * DTO for updating items generator configuration
+ */
+interface UpdateItemsGeneratorDto {
+    /** Optional AI model override */
+    model?: string;
+    /** Method for generation (create-update or recreate) */
+    generation_method?: GenerationMethod;
+    /** Whether to update with pull request */
+    update_with_pull_request?: boolean;
+    /** Provider overrides (pipeline, ai, search, etc.) */
+    providers?: ProvidersDto;
+}
+
+/**
+ * DTO for submitting a new item to a work
+ *
+ * Note: Either `category` (single) or `categories` (array) must be provided.
+ * The backend validates this with conditional validation.
+ */
+interface SubmitItemDto {
+    /** Item name */
+    name: string;
+    /** Item description */
+    description: string;
+    /** Source URL for the item */
+    source_url: string;
+    /** Primary category (required if categories is not provided) */
+    category?: string;
+    /** Additional categories (required if category is not provided) */
+    categories?: string[];
+    /** Tags for the item */
+    tags?: string[];
+    /** Whether item is featured */
+    featured?: boolean;
+    /** Display order */
+    order?: number;
+    /** Whether to pay and publish immediately */
+    pay_and_publish_now?: boolean;
+    /** URL-friendly slug */
+    slug?: string;
+    /** Brand name */
+    brand?: string;
+    /** Brand logo URL */
+    brand_logo_url?: string;
+    /** Item images */
+    images?: string[];
+    /** Whether to create a pull request */
+    create_pull_request?: boolean;
+    /** Long-form markdown body. Written to `data/<slug>/<slug>.md` and mirrored
+     *  on the YAML `markdown` field. When omitted, the generator falls back
+     *  to a stub built from name + description + source_url. */
+    markdown?: string;
+}
+
+/**
+ * DTO for removing an item from a work
+ */
+interface RemoveItemDto {
+    /** Slug of the item to remove */
+    item_slug: string;
+    /** Reason for removal */
+    reason?: string;
+    /** Whether to create a pull request */
+    create_pull_request?: boolean;
+}
+
+/**
+ * DTO for updating item metadata in a work
+ */
+interface UpdateItemDto {
+    /** Slug of the item to update */
+    item_slug: string;
+    /** Source URL */
+    source_url?: string;
+    /** Whether item is featured */
+    featured?: boolean;
+    /** Display order */
+    order?: number;
+    /** Whether to create a pull request */
+    create_pull_request?: boolean;
+    /** Long-form markdown body. When provided, replaces the existing
+     *  `data/<slug>/<slug>.md` file and mirrors onto the YAML `markdown` field. */
+    markdown?: string;
+}
+
+/**
+ * DTO for manually checking a single item's source URL health.
+ */
+interface CheckItemHealthDto {
+    /** Slug of the item to check */
+    item_slug: string;
+}
+/**
+ * Response returned after checking a single item's source URL health.
+ */
+interface CheckItemHealthResponseDto {
+    status: 'success' | 'error';
+    item_slug: string;
+    item_name: string;
+    message: string;
+    item?: ItemData;
+    health?: ItemHealth;
+}
+
+/**
+ * DTO for extracting item details from a URL
+ */
+interface ExtractItemDetailsDto {
+    /** Source URL to extract details from */
+    source_url: string;
+    /** Optional work context for provider resolution and usage attribution */
+    workId?: string;
+    /** Existing categories in the work for matching */
+    existing_categories?: string[];
+}
+
+/**
+ * Cadence options for work scheduled updates
+ */
+declare enum WorkScheduleCadence {
+    HOURLY = "hourly",
+    EVERY_3_HOURS = "every_3_hours",
+    EVERY_8_HOURS = "every_8_hours",
+    EVERY_12_HOURS = "every_12_hours",
+    DAILY = "daily",
+    WEEKLY = "weekly",
+    MONTHLY = "monthly"
+}
+/**
+ * Status options for work schedule
+ */
+declare enum WorkScheduleStatus {
+    DISABLED = "disabled",
+    ACTIVE = "active",
+    PAUSED = "paused",
+    CANCELED = "canceled"
+}
+/**
+ * Billing mode options for scheduled updates
+ */
+declare enum WorkScheduleBillingMode {
+    SUBSCRIPTION = "subscription",
+    USAGE = "usage"
+}
+
+/**
+ * Status types for work generation
+ */
+declare enum GenerateStatusType {
+    GENERATING = "generating",
+    GENERATED = "generated",
+    ERROR = "error",
+    CANCELLED = "cancelled"
+}
+
+/**
+ * Allowed cadence configuration for a work
+ */
+interface WorkScheduleAllowedCadence {
+    /** The cadence option */
+    cadence: WorkScheduleCadence;
+    /** Reason if not allowed */
+    reason?: string;
+    /** Whether this cadence uses pay-per-use billing */
+    payPerUse?: boolean;
+    /** Whether this cadence is allowed */
+    allowed: boolean;
+}
+/**
+ * Work schedule configuration and status
+ */
+interface WorkScheduleDto {
+    /** Current schedule status */
+    status: WorkScheduleStatus;
+    /** Whether the scheduled updates feature is currently available */
+    featureEnabled: boolean;
+    /** Whether this work is currently eligible to enable scheduled updates */
+    canEnable: boolean;
+    /** Machine-readable reason the schedule cannot currently be enabled */
+    blockingCode?: 'SCHEDULED_UPDATES_DISABLED' | 'INITIAL_WORK_SETUP_REQUIRED' | 'SOURCE_SYNC_UNSUPPORTED' | 'CONFIG_UNAVAILABLE';
+    /** Human-readable reason the schedule cannot currently be enabled */
+    blockingReason?: string;
+    /** Selected cadence (null if disabled) */
+    cadence: WorkScheduleCadence | null;
+    /** Billing mode */
+    billingMode: WorkScheduleBillingMode;
+    /** Next scheduled run time (ISO string) */
+    nextRunAt: string | null;
+    /** Last run time (ISO string) */
+    lastRunAt: string | null;
+    /** Status of last run */
+    lastRunStatus: GenerateStatusType | null;
+    /** Number of consecutive failures */
+    failureCount: number;
+    /** Max failures before auto-pause */
+    maxFailureBeforePause: number;
+    /** Whether to always create pull request */
+    alwaysCreatePullRequest: boolean;
+    /** Available cadence options */
+    allowedCadences: WorkScheduleAllowedCadence[];
+    /** User's plan code */
+    planCode?: string;
+    /** Whether subscriptions are enabled */
+    subscriptionsEnabled: boolean;
+    /** Provider overrides for scheduled runs (pipeline, ai, search, etc.) */
+    providerOverrides?: ProvidersDto | null;
+}
+/**
+ * Payload for updating work schedule
+ */
+interface UpdateWorkSchedulePayload {
+    /** Enable or disable schedule */
+    enable?: boolean;
+    /** Trigger an immediate run after saving the active schedule */
+    runImmediately?: boolean;
+    /** Schedule cadence */
+    cadence?: WorkScheduleCadence;
+    /** Billing mode */
+    billingMode?: WorkScheduleBillingMode;
+    /** Max failures before auto-pause */
+    maxFailureBeforePause?: number;
+    /** Always create pull request */
+    alwaysCreatePullRequest?: boolean;
+    /** Provider overrides for scheduled runs (pipeline, ai, search, etc.) */
+    providerOverrides?: ProvidersDto | null;
+}
+
+type WorkCurrentState = 'running' | 'paused' | 'idle';
+type WorkDeploymentReadiness = 'ready' | 'pending' | 'unknown' | 'not_deployed';
+type WorkDeploymentHealthSource = 'deployment_projection' | 'none';
+interface WorkLastGenerationRunDto {
+    status: GenerateStatusType;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+interface WorkLastDeploymentRunDto {
+    status: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+interface WorkLastRunDto {
+    generation: WorkLastGenerationRunDto | null;
+    deployment: WorkLastDeploymentRunDto | null;
+}
+interface WorkCurrentDeploymentHealthDto {
+    readiness: WorkDeploymentReadiness;
+    source: WorkDeploymentHealthSource;
+    /** Null for legacy projections because they pre-date persisted probe timestamps. */
+    observedAt: string | null;
+}
+interface WorkCurrentHealthDto {
+    state: WorkCurrentState;
+    deployment: WorkCurrentDeploymentHealthDto;
+}
+interface WorkStatusProjectionDto {
+    lastRun: WorkLastRunDto;
+    currentHealth: WorkCurrentHealthDto;
+}
+
+/**
+ * Metrics from a generation run
+ */
+interface GenerationMetrics {
+    /** Number of URLs scanned */
+    urls_scanned?: number;
+    /** Number of pages processed */
+    pages_processed?: number;
+    /** Items extracted in current run */
+    items_extracted_current_run?: number;
+    /** New items added to store */
+    new_items_added_to_store?: number;
+    /** Total items in store */
+    total_items_in_store?: number;
+    /** Total tokens used */
+    total_tokens_used?: number;
+    /** Total cost */
+    total_cost?: number;
+}
+declare enum WorkHistoryActivityType {
+    GENERATION = "generation",
+    ITEM_ADDED = "item_added",
+    ITEM_UPDATED = "item_updated",
+    ITEM_REMOVED = "item_removed",
+    COMPARISON_ADDED = "comparison_added",
+    COMPARISON_REMOVED = "comparison_removed",
+    CATEGORY_CHANGE = "category_change",
+    TAG_CHANGE = "tag_change",
+    COLLECTION_CHANGE = "collection_change",
+    COMMUNITY_PR_MERGED = "community_pr_merged"
+}
+type WorkHistoryChangeEntityType = 'item' | 'comparison' | 'category' | 'tag' | 'collection';
+type WorkHistoryChangeAction = 'added' | 'updated' | 'removed';
+interface WorkHistoryChangeEntry {
+    entityType: WorkHistoryChangeEntityType;
+    action: WorkHistoryChangeAction;
+    name: string;
+    slug?: string;
+    fieldsChanged?: string[];
+}
+type GenerationLogLevel = 'info' | 'warn' | 'error' | 'debug';
+type GenerationLogSource = 'pipeline' | 'orchestrator' | 'claude-code' | 'system';
+interface GenerationStepLog {
+    timestamp: string;
+    level: GenerationLogLevel;
+    source: GenerationLogSource;
+    stepIndex?: number | null;
+    stepName?: string | null;
+    event: 'step_started' | 'step_completed' | 'step_failed' | 'step_skipped' | 'message';
+    message: string;
+    durationMs?: number | null;
+}
+interface WorkChangelog {
+    summary?: string | null;
+    addedCount: number;
+    updatedCount: number;
+    removedCount: number;
+    entries: WorkHistoryChangeEntry[];
+}
+/**
+ * Entry in work generation history
+ */
+interface WorkGenerationHistoryEntry {
+    /** History entry ID */
+    id: string;
+    /** Generation status */
+    status: GenerateStatusType;
+    /** Generation method used */
+    generationMethod?: GenerationMethod | null;
+    /** When generation started (ISO string) */
+    startedAt?: string | null;
+    /** When generation finished (ISO string) */
+    finishedAt?: string | null;
+    /** Duration in seconds */
+    durationInSeconds?: number | null;
+    /** Number of new items */
+    newItemsCount: number;
+    /** Number of updated items */
+    updatedItemsCount: number;
+    /** Total items count */
+    totalItemsCount: number;
+    /** Generation metrics */
+    metrics?: GenerationMetrics | null;
+    /** Error message if failed */
+    errorMessage?: string | null;
+    /** Generation parameters used */
+    parameters?: CreateItemsGeneratorDto | null;
+    /** Created timestamp (ISO string) */
+    createdAt: string;
+    /** Updated timestamp (ISO string) */
+    updatedAt: string;
+    /** Trigger.dev run ID */
+    triggerRunId?: string;
+    /** History activity type */
+    activityType: WorkHistoryActivityType;
+    /** Structured changelog details */
+    changelog?: WorkChangelog | null;
+    /** Step-level generation logs */
+    logs?: GenerationStepLog[] | null;
+    /** Warnings captured during generation */
+    warnings?: string[] | null;
+    /** What triggered this run */
+    triggeredBy?: 'user' | 'schedule' | 'api' | null;
+}
+/**
+ * Response for work generation history
+ */
+interface WorkGenerationHistoryResponse {
+    /** History entries */
+    history: WorkGenerationHistoryEntry[];
+    /** Total count */
+    total: number;
+    /** Pagination limit */
+    limit: number;
+    /** Pagination offset */
+    offset: number;
+}
+
+interface UpdateSourceValidationPayload {
+    enabled: boolean;
+    cadence?: WorkScheduleCadence;
+}
+interface SourceValidationSettingsDto {
+    enabled: boolean;
+    cadence: WorkScheduleCadence | null;
+    nextRunAt: string | null;
+    lastRunAt: string | null;
+    allowedCadences: WorkScheduleAllowedCadence[];
+}
+
+declare const IMPORT_SOURCE_TYPES: readonly ["data_repo", "awesome_readme", "link_existing", "works_config"];
+type ImportSourceType = (typeof IMPORT_SOURCE_TYPES)[number];
+declare const AWESOME_README_IMPORT_MODES: readonly ["clone", "reuse_source"];
+type AwesomeReadmeImportMode = (typeof AWESOME_README_IMPORT_MODES)[number];
+type RepositoryRole = 'data' | 'work' | 'website';
+interface RepositoryTarget {
+    owner?: string;
+    repo: string;
+}
+interface RelatedRepositories {
+    data?: RepositoryTarget;
+    work?: RepositoryTarget;
+    website?: RepositoryTarget;
+}
+interface WorksConfigSnapshot {
+    name?: string;
+    initialPrompt?: string;
+    model?: string;
+    websiteRepo?: string;
+    scheduleCadence?: WorkScheduleCadence | null;
+    providers?: ProvidersDto;
+}
+interface SourceRepository<TImportedAt = string> {
+    url: string;
+    owner: string;
+    repo: string;
+    type: ImportSourceType;
+    importedAt: TImportedAt;
+    relatedRepositories?: RelatedRepositories;
+    worksConfig?: WorksConfigSnapshot;
+}
+interface RepoVisibility {
+    data: boolean;
+    website: boolean;
+    work: boolean;
+}
+interface ImportEnrichmentConfig {
+    expansionFactor?: number;
+}
+interface AnalyzeRepositoryResponseDto {
+    sourceUrl: string;
+    owner: string;
+    repo: string;
+    detectedType: ImportSourceType | null;
+    isPublic: boolean;
+    requiresAuth: boolean;
+    structure?: {
+        hasDataFolder: boolean;
+        hasConfig: boolean;
+        hasReadme: boolean;
+        hasWorksConfig?: boolean;
+        isMultiFile?: boolean;
+        itemCount?: number;
+        categoryCount?: number;
+    };
+    worksConfig?: WorksConfigSnapshot;
+    relatedDataRepo?: {
+        name: string;
+        owner: string;
+    };
+    baseSlug?: string;
+    slugConflict?: {
+        hasConflict: boolean;
+        conflictingRepos: string[];
+        suggestedSlug: string;
+    };
+    hasDataRepoWriteAccess?: boolean;
+    error?: string;
+}
+interface ImportWorkDto {
+    sourceUrl: string;
+    sourceType: ImportSourceType;
+    awesomeReadmeImportMode?: AwesomeReadmeImportMode;
+    name: string;
+    owner?: string;
+    organization?: boolean;
+    gitProvider: string;
+    deployProvider?: string;
+    createMissingRepos?: boolean;
+    sync?: boolean;
+    providers?: ProvidersDto;
+    restoreWorksConfig?: boolean;
+    enrichmentConfig?: ImportEnrichmentConfig;
+}
+
+/**
+ * Public request shape for POST /api/register-work and the equivalent
+ * register_work MCP tool. The GitHub credential is NOT part of this body —
+ * it travels in the X-GitHub-Token header (REST) or as a sibling tool
+ * argument that is redacted from logs (MCP).
+ */
+interface RegisterWorkRequest {
+    /** HTTPS GitHub repo URL containing .works/works.yml at root. */
+    repo: string;
+    /** Optional contact email. */
+    email?: string;
+    /** Optional opaque agent identifier (printable ASCII, ≤256 chars). */
+    agentId?: string;
+    /** Optional HTTPS URL for signed terminal-status webhooks. */
+    webhookUrl?: string;
+    /** Optional DNS-safe slug for the assigned subdomain. */
+    subdomain?: string;
+    /**
+     * Reserved for v2 paid plane — accepts x402, Skyfire, Crossmint, or
+     * Stripe Agent payment envelopes. Ignored at v1.
+     */
+    agentPayment?: Record<string, unknown>;
+}
+/**
+ * Item-source variants understood by the manifest at v1. Mirrors the YAML
+ * shape documented in docs/specs/features/agent-zero-friction-onboarding/manifest-schema.md.
+ */
+type OnboardingRequestSource = OnboardingRequestSourceAwesomeReadme | OnboardingRequestSourceWebSearch | OnboardingRequestSourceDataRepo | OnboardingRequestSourceInline;
+interface OnboardingRequestSourceAwesomeReadme {
+    type: 'awesome-readme';
+    url: string;
+    expansionFactor?: number;
+}
+interface OnboardingRequestSourceWebSearch {
+    type: 'web-search';
+    query: string;
+    max?: number;
+}
+interface OnboardingRequestSourceDataRepo {
+    type: 'data-repo';
+    url: string;
+    mode?: 'copy' | 'link';
+}
+interface OnboardingRequestSourceInline {
+    type: 'inline';
+    items: ReadonlyArray<{
+        name: string;
+        url?: string;
+        categories?: ReadonlyArray<string>;
+        tags?: ReadonlyArray<string>;
+        description?: string;
+    }>;
+}
+
+type OnboardingStatus = 'received' | 'validating' | 'validated' | 'queued' | 'generating' | 'deployed' | 'failed' | 'rejected';
+declare const ONBOARDING_TERMINAL_STATUSES: ReadonlyArray<OnboardingStatus>;
+/**
+ * Whether an {@link OnboardingStatus} marks the end of the onboarding
+ * flow — i.e. the status will not transition further. Currently
+ * `'deployed'` (success), `'failed'` (generic error), and `'rejected'`
+ * (input refused upfront) per {@link ONBOARDING_TERMINAL_STATUSES}.
+ * Callers polling for completion should stop polling once this returns
+ * `true`.
+ *
+ * @param status - The status to test.
+ * @returns `true` when the onboarding flow has ended for this status.
+ */
+declare function isTerminalOnboardingStatus(status: OnboardingStatus): boolean;
+
+type RegisterWorkStatus = OnboardingStatus;
+interface RegisterWorkResponse {
+    onboardingId: string;
+    workId: string;
+    status: RegisterWorkStatus;
+    statusUrl: string;
+    subdomain: string;
+    deploymentUrl?: string;
+    warnings?: ReadonlyArray<string>;
+}
+type RegisterWorkErrorCode = 'validation_error' | 'gh_repo_access_denied' | 'gh_credential_invalid' | 'gh_insufficient_scope_for_repo_creation' | 'manifest_missing' | 'manifest_invalid' | 'unsupported_capability' | 'repo_already_owned' | 'subdomain_taken' | 'rate_limited' | 'internal_error';
+interface ManifestValidationError {
+    path: string;
+    message: string;
+    subcode?: string;
+}
+interface RegisterWorkErrorBody {
+    statusCode: number;
+    code: RegisterWorkErrorCode;
+    message: string;
+    errors?: ReadonlyArray<ManifestValidationError>;
+}
+
+type WebhookEvent = WebhookEventTerminal | WebhookEventManifestChanged | WebhookEventDeployFailed;
+interface WebhookEventTerminal {
+    event: 'onboarding.terminal';
+    deliveryId: string;
+    occurredAt: string;
+    onboardingId: string;
+    workId: string;
+    status: Extract<OnboardingStatus, 'deployed' | 'failed' | 'rejected'>;
+    subdomain: string;
+    deploymentUrl?: string;
+    failureCode?: string;
+    failureMessage?: string;
+}
+interface WebhookEventManifestChanged {
+    event: 'work.regenerated';
+    deliveryId: string;
+    occurredAt: string;
+    workId: string;
+    commitSha: string;
+}
+interface WebhookEventDeployFailed {
+    event: 'work.deploy_failed';
+    deliveryId: string;
+    occurredAt: string;
+    workId: string;
+    failureCode: string;
+    failureMessage: string;
+}
+
+interface WorksManifestMetadata {
+    name: string;
+    slug?: string;
+    description?: string;
+    subdomain?: string;
+}
+interface WorksManifestSpec {
+    pipeline: string;
+    domain: 'software' | 'ecommerce' | 'services' | 'general';
+    taxonomy?: {
+        categories?: ReadonlyArray<string>;
+        tags?: ReadonlyArray<string>;
+        lockTaxonomy?: boolean;
+    };
+    items: {
+        sources: ReadonlyArray<OnboardingRequestSource>;
+    };
+    generators?: {
+        aiProvider?: string;
+        searchProvider?: string;
+        screenshot?: string;
+        model?: string;
+    };
+    deployment?: {
+        target?: string;
+        customDomain?: string;
+    };
+    output?: WorksManifestOutput;
+}
+interface WorksManifestOutput {
+    repos?: {
+        website?: 'managed' | 'none';
+        awesomeList?: 'managed' | 'none';
+    };
+    llmsTxt?: boolean;
+    itemsJson?: boolean;
+    markerFile?: string;
+}
+interface WorksManifestV1 {
+    apiVersion: 'works.ever.works/v1';
+    kind: 'Work';
+    metadata: WorksManifestMetadata;
+    spec: WorksManifestSpec;
+}
+
+/**
+ * Wire format for the onboarding wizard's server-side state.
+ *
+ * Persisted on `users.onboarding_state` (jsonb / simple-json). The web
+ * wizard loads this on dashboard mount and PATCHes it on every step
+ * transition so progress survives a cookie wipe or device switch.
+ */
+type OnboardingAiChoice = 'ever-works' | 'openrouter' | 'claude-code' | 'codex' | 'gemini' | 'grok';
+type OnboardingStorageChoice = 'ever-works-git' | 'user-github' | 'user-gitlab' | 'user-git';
+/**
+ * Where a Work's database lives: the platform-managed "Ever Works DB" (shared,
+ * auto-provisioned) or a bring-your-own custom database (connection details are
+ * entered on the Deploy page after the Work is created — never stored in this
+ * onboarding-state blob).
+ */
+type OnboardingDbChoice = 'ever-works-db' | 'custom';
+type OnboardingDeployChoice = 'ever-works' | 'vercel' | 'k8s';
+/**
+ * A8 — where the user actually runs Ever Works, and therefore what their
+ * first run should look like.
+ *
+ * The other four buckets all ask "which provider": AI, storage, database,
+ * deployment. None of them ask the question a desktop-first user is actually
+ * living — "is this thing running on my machine, and are my machines part of
+ * it?" — so those users landed on a cloud-shaped first run and had to find
+ * Fleet and the node apps on their own.
+ *
+ *   - `cloud`      the hosted platform (default; unchanged behaviour)
+ *   - `desktop`    the all-in-one desktop app supervising a local stack
+ *   - `own-nodes`  the platform runs elsewhere, but this person's own
+ *                  machines execute the work (Fleet + node apps)
+ */
+type OnboardingDesktopChoice = 'cloud' | 'desktop' | 'own-nodes';
+/**
+ * Wave 11 — "What do you do" onboarding step. A generic option row:
+ * stable kebab-case id + English display label + one-line description.
+ * The web wizard renders these through i18n keys keyed by `id`; the
+ * label/description here are the canonical English fallback used by
+ * non-web surfaces (desktop embeds, API docs).
+ */
+interface OnboardingProfileOption<Id extends string = string> {
+    readonly id: Id;
+    readonly label: string;
+    readonly description: string;
+}
+/**
+ * Roles for the "What do you do" step (multi-select — picking several
+ * or all is fine). Selections are hints for suggestion surfaces, never
+ * gates: nothing is hidden based on them.
+ */
+declare const ROLE_OPTIONS: readonly [{
+    readonly id: "founder-ceo";
+    readonly label: "Founder / CEO";
+    readonly description: "I run the company and wear many hats";
+}, {
+    readonly id: "engineering";
+    readonly label: "Engineering";
+    readonly description: "I build and ship software";
+}, {
+    readonly id: "product";
+    readonly label: "Product";
+    readonly description: "I define what we build and why";
+}, {
+    readonly id: "marketing";
+    readonly label: "Marketing";
+    readonly description: "I grow awareness, content, and campaigns";
+}, {
+    readonly id: "sales";
+    readonly label: "Sales";
+    readonly description: "I find, pitch, and close customers";
+}, {
+    readonly id: "consultant";
+    readonly label: "Consultant";
+    readonly description: "I deliver projects and advice for clients";
+}, {
+    readonly id: "research";
+    readonly label: "Research";
+    readonly description: "I investigate, analyze, and synthesize";
+}, {
+    readonly id: "operations";
+    readonly label: "Operations";
+    readonly description: "I keep the business running smoothly";
+}, {
+    readonly id: "support";
+    readonly label: "Support";
+    readonly description: "I help customers succeed and resolve issues";
+}, {
+    readonly id: "finance";
+    readonly label: "Finance";
+    readonly description: "I manage budgets, billing, and reporting";
+}, {
+    readonly id: "hr";
+    readonly label: "HR";
+    readonly description: "I hire, onboard, and support our people";
+}, {
+    readonly id: "legal";
+    readonly label: "Legal";
+    readonly description: "I handle contracts, compliance, and policy";
+}, {
+    readonly id: "education";
+    readonly label: "Education";
+    readonly description: "I teach, train, or create learning content";
+}, {
+    readonly id: "other";
+    readonly label: "Other";
+    readonly description: "Something else — tell us more later";
+}];
+type OnboardingRoleId = (typeof ROLE_OPTIONS)[number]['id'];
+/** Team size for the "What do you do" step (single-select). */
+declare const TEAM_SIZE_OPTIONS: readonly [{
+    readonly id: "solo";
+    readonly label: "Solo";
+    readonly description: "Just me";
+}, {
+    readonly id: "small-2-10";
+    readonly label: "Small (2–10)";
+    readonly description: "2–10 people";
+}, {
+    readonly id: "mid-11-50";
+    readonly label: "Mid (11–50)";
+    readonly description: "11–50 people";
+}, {
+    readonly id: "large-51-200";
+    readonly label: "Large (51–200)";
+    readonly description: "51–200 people";
+}, {
+    readonly id: "enterprise-200-plus";
+    readonly label: "Enterprise (200+)";
+    readonly description: "More than 200 people";
+}];
+type OnboardingTeamSizeId = (typeof TEAM_SIZE_OPTIONS)[number]['id'];
+/**
+ * Wave 11 — persisted answers of the "What do you do" step. Values are
+ * plain strings (not the narrowed id unions) so older clients keep
+ * round-tripping payloads written by newer ones; consumers validate
+ * against ROLE_OPTIONS / TEAM_SIZE_OPTIONS and DROP unrecognised values
+ * (never default them).
+ */
+interface OnboardingProfile {
+    readonly roles?: readonly string[];
+    readonly teamSize?: string;
+}
+interface OnboardingWizardStateV2 {
+    readonly version: 2;
+    readonly lastStep: number;
+    readonly ai: {
+        readonly choice: OnboardingAiChoice;
+    };
+    readonly storage: {
+        readonly choice: OnboardingStorageChoice;
+    };
+    readonly db: {
+        readonly choice: OnboardingDbChoice;
+    };
+    readonly deploy: {
+        readonly choice: OnboardingDeployChoice;
+    };
+    /**
+     * A8 — desktop-first bucket. Optional in the persisted shape so a state
+     * blob written before this bucket existed keeps round-tripping; readers
+     * fall back to {@link ONBOARDING_DEFAULT_STATE}'s `cloud`.
+     */
+    readonly desktop?: {
+        readonly choice: OnboardingDesktopChoice;
+    };
+    readonly skippedSteps: readonly string[];
+    readonly pluginsReviewed: boolean;
+    /**
+     * EW-617 G4: prompt carried over from the landing-page input
+     * (`ever.works/?prompt=…`) so the wizard's "Generate now" step can
+     * kick off generation without re-asking the user. Bounded by the
+     * same 5000-char limit as `CreateItemsGeneratorDto.prompt`.
+     */
+    readonly prompt?: string;
+    /** Wave 11 — optional "What do you do" answers (roles + team size). */
+    readonly profile?: OnboardingProfile;
+}
+/** Wire shape of `GET /api/onboarding/state`. */
+interface OnboardingStateResponse {
+    readonly completedAt: string | null;
+    readonly dismissedAt: string | null;
+    readonly state: OnboardingWizardStateV2;
+    /**
+     * Audit item A53 — the ORGANIZATION-level mirror of the "What do you
+     * do" answers, persisted on `organization_onboarding_profiles`.
+     *
+     * `state.profile` above stays the per-user answer that drives the
+     * wizard UI; this field is the org-wide read model (last writer
+     * inside the organization wins) so team-shaped suggestion surfaces
+     * can reason about the whole organization rather than one member.
+     *
+     * `null` when the request resolved no organization scope (e.g. a
+     * user who has not created an Organization yet) or when nobody in
+     * the organization has answered the step. Optional so older clients
+     * and the web fallback payloads keep type-checking unchanged.
+     */
+    readonly organizationProfile?: OnboardingProfile | null;
+}
+/**
+ * Wire shape of `PATCH /api/onboarding/state`. All fields are optional;
+ * `state` accepts a partial object that the server deep-merges with the
+ * persisted version-2 shape (re-using existing values for missing keys).
+ *
+ * Security: `state.prompt` MUST be validated server-side with
+ * `@MaxLength(5000)` in `OnboardingStatePatchInnerDto` before it is
+ * persisted or forwarded to any LLM call. Do NOT wire user-controlled
+ * prompt text into agent generation without output constraints/sandboxing.
+ */
+interface OnboardingStatePatchRequest {
+    readonly state?: Partial<{
+        readonly lastStep: number;
+        readonly ai: Partial<{
+            choice: OnboardingAiChoice;
+        }>;
+        readonly storage: Partial<{
+            choice: OnboardingStorageChoice;
+        }>;
+        readonly db: Partial<{
+            choice: OnboardingDbChoice;
+        }>;
+        readonly deploy: Partial<{
+            choice: OnboardingDeployChoice;
+        }>;
+        /** A8 — desktop-first bucket. */
+        readonly desktop: Partial<{
+            choice: OnboardingDesktopChoice;
+        }>;
+        readonly skippedSteps: readonly string[];
+        readonly pluginsReviewed: boolean;
+        /** Max 5 000 chars — enforced by `@MaxLength(5000)` in the server DTO. */
+        readonly prompt: string;
+        /**
+         * Wave 11 — "What do you do" answers. `roles` entries are validated
+         * server-side against ROLE_OPTIONS ids, `teamSize` against
+         * TEAM_SIZE_OPTIONS ids (unknown values are rejected with 400).
+         */
+        readonly profile: {
+            readonly roles?: readonly string[];
+            readonly teamSize?: string;
+        };
+    }>;
+}
+/** Wire shape of `GET /api/onboarding/catalog`. */
+interface OnboardingCatalogResponse {
+    readonly ai: ReadonlyArray<OnboardingCard<OnboardingAiChoice>>;
+    readonly storage: ReadonlyArray<OnboardingCard<OnboardingStorageChoice>>;
+    readonly db: ReadonlyArray<OnboardingCard<OnboardingDbChoice>>;
+    readonly deploy: ReadonlyArray<OnboardingCard<OnboardingDeployChoice>>;
+    /** A8 — cards for the desktop-first bucket. */
+    readonly desktop: ReadonlyArray<OnboardingCard<OnboardingDesktopChoice>>;
+    /** Plugins to surface in the "Plugins & Integrations" wizard step. */
+    readonly plugins: ReadonlyArray<OnboardingPluginCard>;
+}
+interface OnboardingCard<Choice extends string> {
+    readonly choice: Choice;
+    readonly title: string;
+    readonly description: string;
+    readonly default: boolean;
+    readonly available: boolean;
+    readonly badges: ReadonlyArray<OnboardingCardBadge>;
+    /** Plugin id behind this card, when applicable. */
+    readonly pluginId?: string;
+}
+type OnboardingCardBadge = 'default' | 'byok' | 'planned';
+interface OnboardingPluginCard {
+    readonly pluginId: string;
+    readonly name: string;
+    readonly category: string;
+    readonly description: string;
+    readonly onboardingPriority: number;
+}
+declare const ONBOARDING_DEFAULT_STATE: OnboardingWizardStateV2;
+/**
+ * A8 — first-run guidance implied by the desktop bucket. Consumed by the web
+ * wizard's final step (and any other surface that wants to point a user at the
+ * right next thing) so "which shape am I running" actually changes what the
+ * user is told to do next, rather than being a stored preference nobody reads.
+ */
+interface OnboardingDesktopNextStep {
+    readonly choice: OnboardingDesktopChoice;
+    readonly title: string;
+    readonly description: string;
+    /** In-app route to send the user to, when there is one. */
+    readonly href?: string;
+}
+declare const ONBOARDING_DESKTOP_NEXT_STEPS: Readonly<Record<OnboardingDesktopChoice, OnboardingDesktopNextStep>>;
+/** The guidance for a bucket choice, defaulting to the cloud path. */
+declare function desktopNextStep(choice: OnboardingDesktopChoice | undefined): OnboardingDesktopNextStep;
+
+/**
+ * AW-20 P1 — the roster vocabulary shared by the API, the agent package
+ * and the web wizard step.
+ *
+ * A **roster** is not a new entity: it is the set of Agents the platform
+ * provisions for one person in one workspace scope, each carrying a
+ * **lane**. Everything here is a closed vocabulary so the wizard, the
+ * provisioning service and the DTO validators cannot drift apart — the
+ * same trick `ROLE_OPTIONS` / `TEAM_SIZE_OPTIONS` already use one file
+ * over.
+ */
+/**
+ * A lane is a short, stable key naming the area of work one Agent owns
+ * (FR-26). Seven ship with the build, and the catalogue is capped at 12
+ * (FR-30) so the "add a lane" menu stays a menu rather than a directory.
+ *
+ * 🛑 A lane is a **label, not a permission** (FR-27). It grants nothing,
+ * restricts nothing, and must never be consulted by an authorization
+ * decision. It exists so a surface can ask "who owns research here?" and
+ * get a stable answer instead of grepping free-text titles.
+ */
+declare const ROSTER_LANE_KEYS: readonly ["coordination", "research", "content", "outreach", "visibility", "social", "market-watch"];
+type RosterLaneKey = (typeof ROSTER_LANE_KEYS)[number];
+/**
+ * Named starting rosters. Content that ships with the build, not data:
+ * a blueprint changes when we deploy, never when a user acts, and it
+ * must mean the same thing in a bug report as it does in production.
+ */
+declare const ROSTER_BLUEPRINT_SLUGS: readonly ["general", "growth", "revenue", "insight", "solo-starter"];
+type RosterBlueprintSlug = (typeof ROSTER_BLUEPRINT_SLUGS)[number];
+/**
+ * The most lanes one provisioning run will set up (FR-6). A blueprint
+ * may declare at most this many, and a user adding lanes by hand stops
+ * here too — more agents than this in one go is a fleet, not a start.
+ */
+declare const ROSTER_MAX_LANES = 8;
+/** Longest agent name the roster step accepts, in characters (FR-7). */
+declare const ROSTER_NAME_MAX = 60;
+
+/**
+ * AW-20 — the first-hour vocabulary: what a new owner still has to do,
+ * and what happened the last time we set their agents up.
+ *
+ * The milestone enum lands with P1 because the provisioning record it
+ * sits beside is written by P1's roster run; the checklist surfaces that
+ * read these milestones are P2. Nothing here is persisted twice: the
+ * provisioning record is one JSON column on the checklist row.
+ */
+
+/**
+ * The five first-hour milestones, in the order they are shown (FR-34).
+ * Order is part of the contract — the card renders this array.
+ */
+declare const ONBOARDING_MILESTONES: readonly ["connectProvider", "meetAgents", "shipTask", "resolveDecision", "scheduleJob"];
+type OnboardingMilestoneKey = (typeof ONBOARDING_MILESTONES)[number];
+/** `pending → done` is one-way; `pending ⇄ skipped` is reversible (FR-35, FR-40). */
+declare const MILESTONE_STATUSES: readonly ["pending", "done", "skipped"];
+type MilestoneStatus = (typeof MILESTONE_STATUSES)[number];
+/**
+ * One milestone's state. A milestone is never marked done on the
+ * client's word (FR-36): `evidenceKind` / `evidenceId` record which
+ * platform fact satisfied it, so "how do I know this is true?" has an
+ * answer that is not "the browser said so".
+ */
+interface MilestoneRecord {
+    readonly status: MilestoneStatus;
+    readonly completedAt?: string | null;
+    /** What satisfied it: 'connection' | 'roster' | 'run' | 'approval' | 'escalation' | 'schedule'. */
+    readonly evidenceKind?: string | null;
+    /** Opaque id of the satisfying object. Never rendered; used for the "what completed it" line. */
+    readonly evidenceId?: string | null;
+    /**
+     * FR-59 degradation flag. True when this milestone's completion fact
+     * could not be read on the last evaluation. The milestone stays
+     * `pending` and the row renders a quiet "couldn't check" marker —
+     * an unreadable fact must never be allowed to look like a done one,
+     * and must never fail the whole checklist.
+     */
+    readonly unknown?: boolean;
+}
+/**
+ * Provisioning run states (FR-10). There is no other state: a record
+ * that is not one of these is a bug, not a new case to handle.
+ */
+declare const ROSTER_PROVISION_STATES: readonly ["idle", "queued", "creating", "binding", "ready", "partial", "failed"];
+type RosterProvisionState = (typeof ROSTER_PROVISION_STATES)[number];
+/**
+ * What happened to one lane (FR-11). `reused` is a success: the point of
+ * idempotent provisioning is that a second run fills gaps rather than
+ * creating a second "Research".
+ */
+declare const LANE_OUTCOMES: readonly ["pending", "created", "reused", "skippedNoSeat", "failed"];
+type LaneOutcome = (typeof LANE_OUTCOMES)[number];
+/** Why one lane failed. Closed vocabulary — the UI maps each to its own copy. */
+declare const LANE_FAILURE_REASONS: readonly ["nameUnavailable", "noSeat", "permissionDenied", "timedOut", "unknown"];
+type LaneFailureReason = (typeof LANE_FAILURE_REASONS)[number];
+/** One lane's outcome inside a provisioning run. */
+interface RosterLaneResult {
+    readonly laneKey: RosterLaneKey;
+    readonly templateSlug: string;
+    readonly requestedName: string;
+    readonly outcome: LaneOutcome;
+    readonly agentId?: string | null;
+    /** Set when a numeric suffix was needed to find a free name (FR-18). */
+    readonly finalName?: string | null;
+    readonly failureReason?: LaneFailureReason | null;
+    /** Skills that could not be attached (FR-23). A warning, never a failure. */
+    readonly skillWarnings?: readonly string[];
+}
+/**
+ * The current or last roster provisioning attempt. Persisted as one JSON
+ * object on the checklist row rather than its own table: it is bounded,
+ * one-to-one with a row that already exists, written only by
+ * provisioning and read only in the moments around it.
+ */
+interface RosterProvisionRecord {
+    readonly runId: string;
+    readonly blueprintSlug: RosterBlueprintSlug;
+    readonly state: RosterProvisionState;
+    readonly startedAt: string;
+    readonly finishedAt?: string | null;
+    readonly lanes: readonly RosterLaneResult[];
+}
+
+/**
+ * Role-driven starter seeding for the onboarding "What do you do" step.
+ *
+ * The first cut of this feature resolved suggestions IN THE BROWSER: the
+ * step fetched the whole prebuilt-agent catalog and intersected
+ * `suggestedRoles` client-side. Three things were wrong with that.
+ *
+ *  1. Coverage was accidental. Only the roles that happened to appear in
+ *     a go-to-market template's `suggestedRoles` produced anything —
+ *     3 of the 14 roles the step actually offers. The other 11 selected
+ *     a role and were shown nothing, which reads as "we have nothing
+ *     for you" rather than "nobody wrote the mapping".
+ *  2. It was Agents-only. A role implies a starting KIT — the agents to
+ *     activate AND the skills that make them useful — and the skills
+ *     half simply did not exist.
+ *  3. The mapping lived in the client bundle, so every non-web surface
+ *     (desktop shell, chat, API consumers) had no way to ask "what
+ *     should a Marketing person start with?".
+ *
+ * The mapping is therefore server-side (`@ever-works/agent/agents`,
+ * `role-seeding.ts`), exposed over `/api/onboarding/suggestions`, and
+ * pinned by a spec that fails if ANY role in `ROLE_OPTIONS` is missing.
+ * These are the wire shapes for that surface.
+ */
+/** One prebuilt Agent template offered for the selected roles. */
+interface OnboardingSeedAgentSuggestion {
+    /** Template slug — the id `POST /api/agents/from-template/:slug` takes. */
+    readonly slug: string;
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    /** Template category, e.g. `marketing` / `sales` / `ops`. */
+    readonly category: string;
+    /** Role ids (from `ROLE_OPTIONS`) that caused this template to surface. */
+    readonly matchedRoles: readonly string[];
+}
+/** One first-party Skill offered for the selected roles. */
+interface OnboardingSeedSkillSuggestion {
+    /** Skill catalog slug. */
+    readonly slug: string;
+    readonly title: string;
+    readonly description: string;
+    /** Go-to-market stage the Skill powers. */
+    readonly stage: string;
+    /** Role ids (from `ROLE_OPTIONS`) that caused this Skill to surface. */
+    readonly matchedRoles: readonly string[];
+}
+/**
+ * Wire shape of `GET /api/onboarding/suggestions`.
+ *
+ * `roles` echoes the RECOGNISED subset of the request (unknown ids are
+ * dropped, never defaulted, matching how the wizard state validates its
+ * own `profile.roles`). An empty `roles` yields empty suggestion lists
+ * rather than a "here is everything" dump.
+ */
+interface OnboardingSeedSuggestionsResponse {
+    readonly roles: readonly string[];
+    /** Ids that were sent but are not in `ROLE_OPTIONS` — echoed so the caller can notice a typo. */
+    readonly unknownRoles: readonly string[];
+    readonly agents: readonly OnboardingSeedAgentSuggestion[];
+    readonly skills: readonly OnboardingSeedSkillSuggestion[];
+}
+/**
+ * Request body of `POST /api/onboarding/suggestions/seed`.
+ *
+ * `roles` is optional: omitted, the server uses the roles already saved
+ * on the caller's onboarding state, so the client never has to be the
+ * authority on what the user picked.
+ */
+interface OnboardingSeedRequest {
+    readonly roles?: readonly string[];
+}
+/** Per-template outcome of a seeding run. */
+type OnboardingSeedOutcome = 'created' | 'already-exists' | 'failed';
+interface OnboardingSeedResultEntry {
+    readonly slug: string;
+    readonly outcome: OnboardingSeedOutcome;
+    /** Id of the Agent created by THIS run; null for every other outcome. */
+    readonly agentId: string | null;
+    /** Short, non-sensitive reason — present only for `failed`. */
+    readonly reason?: string;
+}
+/**
+ * Wire shape of `POST /api/onboarding/suggestions/seed`.
+ *
+ * Seeding is idempotent and best-effort per template: a template that
+ * is already activated reports `already-exists` instead of failing the
+ * whole call, so re-running the step never produces duplicates and a
+ * single bad template never blocks the rest of the kit.
+ */
+interface OnboardingSeedResponse {
+    readonly roles: readonly string[];
+    readonly agents: readonly OnboardingSeedResultEntry[];
+    /** Skills recommended alongside the seeded agents (informational). */
+    readonly skills: readonly OnboardingSeedSkillSuggestion[];
+    readonly createdCount: number;
+    readonly skippedCount: number;
+    readonly failedCount: number;
+}
+
+/**
+ * EW-628 data-repo instant-sync — wire-format contract for the activity
+ * row `details` payload emitted by the API and consumed by the web
+ * `SyncEventRow` component.
+ *
+ * Spec: `docs/specs/features/data-repo-instant-sync/spec.md` §5.6.
+ *
+ * The discriminated union is the canonical source of truth for both
+ * sides — `apps/api/src/data-sync/data-sync.service.ts` writes it into
+ * `activity_log.details`, and `apps/web/src/components/works/detail/
+ * activity/SyncEvent.types.ts` re-exports it as `SyncEvent` so the
+ * row renderer's exhaustive switch stays in lock-step.
+ *
+ * `kind` (not `status`) discriminates row variants — the activity-feed
+ * convention reserves `status` for HTTP / pipeline lifecycle values
+ * (`COMPLETED` / `FAILED` / `CANCELLED`), which live on the parent
+ * `activity_log` row.
+ */
+/** Which transport surfaced the sync attempt. */
+type SyncEventSource = 'webhook' | 'poll' | 'manual';
+/**
+ * Skip reasons the dispatcher or the three gates emit. Locked to a
+ * small literal union so dashboards can pivot on it without parsing
+ * free-form text.
+ */
+type SyncEventSkipReason = 'retry-backoff' | 'sync-in-progress' | 'generation-in-progress' | 'no-changes' | 'app-not-installed-and-no-credentials';
+/**
+ * Failure classes the render gate maps caught errors to. The set is
+ * deliberately small — adding a new class is a deliberate schema
+ * decision, not an autopilot fallback. `unknown` is the explicit
+ * fallback when nothing matches.
+ */
+type SyncEventErrorClass = 'data-repo-unreachable' | 'main-repo-push-rejected' | 'work-not-found' | 'timeout' | 'unknown';
+interface SyncEventSuccess {
+    kind: 'success';
+    source: SyncEventSource;
+    beforeSha?: string;
+    afterSha?: string;
+    filesChanged: number;
+    durationMs?: number;
+}
+interface SyncEventSkipped {
+    kind: 'skipped';
+    source: SyncEventSource;
+    reason: SyncEventSkipReason;
+}
+interface SyncEventFailed {
+    kind: 'failed';
+    source: SyncEventSource;
+    errorClass: SyncEventErrorClass;
+    errorTail: string;
+}
+/**
+ * The discriminated union the API writes into `activity_log.details`
+ * for every `data_sync_*` row, and the web reads back to render the
+ * `SyncEventRow`.
+ */
+type SyncEventPayload = SyncEventSuccess | SyncEventSkipped | SyncEventFailed;
+/** Narrow `kind` values used as React keys + telemetry labels. */
+type SyncEventKind = SyncEventPayload['kind'];
+
+/**
+ * EW-658 (Tenants & Organizations Phase 6) — wire-types for the
+ * Organization-create / list / update / upgrade-from-account API
+ * surface.
+ *
+ * Plain TypeScript interfaces so the API package and the web package
+ * speak the same shape over the wire without dragging NestJS / TypeORM
+ * decorators across the workspace boundary.
+ */
+
+interface CreateOrganizationRequest {
+    /** Display name. 1-200 chars. */
+    name: string;
+    /** Optional slug override. If omitted, allocated from `name`. */
+    slug?: string;
+    /**
+     * PR-6 (domain-model evolution §23.5) — optional company vision
+     * statement. Trimmed + capped at 5000 chars server-side; empty /
+     * whitespace-only collapses to null.
+     */
+    vision?: string | null;
+}
+/**
+ * EW-662 (Tenants & Organizations Phase 10) — body for
+ * `POST /api/organizations/register-company`.
+ *
+ * Driven by the Company chip on `+ New`. The service hard-codes
+ * `registrationProvider = 'manual'` and `registrationStatus =
+ * 'registered'` for v1 (Stripe Atlas integration is deferred); the
+ * client only supplies the user-visible fields.
+ */
+interface RegisterCompanyRequest {
+    /** Display name. 1-200 chars. */
+    name: string;
+    /** Registered legal name. Defaults to `name` when omitted. */
+    legalName?: string;
+    /** ISO 3166-1 alpha-2 country code (e.g. `'US'`). */
+    countryCode?: string;
+    /** Optional slug override. If omitted, allocated from `name`. */
+    slug?: string;
+}
+interface UpdateOrganizationRequest {
+    displayName?: string;
+    legalName?: string;
+    countryCode?: string;
+    /**
+     * PR-6 — company vision. Omit to leave unchanged; explicit `null`
+     * clears it. Any present value (including `null`) bumps
+     * `visionUpdatedAt` to now.
+     */
+    vision?: string | null;
+    /**
+     * Merge-policy matrix (Wave 3, D4) — the organization-scoped PARTIAL.
+     * Omit to leave unchanged; explicit `null` clears the override so
+     * everything inherits the tenant, then the platform default. Fields
+     * omitted INSIDE the object inherit individually.
+     */
+    mergePolicy?: MergePolicyOverride | null;
+    /**
+     * AW-15 — connection safety settings. Omit to leave unchanged; explicit
+     * `null` resets every setting to its default. Today one setting:
+     * `requireHttpsForCredentials` ("Require https for connection
+     * credentials", default off).
+     */
+    connectionPolicy?: OrganizationConnectionPolicy | null;
+}
+interface OrganizationResponse {
+    id: string;
+    tenantId: string;
+    slug: string;
+    legalName: string | null;
+    displayName: string | null;
+    countryCode: string | null;
+    registrationProvider: string | null;
+    registrationStatus: string | null;
+    linkedWorkId: string | null;
+    /** PR-6 — company vision statement (null = never set / cleared). */
+    vision: string | null;
+    /** PR-6 — ISO timestamp of the last vision change (null = never set). */
+    visionUpdatedAt: string | null;
+    /**
+     * Merge-policy matrix (Wave 3, D4) — the PARTIAL stored on this row.
+     * `null` means the organization declares nothing. OPTIONAL rather than
+     * required: the field is additive, so a response from an API build that
+     * predates it simply omits the key, and every consumer already has to
+     * treat "absent" and "null" the same way (both mean "inherit").
+     *
+     * The EFFECTIVE policy is a fold of four scopes and is never derivable
+     * from this field alone — read `GET /api/merge-policy/resolve` for that.
+     */
+    mergePolicy?: MergePolicyOverride | null;
+    /**
+     * AW-15 — the stored connection safety settings. `null` / absent = every
+     * default (literal connection credentials over plain http are allowed,
+     * with a warning).
+     */
+    connectionPolicy?: OrganizationConnectionPolicy | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CheckSlugAvailabilityResponse {
+    /** True iff the slug collides with neither `users.slug` nor `organizations.slug`. */
+    available: boolean;
+    /** Echo of the normalized form of the input (for the caller to display). */
+    normalized: string;
+    /** If unavailable, a next-free `-N` suggestion. Omitted when available. */
+    suggestion?: string;
+}
+interface UpgradeFromAccountResponse {
+    organizationId: string;
+    tenantId: string;
+    /** Total Tier A rows updated across all enumerated tables. */
+    tierARowsUpdated: number;
+    /** Total Tier B rows updated. */
+    tierBRowsUpdated: number;
+    /**
+     * EW-663 (Phase 11 follow-up) — total Tier C rows backfilled via the
+     * parent-FK join walk (e.g. `conversation_messages` whose parent
+     * `conversations` belongs to the user). Zero before Phase 11 ships
+     * and on second-call idempotency.
+     */
+    tierCRowsUpdated: number;
+}
+/**
+ * Error code returned with 409 Conflict when `upgrade-from-account` is
+ * called after the user has created additional Organizations (spec §5.2,
+ * "first-Org guard"). The endpoint is only callable while the user has
+ * **exactly one** Organization under their Tenant.
+ */
+declare const UPGRADE_NOT_AVAILABLE_AFTER_MULTIPLE_ORGS: "UPGRADE_NOT_AVAILABLE_AFTER_MULTIPLE_ORGS";
+
+/** Reserved transport contract; Organization slugs can never collide with this value. */
+declare const ACTIVE_SCOPE_PERSONAL_SENTINEL: "@personal";
+declare const ACTIVE_SCOPE_API_HEADER: "x-scope-slug";
+declare const ACTIVE_SCOPE_BROWSER_HEADER: "x-ever-workspace";
+declare const ACTIVE_SCOPE_RESPONSE_PROPERTIES: {
+    tenantId: {
+        type: "string";
+        format: "uuid";
+        nullable: true;
+    };
+    organizationId: {
+        type: "string";
+        format: "uuid";
+        nullable: true;
+    };
+    organizationSlug: {
+        type: "string";
+        nullable: true;
+    };
+};
+type ActiveScopeResponseKey = keyof typeof ACTIVE_SCOPE_RESPONSE_PROPERTIES;
+/** Runtime OpenAPI schema and source of truth for the active-scope response keys. */
+declare const ACTIVE_SCOPE_RESPONSE_SCHEMA: {
+    type: "object";
+    properties: {
+        tenantId: {
+            type: "string";
+            format: "uuid";
+            nullable: true;
+        };
+        organizationId: {
+            type: "string";
+            format: "uuid";
+            nullable: true;
+        };
+        organizationSlug: {
+            type: "string";
+            nullable: true;
+        };
+    };
+    required: ActiveScopeResponseKey[];
+};
+/** Wire response shared by the API and every active-scope consumer. */
+type ActiveScopeResponse = {
+    [Key in ActiveScopeResponseKey]: string | null;
+};
+
+/**
+ * Dynamic plugin distribution (EW-693).
+ *
+ * Per-replica install lifecycle for a distributable plugin. Distinct
+ * from `state` (load-lifecycle) and `enabled` (per-user/per-work) so
+ * the UI can show all three independently.
+ *
+ * - `available`: known in the catalog but not yet installed on this node.
+ * - `installing`: currently being resolved / downloaded / placed.
+ * - `installed`: present on disk and importable; may or may not be enabled.
+ * - `error`: last install attempt failed; `installError` carries the reason.
+ */
+type PluginInstallState = 'available' | 'installing' | 'installed' | 'error';
+/**
+ * Source the plugin's code came from on this deployment. Denormalised
+ * onto the row for listing; the manifest's `distribution` is the
+ * source of truth for "could this plugin ever be installed at runtime?"
+ */
+type PluginInstallSource = 'bundled' | 'registry';
+/**
+ * Wire payload describing where a plugin sits in the install lifecycle.
+ * Returned by `GET /plugins/:id/install-status` and embedded in the
+ * plugin list / catalog responses (see {@link PluginCatalogEntry}).
+ */
+interface PluginInstallStateDto {
+    readonly pluginId: string;
+    readonly installState: PluginInstallState;
+    readonly source: PluginInstallSource;
+    /** npm spec actually installed, e.g. `@ever-works/notion-extractor-plugin@1.2.0`. */
+    readonly registrySpec?: string;
+    readonly installedVersion?: string;
+    /** Integrity used to verify the install (sha512 from the registry). */
+    readonly integrity?: string;
+    /** Last error message if `installState === 'error'`. */
+    readonly installError?: string;
+    readonly updatedAt?: string;
+}
+
+/**
+ * Dynamic plugin distribution (EW-693).
+ *
+ * A single entry in `GET /plugins/catalog` — the listable set of
+ * distributable plugins. Manifest summary only (id/name/category/...)
+ * + the local install state so the UI can render an "available"
+ * card before the plugin has ever been instantiated.
+ */
+interface PluginCatalogEntry {
+    readonly pluginId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly category: string;
+    readonly capabilities: readonly string[];
+    readonly version: string;
+    readonly distribution: 'core' | 'registry';
+    /** npm package name (e.g. `@ever-works/notion-extractor-plugin`). */
+    readonly packageName?: string;
+    /** Most recent version published to the registry (catalog-side). */
+    readonly latestVersion?: string;
+    readonly homepage?: string;
+    readonly author?: string;
+    readonly deprecated?: boolean;
+    /** Per-replica install state, merged from the local DB. */
+    readonly install: PluginInstallStateDto;
+}
+/**
+ * Catalog response envelope. Errors fetching the upstream catalog are
+ * surfaced via {@link PluginCatalogResponse.fetchedAt} being absent
+ * and {@link PluginCatalogResponse.degraded} being true, so the UI
+ * can show "registry unreachable — only locally-known plugins listed".
+ */
+interface PluginCatalogResponse {
+    readonly entries: readonly PluginCatalogEntry[];
+    readonly fetchedAt?: string;
+    /** True when the registry call failed and entries reflect local state only. */
+    readonly degraded?: boolean;
+    readonly degradedReason?: string;
+}
+/**
+ * Request body for `POST /plugins/:id/install`.
+ *
+ * - `version` is optional; when omitted the server resolves the
+ *   latest matching version pinned via the allowlist (or the
+ *   `@ever-works/*` package's `latest` dist-tag for first-party).
+ * - `integrity` is optional; when provided the server MUST refuse
+ *   if the downloaded integrity does not match (FR-10).
+ * - `source` lets a self-hoster prefer `github-packages` over the
+ *   default public npm mirror, when both are configured.
+ */
+interface PluginInstallRequestDto {
+    readonly version?: string;
+    readonly integrity?: string;
+    readonly source?: 'npm' | 'github-packages';
+}
+/**
+ * Response body for `POST /plugins/:id/install` (sync 202-accepted
+ * envelope). The actual install runs asynchronously; clients poll
+ * `GET /plugins/:id/install-status` for terminal state.
+ */
+interface PluginInstallResponseDto {
+    readonly pluginId: string;
+    readonly install: PluginInstallStateDto;
+}
+
+/**
+ * Dynamic plugin distribution (EW-693).
+ *
+ * Admin-managed list of non-first-party packages permitted for
+ * runtime install. First-party `@ever-works/*` is implicitly allowed
+ * (no row required); everything else must match an enabled
+ * `plugin_allowlist` row by name + version range, otherwise the
+ * installer refuses the package BEFORE any network fetch (FR-11).
+ */
+interface PluginAllowlistEntryDto {
+    readonly id: string;
+    /** Full npm package name, e.g. `@some-vendor/cool-plugin`. */
+    readonly packageName: string;
+    /** Semver range pinning what versions are allowed, e.g. `^2.0.0` or `2.1.3`. */
+    readonly versionRange: string;
+    /** Optional integrity (sha512); when set the install MUST match. */
+    readonly integrity?: string;
+    readonly source: 'npm' | 'github-packages';
+    readonly enabled: boolean;
+    readonly createdAt: string;
+}
+/** Body for `POST /admin/plugins/allowlist`. */
+interface CreatePluginAllowlistEntryDto {
+    readonly packageName: string;
+    readonly versionRange: string;
+    readonly integrity?: string;
+    readonly source?: 'npm' | 'github-packages';
+    readonly enabled?: boolean;
+}
+/** Body for `PATCH /admin/plugins/allowlist/:id` (toggle / re-pin). */
+interface UpdatePluginAllowlistEntryDto {
+    readonly versionRange?: string;
+    readonly integrity?: string;
+    readonly enabled?: boolean;
+}
+/** Response envelope for `GET /admin/plugins/allowlist`. */
+interface PluginAllowlistResponseDto {
+    readonly entries: readonly PluginAllowlistEntryDto[];
+}
+
+/**
+ * What's new (AW-14) — closed vocabularies for product changelog entries.
+ *
+ * Nothing persists a category or a kind: entries come from a content source
+ * that ships with the build, and only per-person read state is stored. These
+ * tuples are therefore the single definition both the API and the web app
+ * validate against.
+ */
+/**
+ * The product area an entry belongs to (spec FR-9). A closed set of six —
+ * adding a seventh is a spec change, not an authoring decision. Drives the
+ * filter chips in the What's new panel.
+ */
+declare const CHANGELOG_CATEGORIES: readonly ["agents", "decisions", "knowledge", "connections", "costs", "platform"];
+type ChangelogCategory = (typeof CHANGELOG_CATEGORIES)[number];
+/**
+ * What kind of change an entry describes (spec FR-10). Rendered as a badge
+ * only — kind is never a filter dimension.
+ */
+declare const CHANGELOG_KINDS: readonly ["new", "improved", "fixed", "security"];
+type ChangelogKind = (typeof CHANGELOG_KINDS)[number];
+/** Narrowing guard for a category read from an untrusted source (query string, content file). */
+declare function isChangelogCategory(value: unknown): value is ChangelogCategory;
+/** Narrowing guard for a kind read from an untrusted source. */
+declare function isChangelogKind(value: unknown): value is ChangelogKind;
+/**
+ * Spec FR-39 — is `raw` an in-product path a call-to-action may navigate to?
+ *
+ * True only for a string that begins with exactly one `/` and carries no
+ * backslash, whitespace or control character anywhere. That single rule
+ * rejects every form FR-39 names: an absolute URL to another origin or any
+ * scheme-bearing string (neither can start with `/`), a protocol-relative
+ * `//host`, a backslash-obfuscated `/\host`, and `/<tab>/host`, which
+ * browsers collapse to `//host` because they strip tabs and newlines from
+ * URLs before parsing them.
+ *
+ * Shared so the API (which drops an unsafe call-to-action when it loads
+ * entries) and every client (which re-checks before rendering the button)
+ * apply the identical rule.
+ */
+declare function isSafeInAppPath(raw: unknown): raw is string;
+/**
+ * Stable entry identifier grammar (spec FR-6): a lowercase slug of 3–64
+ * characters. It is the permalink and is never reused for a different entry.
+ */
+declare const CHANGELOG_SLUG_PATTERN: RegExp;
+/** Authoring limits (spec FR-5, FR-17, FR-15, FR-26, FR-27). */
+declare const CHANGELOG_LIMITS: {
+    readonly titleMaxLength: 80;
+    readonly bodyMaxLength: 600;
+    readonly bodyMaxParagraphs: 3;
+    readonly ctaLabelMaxLength: 32;
+    /** Most slugs one mark-read write may carry. */
+    readonly markReadBatchMax: 25;
+    /** The unread count only ever considers this many of the newest entries. */
+    readonly unreadWindow: 50;
+    /** Default page size for the panel and the full list. */
+    readonly pageSize: 20;
+    /** Largest page a client may request. */
+    readonly pageSizeMax: 50;
+    /** The deepest the list can be paged. */
+    readonly listMax: 200;
+};
+
+/**
+ * What's new (AW-14) — wire contracts for `GET/POST /api/changelog/*`.
+ *
+ * Pure types, no decorators, so the API, the web app and any external client
+ * can import them. Additive-only (these ship in a public package).
+ */
+/** An in-product call-to-action: a button label and the app path it opens. */
+interface ChangelogCtaDto {
+    label: string;
+    /** Always an in-product path beginning with exactly one `/` (spec FR-39). */
+    href: string;
+}
+/**
+ * One product changelog entry as a reader sees it.
+ *
+ * Title and body are authored in English and are content, not interface
+ * chrome — they are never passed through the translation layer (spec FR-11).
+ */
+interface ChangelogEntryDto {
+    /** Stable slug; the permalink (spec FR-6). */
+    slug: string;
+    /** ≤ 80 characters (spec FR-5). */
+    title: string;
+    /** Plain text, ≤ 600 characters, ≤ 3 paragraphs, line breaks preserved (spec FR-5). */
+    body: string;
+    category: ChangelogCategory;
+    kind: ChangelogKind;
+    /** ISO-8601 publish timestamp. Future-dated entries are never returned (spec FR-7). */
+    publishedAt: string;
+    /** At most one entry is pinned; it sorts first (spec FR-8). */
+    pinned: boolean;
+    /** `null` when the entry has no call-to-action OR its target is not a safe in-product path (spec FR-40). */
+    cta: ChangelogCtaDto | null;
+    /** Read for this person — explicitly, or because it predates their account (spec FR-14). */
+    isRead: boolean;
+}
+/** `GET /api/changelog` */
+interface ChangelogListResponseDto {
+    entries: ChangelogEntryDto[];
+    /** Slug of the last returned entry when another page exists, otherwise `null`. */
+    nextCursor: string | null;
+    /** Visible entries in this build, ignoring any category filter. */
+    total: number;
+    /** Always the UNFILTERED unread count — a category filter never changes it (spec FR-38). */
+    unreadCount: number;
+    /** Categories that have at least one visible entry; the others render as disabled chips (spec FR-37). */
+    categoriesWithEntries: ChangelogCategory[];
+}
+/** `GET /api/changelog/unread-count` */
+interface ChangelogUnreadCountResponseDto {
+    count: number;
+}
+/** `POST /api/changelog/read` and `POST /api/changelog/read-all` */
+interface ChangelogMarkReadResponseDto {
+    /** The reader's fresh unread count after the write (spec FR-18, FR-19). */
+    unreadCount: number;
+}
+/** `POST /api/changelog/read` request body. */
+interface ChangelogMarkReadRequestDto {
+    /** 1–25 entry slugs (spec FR-17). Slugs this build does not know are ignored. */
+    slugs: string[];
+}
+/**
+ * The authoring shape a changelog content source yields — what a person (or
+ * a later non-file source) writes, before the API validates it and resolves
+ * per-reader read state.
+ *
+ * Kept in contracts rather than inside the API so a content source that
+ * lives outside `apps/api` can produce records of exactly this shape.
+ */
+interface ChangelogSourceEntry {
+    readonly slug: string;
+    readonly title: string;
+    readonly body: string;
+    readonly category: ChangelogCategory;
+    readonly kind: ChangelogKind;
+    /** ISO-8601 date or date-time. */
+    readonly publishedAt: string;
+    readonly pinned?: boolean;
+    readonly cta?: {
+        readonly label: string;
+        readonly href: string;
+    };
+}
+
+/**
+ * AW-01 — wire-types for the workspace-wide search behind the dashboard
+ * command palette (`GET /api/workspace-search`).
+ *
+ * Deliberately a different word from the existing `/api/search`, which means
+ * "search the web through the configured search plugin". The two surfaces
+ * never share a path, a controller or a type.
+ */
+/**
+ * Every record kind the palette can return. The first ten ship with the live
+ * fan-out; the remaining kinds are reserved so a later index-backed read can
+ * add them without a wire change.
+ */
+declare const WORKSPACE_SEARCH_KINDS: readonly ["mission", "task", "agent", "work", "idea", "skill", "team", "knowledge", "run", "decision", "memory", "goal", "meeting", "node", "connection"];
+type WorkspaceSearchKind = (typeof WORKSPACE_SEARCH_KINDS)[number];
+/** How a hit matched the query — the band that produced its base score. */
+type WorkspaceSearchMatchReason = 'exact' | 'prefix' | 'wordPrefix' | 'contains' | 'identifier' | 'secondary' | 'fuzzy';
+/** Shortest trimmed query the server answers; shorter queries return no groups. */
+declare const WORKSPACE_SEARCH_MIN_QUERY_LENGTH = 2;
+/** Longest query the server matches; longer input is truncated, not rejected. */
+declare const WORKSPACE_SEARCH_MAX_QUERY_LENGTH = 128;
+/** Hard ceiling on rows across all groups in one response. */
+declare const WORKSPACE_SEARCH_MAX_TOTAL = 60;
+/** Default rows per group when no filter is applied. */
+declare const WORKSPACE_SEARCH_DEFAULT_PER_KIND = 5;
+/** Hard ceiling on rows for one group, reached when a group filter is applied. */
+declare const WORKSPACE_SEARCH_MAX_PER_KIND = 25;
+/** How many recently opened records a client may send to boost ranking. */
+declare const WORKSPACE_SEARCH_MAX_RECENT = 12;
+interface WorkspaceSearchHit {
+    /** `${kind}:${sourceId}` — a stable client key. */
+    id: string;
+    kind: WorkspaceSearchKind;
+    sourceId: string;
+    title: string;
+    /** Breadcrumb, path, identifier or owner. */
+    subtitle: string | null;
+    /** Raw status value of the source record (rendered as a badge). */
+    statusLabel: string | null;
+    /** Locale-agnostic dashboard route the row opens. */
+    destination: string;
+    /** Deterministic 0..100. */
+    score: number;
+    matchReason: WorkspaceSearchMatchReason;
+    /** ISO 8601. */
+    updatedAt: string | null;
+}
+interface WorkspaceSearchGroup {
+    kind: WorkspaceSearchKind;
+    /** Matches before the per-group cap — drives the "Show all" row. */
+    total: number;
+    hits: WorkspaceSearchHit[];
+}
+interface WorkspaceSearchResponse {
+    query: string;
+    groups: WorkspaceSearchGroup[];
+    /** Kinds whose source failed; the client renders a partial-results notice. */
+    degradedKinds: WorkspaceSearchKind[];
+    servedBy: 'index' | 'fanout' | 'mixed';
+    tookMs: number;
+}
+
+/**
+ * Help centre (AW-25) — closed vocabularies and the structured article grammar.
+ *
+ * The in-product manual renders pages of the documentation site (`docs/`) that
+ * ship with the build. Nothing here is persisted: a build-time generator turns
+ * those Markdown pages into the structured blocks below, and the web app renders
+ * the blocks without ever injecting raw markup (spec FR-28). These tuples and
+ * types are the one definition the generator, the renderer and any later API
+ * surface agree on.
+ */
+/**
+ * The manual's sections, in reading order (spec FR-4). A closed set of six —
+ * adding a seventh is a spec change, not an authoring decision.
+ */
+declare const HELP_SECTIONS: readonly ["start-here", "running-the-loop", "your-agents", "setup-and-connections", "money-and-limits", "when-something-goes-wrong"];
+type HelpSection = (typeof HELP_SECTIONS)[number];
+/**
+ * Every block kind an article body may contain (spec FR-27). Closed — the
+ * renderer switches over this set without a default branch, so a new kind is a
+ * compile error until it is rendered. `table` is part of the set because the
+ * documentation pages the manual reuses present reference material as tables.
+ */
+declare const HELP_BLOCK_KINDS: readonly ["paragraph", "heading", "orderedList", "unorderedList", "note", "shortcut", "code", "link", "table"];
+type HelpBlockKind = (typeof HELP_BLOCK_KINDS)[number];
+/** What a link may point at (spec FR-27a). Closed. */
+declare const HELP_LINK_TARGET_TYPES: readonly ["article", "screen", "external"];
+type HelpLinkTargetType = (typeof HELP_LINK_TARGET_TYPES)[number];
+/** Visual tone of a callout block. Closed. */
+declare const HELP_NOTE_TONES: readonly ["note", "tip", "info", "warning", "danger"];
+type HelpNoteTone = (typeof HELP_NOTE_TONES)[number];
+/**
+ * Build-time limits (spec FR-3). Where the manual reuses an existing
+ * documentation page, the body and heading ceilings are sized for those pages
+ * rather than for short purpose-written articles.
+ */
+declare const HELP_LIMITS: {
+    readonly maxArticles: 200;
+    readonly titleChars: 70;
+    readonly summaryChars: 200;
+    readonly bodyChars: 60000;
+    readonly maxHeadings: 80;
+    readonly headingIdMinChars: 2;
+    readonly headingIdMaxChars: 96;
+    readonly maxKeywords: 12;
+    readonly keywordChars: 32;
+    readonly maxDocuments: 8;
+    readonly maxRelated: 5;
+    readonly linkLabelChars: 80;
+    readonly externalHrefChars: 2048;
+};
+/** Article identifier: lowercase letters, digits and hyphens, 3–64 characters (spec FR-3). */
+declare const HELP_ARTICLE_ID_PATTERN: RegExp;
+type HelpLinkTarget = 
+/** Another article, optionally at a heading. Resolved like a help link (spec FR-22). */
+{
+    type: 'article';
+    articleId: string;
+    headingId: string | null;
+}
+/** A KEY of the web app's route map — never a literal path (spec FR-5.2). */
+ | {
+    type: 'screen';
+    routeKey: string;
+}
+/** Absolute `https:` URL with no embedded credentials (spec FR-27a). */
+ | {
+    type: 'external';
+    href: string;
+};
+/** Inline content inside a paragraph, list item, heading or table cell. */
+type HelpInline = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'strong';
+    children: HelpInline[];
+} | {
+    type: 'emphasis';
+    children: HelpInline[];
+} | {
+    type: 'code';
+    text: string;
+} | {
+    type: 'link';
+    children: HelpInline[];
+    target: HelpLinkTarget;
+};
+interface HelpListItem {
+    content: HelpInline[];
+    /** Nested blocks — a sub-list, a code sample or a callout inside the item. */
+    children: HelpBlock[];
+}
+interface HelpLinkBlock {
+    kind: 'link';
+    /** Plain text, 1–80 characters, no inline markup. */
+    label: string;
+    target: HelpLinkTarget;
+}
+type HelpBlock = {
+    kind: 'paragraph';
+    content: HelpInline[];
+} | {
+    kind: 'heading';
+    level: 2 | 3 | 4;
+    id: string;
+    content: HelpInline[];
+} | {
+    kind: 'orderedList';
+    items: HelpListItem[];
+} | {
+    kind: 'unorderedList';
+    items: HelpListItem[];
+} | {
+    kind: 'note';
+    tone: HelpNoteTone;
+    title: string | null;
+    blocks: HelpBlock[];
+} | {
+    kind: 'shortcut';
+    keys: string[];
+    label: string;
+} | {
+    kind: 'code';
+    language: string | null;
+    text: string;
+} | HelpLinkBlock | {
+    kind: 'table';
+    header: HelpInline[][];
+    rows: HelpInline[][][];
+};
+/** The body file the generator emits for one article. */
+interface HelpArticleBody {
+    /** Format version of this file; bumped only on an incompatible grammar change. */
+    version: 1;
+    id: string;
+    blocks: HelpBlock[];
+}
+/** Narrowing guard for a section read from an untrusted source. */
+declare function isHelpSection(value: unknown): value is HelpSection;
+/** Narrowing guard for an article identifier read from an untrusted source (a URL segment). */
+declare function isHelpArticleId(value: unknown): value is string;
+
+/**
+ * Shared view — the owner-facing wire contracts behind Settings → Sharing and
+ * the public share-link exchange.
+ *
+ * A Shared view is one Workspace's read-only published face: a live,
+ * revocable projection of its Task board reached by a share link. It holds
+ * WHAT may be read and BY WHICH token, never a copy of the content.
+ *
+ * Pure types plus closed vocabularies, so the API, the web app and any other
+ * client import one definition. Additive-only (this ships in a public package).
+ */
+/** `active` = the link resolves; `paused` = sharing is off but the link is kept. */
+type SharedViewStatus = 'active' | 'paused';
+declare const SHARED_VIEW_STATUSES: readonly SharedViewStatus[];
+declare function isSharedViewStatus(value: unknown): value is SharedViewStatus;
+/** Which sections a Shared view publishes. The board is on by default, knowledge off. */
+interface SharedViewSectionsDto {
+    board: boolean;
+    knowledge: boolean;
+}
+/** How a Shared view answers crawlers. `blocked` is the default. */
+type SharedViewIndexingMode = 'blocked' | 'allowed';
+/** Every number the Shared view contract promises, in one place. */
+declare const SHARED_VIEW_LIMITS: {
+    /** 256 bits of randomness, base64url without padding. */
+    readonly tokenBytes: 32;
+    readonly tokenLength: 43;
+    /** A view session lives this long before the client exchanges the token again. */
+    readonly viewSessionTtlSeconds: number;
+    /** Cards per published column. */
+    readonly columnCardLimit: 50;
+    /** Lines in the published activity strip. */
+    readonly activityLineLimit: 20;
+    /** Labels per published card. */
+    readonly cardLabelLimit: 3;
+    /** Exchanges and reads per token (or per view) per minute. */
+    readonly requestsPerTokenPerMinute: 60;
+    /** Public requests per client per hour. */
+    readonly requestsPerClientPerHour: 600;
+    /** Owner regenerations per Workspace per minute. */
+    readonly regeneratePerMinute: 10;
+    /** A client increments the view count at most once in this window. */
+    readonly viewDedupeWindowSeconds: number;
+    /** The `Retry-After` a throttled public request carries. */
+    readonly retryAfterSeconds: 60;
+    /** The live poll cadence of the published page. */
+    readonly pollIntervalSeconds: 20;
+    /** Knowledge class names a selection may hold. */
+    readonly knowledgeClassLimit: 32;
+};
+/** The one error message every refused share-link request carries. */
+declare const SHARED_VIEW_NOT_ACTIVE = "shared_view_not_active";
+/** The share link, returned only to the Tenant owner. */
+interface SharedViewLinkDto {
+    /** The 43-character share token. The web app builds `/share/<token>` from it. */
+    token: string;
+}
+/**
+ * `GET /api/organizations/:orgId/shared-view` and every owner write.
+ *
+ * Every member of the Workspace may read the settings; only the Tenant owner
+ * receives `link`. `exists: false` means sharing has never been turned on.
+ */
+interface SharedViewSettingsDto {
+    exists: boolean;
+    /** True when the caller is the Tenant owner and may change sharing. */
+    canManage: boolean;
+    status: SharedViewStatus | null;
+    sections: SharedViewSectionsDto;
+    /** Knowledge Base classes selected for publication. Empty publishes nothing. */
+    knowledgeClasses: string[];
+    searchIndexable: boolean;
+    viewCount: number;
+    /** ISO timestamp, or `null` when the link was never opened. */
+    lastViewedAt: string | null;
+    /** ISO timestamp of the last regenerate, or `null` when never regenerated. */
+    tokenRotatedAt: string | null;
+    rotationCount: number;
+    /** ISO timestamp the Shared view was first turned on. */
+    createdAt: string | null;
+    /** Present only for the Tenant owner, and only when the stored token could be read. */
+    link: SharedViewLinkDto | null;
+    /** True for the owner when a stored token exists but could not be decrypted — regenerate to recover. */
+    linkUnreadable: boolean;
+}
+/** `PATCH /api/organizations/:orgId/shared-view` — every field optional, one facet per field. */
+interface UpdateSharedViewDto {
+    status?: SharedViewStatus;
+    sections?: Partial<SharedViewSectionsDto>;
+    knowledgeClasses?: string[];
+    searchIndexable?: boolean;
+}
+/** `POST /api/public/shared-view/sessions` request body. The token never travels in a URL. */
+interface SharedViewSessionRequestDto {
+    token: string;
+}
+/** `POST /api/public/shared-view/sessions` response. */
+interface SharedViewSessionDto {
+    /** Opaque credential presented as `Authorization: Bearer <viewSession>` on every read. */
+    viewSession: string;
+    /** ISO timestamp after which the view session is refused. */
+    expiresAt: string;
+    /** Crawler posture of the resolved view, so the page can render its own robots directive. */
+    searchIndexable: boolean;
+    /** Sections the resolved view publishes. */
+    sections: SharedViewSectionsDto;
+}
+/** Per-class publishable document counts for the knowledge confirm dialog. */
+interface SharedViewKnowledgeClassCountDto {
+    documentClass: string;
+    count: number;
+}
+
+/**
+ * Shared view — the published board: what a link visitor with no account is
+ * allowed to read.
+ *
+ * Every type below is CLOSED: no index signature, no `Record<string, unknown>`
+ * escape hatch, no optional passthrough. A field that is not declared here
+ * cannot be serialised, so adding a field to a Task, an Agent or an activity
+ * record can never leak it onto the published page.
+ *
+ * What is deliberately absent, and must stay absent: ids of any kind, costs,
+ * budgets, token counts, model names, run references, error text, comments,
+ * sub-tasks, the Mission / Work / Idea / Team / Goal a Task is filed against,
+ * repositories, file paths, in-product URLs, and every human's name or email.
+ */
+/** The four published columns — the private Task board's Focus layout, minus Cancelled. */
+type PublishedColumnKey = 'backlog' | 'in_flight' | 'needs_you' | 'done';
+declare const PUBLISHED_COLUMN_KEYS: readonly PublishedColumnKey[];
+/** `p0` (Urgent) … `p4` (Low). */
+type PublishedTaskPriority = 'p0' | 'p1' | 'p2' | 'p3' | 'p4';
+/** The Agent working a card: a display name only. The page draws the avatar from it. */
+interface PublishedAgentRefDto {
+    name: string;
+}
+interface PublishedTaskCardDto {
+    title: string;
+    column: PublishedColumnKey;
+    priority: PublishedTaskPriority;
+    /** At most three labels. */
+    labels: string[];
+    /** ISO timestamp the work last moved. */
+    lastProgressAt: string;
+    /** True when the work has stopped moving (the private board's stall rule). */
+    stale: boolean;
+    agent: PublishedAgentRefDto | null;
+}
+interface PublishedColumnDto {
+    key: PublishedColumnKey;
+    /** Cards in the column, at most fifty, ordered exactly as on the private board. */
+    cards: PublishedTaskCardDto[];
+    /** Cards the column holds beyond the published ones — rendered as `+N more`. */
+    moreCount: number;
+}
+/** `working` = has work in flight or a run going; `paused` = paused by its owner; otherwise `idle`. */
+type PublishedAgentStatus = 'working' | 'idle' | 'paused';
+interface PublishedAgentDto {
+    name: string;
+    status: PublishedAgentStatus;
+    /** Published cards this Agent is working in the In flight column. */
+    inFlightCount: number;
+}
+/** Who an activity line is about. Only an Agent is ever named. */
+type PublishedActorKind = 'agent' | 'person' | 'system';
+interface PublishedActivityLineDto {
+    actorKind: PublishedActorKind;
+    /** The Agent's display name. Always `null` for a person or the system. */
+    actorName: string | null;
+    /** The same narration the Live Feed renders, with the actor param never naming a person. */
+    narration: FeedNarrationDto;
+    /** ISO timestamp. */
+    at: string;
+}
+/** `GET /api/public/shared-view/board` */
+interface PublishedBoardDto {
+    workspaceName: string;
+    sections: SharedViewSectionsDto;
+    columns: PublishedColumnDto[];
+    agents: PublishedAgentDto[];
+    recent: PublishedActivityLineDto[];
+    /** ISO timestamp the projection was computed. */
+    generatedAt: string;
+}
+
+/**
+ * Shared view — the published knowledge library.
+ *
+ * Declared with the rest of the published contract so the shape is settled
+ * once; the knowledge section itself stays off (and its endpoints answer the
+ * not-active response) until it ships. Closed types, like the board's.
+ *
+ * Never published: git history, citations, the retrieval trail, embedding
+ * state, uploads and original source files.
+ */
+interface PublishedDocumentSummaryDto {
+    /** An opaque, per-view document reference — never the stored document id. */
+    ref: string;
+    title: string;
+    documentClass: string;
+    wordCount: number;
+    /** ISO timestamp. */
+    updatedAt: string;
+}
+interface PublishedDocumentDto extends PublishedDocumentSummaryDto {
+    /** The rendered document text. */
+    body: string;
+}
+
+/**
+ * Shared view — the activity kinds the published strip may show.
+ *
+ * CLOSED BY DEFAULT: an activity kind is published only when it is named
+ * here. A newly added kind stays off the published page until somebody adds
+ * it deliberately; the agent-side classification spec fails until every kind
+ * is on this list or on the never-publish list.
+ *
+ * Each entry is safe because its Live Feed narration reads nothing beyond a
+ * Task title (already on a published card) or a status token: no path, no
+ * repository, no Work name, no amount, no error text, no person.
+ */
+declare const PUBLISHABLE_ACTIVITY_ACTIONS: readonly string[];
+declare function isPublishableActivityAction(actionType: unknown): boolean;
+
+export { ACTIVE_SCOPE_API_HEADER, ACTIVE_SCOPE_BROWSER_HEADER, ACTIVE_SCOPE_PERSONAL_SENTINEL, ACTIVE_SCOPE_RESPONSE_SCHEMA, AWESOME_README_IMPORT_MODES, type ActiveScopeResponse, type AnalyzeRepositoryResponseDto, type AwesomeReadmeImportMode, CHANGELOG_CATEGORIES, CHANGELOG_KINDS, CHANGELOG_LIMITS, CHANGELOG_SLUG_PATTERN, type ChangelogCategory, type ChangelogCtaDto, type ChangelogEntryDto, type ChangelogKind, type ChangelogListResponseDto, type ChangelogMarkReadRequestDto, type ChangelogMarkReadResponseDto, type ChangelogSourceEntry, type ChangelogUnreadCountResponseDto, type CheckItemHealthDto, type CheckItemHealthResponseDto, type CheckSlugAvailabilityResponse, type CreateItemsGeneratorDto, type CreateOrganizationRequest, type CreatePluginAllowlistEntryDto, type ExtractItemDetailsDto, GenerateStatusType, type GenerationLogLevel, type GenerationLogSource, GenerationMethod, type GenerationMetrics, type GenerationStepLog, HELP_ARTICLE_ID_PATTERN, HELP_BLOCK_KINDS, HELP_LIMITS, HELP_LINK_TARGET_TYPES, HELP_NOTE_TONES, HELP_SECTIONS, type HelpArticleBody, type HelpBlock, type HelpBlockKind, type HelpInline, type HelpLinkBlock, type HelpLinkTarget, type HelpLinkTargetType, type HelpListItem, type HelpNoteTone, type HelpSection, IMPORT_SOURCE_TYPES, type ImportEnrichmentConfig, type ImportSourceType, type ImportWorkDto, LANE_FAILURE_REASONS, LANE_OUTCOMES, type LaneFailureReason, type LaneOutcome, MILESTONE_STATUSES, type ManifestValidationError, type MilestoneRecord, type MilestoneStatus, ONBOARDING_DEFAULT_STATE, ONBOARDING_DESKTOP_NEXT_STEPS, ONBOARDING_MILESTONES, ONBOARDING_TERMINAL_STATUSES, type OnboardingAiChoice, type OnboardingCard, type OnboardingCardBadge, type OnboardingCatalogResponse, type OnboardingDbChoice, type OnboardingDeployChoice, type OnboardingDesktopChoice, type OnboardingDesktopNextStep, type OnboardingMilestoneKey, type OnboardingPluginCard, type OnboardingProfile, type OnboardingProfileOption, type OnboardingRequestSource, type OnboardingRequestSourceAwesomeReadme, type OnboardingRequestSourceDataRepo, type OnboardingRequestSourceInline, type OnboardingRequestSourceWebSearch, type OnboardingRoleId, type OnboardingSeedAgentSuggestion, type OnboardingSeedOutcome, type OnboardingSeedRequest, type OnboardingSeedResponse, type OnboardingSeedResultEntry, type OnboardingSeedSkillSuggestion, type OnboardingSeedSuggestionsResponse, type OnboardingStatePatchRequest, type OnboardingStateResponse, type OnboardingStatus, type OnboardingStorageChoice, type OnboardingTeamSizeId, type OnboardingWizardStateV2, type OrganizationResponse, PUBLISHABLE_ACTIVITY_ACTIONS, PUBLISHED_COLUMN_KEYS, type PluginAllowlistEntryDto, type PluginAllowlistResponseDto, type PluginCatalogEntry, type PluginCatalogResponse, type PluginInstallRequestDto, type PluginInstallResponseDto, type PluginInstallSource, type PluginInstallState, type PluginInstallStateDto, type ProvidersDto, type PublishedActivityLineDto, type PublishedActorKind, type PublishedAgentDto, type PublishedAgentRefDto, type PublishedAgentStatus, type PublishedBoardDto, type PublishedColumnDto, type PublishedColumnKey, type PublishedDocumentDto, type PublishedDocumentSummaryDto, type PublishedTaskCardDto, type PublishedTaskPriority, ROLE_OPTIONS, ROSTER_BLUEPRINT_SLUGS, ROSTER_LANE_KEYS, ROSTER_MAX_LANES, ROSTER_NAME_MAX, ROSTER_PROVISION_STATES, type RegisterCompanyRequest, type RegisterWorkErrorBody, type RegisterWorkErrorCode, type RegisterWorkRequest, type RegisterWorkResponse, type RegisterWorkStatus, type RelatedRepositories, type RemoveItemDto, type RepoVisibility, type RepositoryRole, type RepositoryTarget, type RosterBlueprintSlug, type RosterLaneKey, type RosterLaneResult, type RosterProvisionRecord, type RosterProvisionState, SHARED_VIEW_LIMITS, SHARED_VIEW_NOT_ACTIVE, SHARED_VIEW_STATUSES, type SharedViewIndexingMode, type SharedViewKnowledgeClassCountDto, type SharedViewLinkDto, type SharedViewSectionsDto, type SharedViewSessionDto, type SharedViewSessionRequestDto, type SharedViewSettingsDto, type SharedViewStatus, type SourceRepository, type SourceValidationSettingsDto, type SubmitItemDto, type SyncEventErrorClass, type SyncEventFailed, type SyncEventKind, type SyncEventPayload, type SyncEventSkipReason, type SyncEventSkipped, type SyncEventSource, type SyncEventSuccess, TEAM_SIZE_OPTIONS, UPGRADE_NOT_AVAILABLE_AFTER_MULTIPLE_ORGS, type UpdateItemDto, type UpdateItemsGeneratorDto, type UpdateOrganizationRequest, type UpdatePluginAllowlistEntryDto, type UpdateSharedViewDto, type UpdateSourceValidationPayload, type UpdateWorkSchedulePayload, type UpgradeFromAccountResponse, WORKSPACE_SEARCH_DEFAULT_PER_KIND, WORKSPACE_SEARCH_KINDS, WORKSPACE_SEARCH_MAX_PER_KIND, WORKSPACE_SEARCH_MAX_QUERY_LENGTH, WORKSPACE_SEARCH_MAX_RECENT, WORKSPACE_SEARCH_MAX_TOTAL, WORKSPACE_SEARCH_MIN_QUERY_LENGTH, type WebhookEvent, type WebhookEventDeployFailed, type WebhookEventManifestChanged, type WebhookEventTerminal, WebsiteRepositoryCreationMethod, type WorkChangelog, type WorkCurrentDeploymentHealthDto, type WorkCurrentHealthDto, type WorkCurrentState, type WorkDeploymentHealthSource, type WorkDeploymentReadiness, type WorkGenerationHistoryEntry, type WorkGenerationHistoryResponse, WorkHistoryActivityType, type WorkHistoryChangeAction, type WorkHistoryChangeEntityType, type WorkHistoryChangeEntry, type WorkLastDeploymentRunDto, type WorkLastGenerationRunDto, type WorkLastRunDto, type WorkScheduleAllowedCadence, WorkScheduleBillingMode, WorkScheduleCadence, type WorkScheduleDto, WorkScheduleStatus, type WorkStatusProjectionDto, type WorksConfigSnapshot, type WorksManifestMetadata, type WorksManifestOutput, type WorksManifestSpec, type WorksManifestV1, type WorkspaceSearchGroup, type WorkspaceSearchHit, type WorkspaceSearchKind, type WorkspaceSearchMatchReason, type WorkspaceSearchResponse, desktopNextStep, isChangelogCategory, isChangelogKind, isHelpArticleId, isHelpSection, isPublishableActivityAction, isSafeInAppPath, isSharedViewStatus, isTerminalOnboardingStatus };