@ever-works/contracts 1.0.0

package/dist/domain/index.d.cts

@@ -0,0 +1,316 @@
+/**
+ * Domain type classification for work content
+ */
+declare enum DomainType {
+    SOFTWARE = "software",
+    ECOMMERCE = "ecommerce",
+    SERVICES = "services",
+    GENERAL = "general"
+}
+/**
+ * Result of domain analysis for a work
+ */
+interface DomainAnalysis {
+    /** The detected domain type */
+    readonly domain_type: DomainType;
+    /** Confidence score from 0.0 to 1.0 */
+    readonly confidence: number;
+    /** The noun used to describe items in this domain (e.g., "tool", "product") */
+    readonly item_noun?: string;
+    /** Expected attributes for items in this domain */
+    readonly expected_attributes?: readonly string[];
+    /** URL patterns that indicate official sources */
+    readonly official_source_patterns?: readonly string[];
+    /** Domains known to be aggregators rather than official sources */
+    readonly aggregator_domains?: readonly string[];
+}
+/**
+ * Web page data retrieved during content extraction
+ */
+interface WebPageData {
+    /** The source URL of the page */
+    readonly source_url: string;
+    /** ISO date string when the content was retrieved */
+    readonly retrieved_at: string;
+    /** Raw content extracted from the page */
+    readonly raw_content: string;
+}
+/**
+ * Relevance assessment for a piece of content
+ */
+interface RelevanceAssessment {
+    /** Whether the content is relevant */
+    readonly relevant: boolean;
+    /** Relevance score from 0.0 to 1.0 */
+    readonly relevance_score: number;
+    /** Human-readable reason for the assessment */
+    readonly reason: string;
+}
+
+/**
+ * Work "kind" vocabulary — the single source of truth shared by the API,
+ * the agent package and the web app.
+ *
+ * This lives in `@ever-works/contracts` rather than in the TypeORM entity
+ * because `apps/web` deliberately does not depend on `@ever-works/agent`;
+ * contracts is the only package both sides import at runtime. The entity
+ * (`packages/agent/src/entities/work.entity.ts`) re-exports from here so
+ * there is exactly one list to extend when a new kind ships.
+ */
+/**
+ * Kinds a user can pick from the chip catalog at creation time.
+ *
+ * `company` is deliberately absent: Company Works are minted only through
+ * the dedicated Register-Company flow (`WorkLifecycleService.createCompanyWork`),
+ * never through the general create path.
+ *
+ * `repo` (chip label "Repository") is the one selectable kind that is NOT a
+ * generated site: it registers an EXISTING code repository — the platform
+ * monorepo, a template repo, a website repo — as a first-class Work so
+ * Tasks, Goals and fleet runs can attach to it (self-build slice D,
+ * EW-766). Its data repository IS the code repository; see
+ * `WORK_KIND_CAPABILITIES.repo`.
+ */
+declare const USER_SELECTABLE_WORK_KINDS: readonly ["website", "landing-page", "blog", "directory", "awesome-repo", "repo"];
+type UserSelectableWorkKind = (typeof USER_SELECTABLE_WORK_KINDS)[number];
+/**
+ * Every kind a persisted `work.kind` may hold.
+ *
+ *   - `default` — the column default. Carried by every Work created before
+ *     the kind-aware create path shipped, which is the overwhelming majority
+ *     of existing rows. It must behave identically to `directory`; see
+ *     `WORK_KIND_CAPABILITIES` for why that invariant is load-bearing.
+ *   - `company` — see above.
+ *   - `campaign` — a go-to-market campaign Work: the artifact home for the
+ *     lead lists, drafts, and reports a go-to-market pipeline produces. Like
+ *     `company` it is minted by a dedicated flow (template activation), not
+ *     by the general create path, so it stays out of the chip catalog.
+ */
+declare const WORK_KINDS: readonly ["website", "landing-page", "blog", "directory", "awesome-repo", "repo", "company", "campaign", "default"];
+type WorkKind = (typeof WORK_KINDS)[number];
+/**
+ * Coerce an arbitrary value into a known `WorkKind`.
+ *
+ * `work.kind` is persisted as `varchar(32)` and modelled as an open string
+ * union so the server can ship a new kind without a coordinated web deploy.
+ * Every consumer must therefore route unknown values through here and get
+ * the safe generic `default` behaviour rather than crashing or silently
+ * mis-rendering.
+ *
+ * `landing` is accepted as an alias for `landing-page`.
+ *
+ * NEVER throws.
+ */
+declare function normalizeWorkKind(value?: string | null): WorkKind;
+/** True when `value` is a kind the create-path chip catalog offers. */
+declare function isUserSelectableWorkKind(value?: string | null): value is UserSelectableWorkKind;
+/**
+ * True when `value` names the Repository kind (`repo`) — the one kind whose
+ * data repository is a code repository the user already owns rather than
+ * something the platform generated (self-build slice D, EW-766).
+ *
+ * This is deliberately a KIND test rather than a capability test. The
+ * content pipelines (item generation, README regeneration, deployment) are
+ * not capability-gated for any kind today; what is special about a
+ * Repository Work is not "it has no items" — a Company Work has none either
+ * — but that running the directory pipeline against its data repository
+ * would write generated scaffolding into a human's source tree. Callers
+ * that must never touch that repository check this predicate. Accepts the
+ * same loose input as `normalizeWorkKind` and never throws.
+ */
+declare function isRepositoryWorkKind(value?: string | null): boolean;
+
+/**
+ * Goal "kind" vocabulary — the single source of truth shared by the API,
+ * the agent package, the MCP server and the web app.
+ *
+ * Lives in `@ever-works/contracts` for the same reason `work-kind.ts` does:
+ * `apps/web` deliberately does not depend on `@ever-works/agent`, and
+ * contracts is the only package every side imports. The Goal entity
+ * (`packages/agent/src/entities/goal.entity.ts`) re-exports from here so
+ * there is exactly one list to extend when a new kind ships.
+ *
+ *   - `metric`   — the original Goal: reads a number from a metrics-provider
+ *                  plugin on a schedule and completes when the comparator is
+ *                  satisfied against `targetValue`. Every row that predates
+ *                  the `goalKind` column is a metric Goal.
+ *   - `delivery` — "ship feature X across three repos": there is NO metric,
+ *                  no comparator and no target value. The Goal completes on
+ *                  its approved Definition of Done alone — every approved
+ *                  criterion done or waived — and is otherwise driven by the
+ *                  same iteration loop and budget rules as a metric Goal.
+ */
+declare const GOAL_KINDS: readonly ["metric", "delivery"];
+type GoalKind = (typeof GOAL_KINDS)[number];
+/** The column default, and what every pre-existing Goal row reads as. */
+declare const DEFAULT_GOAL_KIND: GoalKind;
+/**
+ * Type guard for WRITE paths. Fail closed: an unknown kind is rejected by
+ * the caller, never coerced — a Goal that is neither metric nor delivery
+ * has no completion rule and must not be persisted.
+ */
+declare function isGoalKind(value: unknown): value is GoalKind;
+/**
+ * Coerce an arbitrary value into a known `GoalKind` for READ paths only.
+ *
+ * `goals.goalKind` is `varchar(16)`, so a row written by a newer server (or
+ * by hand) may carry a value this build does not know. Rendering it as the
+ * generic `metric` behaviour is the safe default for a display surface; a
+ * write path must use {@link isGoalKind} instead.
+ *
+ * NEVER throws.
+ */
+declare function normalizeGoalKind(value?: string | null): GoalKind;
+/** True when `value` names the Delivery kind. Accepts loose input; never throws. */
+declare function isDeliveryGoalKind(value?: string | null): boolean;
+
+/**
+ * Per-Work-kind metric vocabulary.
+ *
+ * A Work's headline statistics depend on what the Work *is*: counting
+ * "Total Items" on a landing page is noise, and counting "Comparisons" on a
+ * blog is meaningless. The kind → metric mapping lives in
+ * `work-capabilities.ts`; this module defines the metrics themselves.
+ *
+ * Definitions are data, not components — `@ever-works/contracts` is
+ * framework-free and must stay importable from the API, the agent package
+ * and the web app alike. The web app maps `WorkMetricDefinition.id` to a
+ * Lucide icon in its own presentation layer.
+ */
+/** Every metric the platform can render on a Work. */
+declare const WORK_METRIC_IDS: readonly ["total-items", "posts", "categories", "tags", "comparisons", "generation-status", "deploy-status", "days-active", "registered-users", "team-members", "agents", "open-tasks", "works-owned", "page-views", "sessions", "conversions"];
+type WorkMetricId = (typeof WORK_METRIC_IDS)[number];
+/**
+ * Where a metric's value comes from. Drives which resolver runs and, when
+ * the value is unavailable, which remediation hint the UI offers.
+ */
+type WorkMetricSource = 
+/** Read straight off the Work row — always available. */
+'work-column'
+/** Computed from Work columns (e.g. days since creation). */
+ | 'derived'
+/** A cheap `COUNT(*)` against a table the platform owns. */
+ | 'db-count'
+/** Supplied by a connected metrics-provider plugin. */
+ | 'provider';
+/** How the raw number should be presented. */
+type WorkMetricFormat = 'integer' | 'percent' | 'duration-days' | 'status';
+/**
+ * Message keys under `dashboard.workDetail.stats`.
+ *
+ * A literal union rather than `string`: the web app looks these up through
+ * next-intl, whose `useTranslations` type-checks keys against the message
+ * catalogue at compile time. Widening this to `string` would silently opt
+ * every tile label out of that check.
+ */
+type WorkMetricLabelKey = 'totalItems' | 'posts' | 'categories' | 'tags' | 'comparisons' | 'generationStatus' | 'deployStatus' | 'daysActive' | 'registeredUsers' | 'teamMembers' | 'agents' | 'openTasks' | 'worksOwned' | 'pageViews' | 'sessions' | 'conversions';
+interface WorkMetricDefinition {
+    readonly id: WorkMetricId;
+    /**
+     * Key under `dashboard.workDetail.stats` in the web app's messages.
+     * Kept as a key rather than a label so contracts stays locale-free.
+     */
+    readonly labelKey: WorkMetricLabelKey;
+    readonly source: WorkMetricSource;
+    readonly format: WorkMetricFormat;
+}
+/**
+ * The resolution state of a single metric.
+ *
+ * Distinguishing these from a plain `0` is the whole point: a Website Work
+ * that has never had analytics connected has *unknown* page views, not zero
+ * page views, and showing "0" reads as a broken product.
+ */
+type WorkMetricState = 'ok'
+/** No analytics/metrics provider is connected to this Work yet. */
+ | 'not_configured'
+/** Metric needs a deployment that does not exist yet. */
+ | 'not_deployed'
+/** Metric needs content generation that has not run yet. */
+ | 'not_generated'
+/** Resolution failed. Never fatal — the tile degrades, the page renders. */
+ | 'error';
+interface WorkMetricValue {
+    readonly id: WorkMetricId;
+    readonly state: WorkMetricState;
+    /** Present only when `state === 'ok'`. */
+    readonly value?: number | string;
+    /**
+     * Change versus the previous comparable period, as a signed ratio
+     * (`0.12` = +12%). Omitted when a comparison is unavailable or would be
+     * expensive.
+     */
+    readonly delta?: number;
+}
+declare const WORK_METRIC_DEFINITIONS: Record<WorkMetricId, WorkMetricDefinition>;
+/** Definition lookup that tolerates an unknown id from a newer server. */
+declare function getWorkMetricDefinition(id: string): WorkMetricDefinition | undefined;
+
+/**
+ * What a Work of a given kind actually has.
+ *
+ * Before this registry, "given `work.kind`, what does this Work support?"
+ * was answered independently in half a dozen places — the create-page chip
+ * catalogs, the website-template resolver, and (mostly) nowhere at all,
+ * because every surface simply assumed a directory. That is why a Landing
+ * Page Work shows an Items tab and a "Total Items: 0" tile.
+ *
+ * Every kind-conditional decision in the platform should route through
+ * `getWorkCapabilities()` rather than testing `kind === 'directory'` inline.
+ */
+interface WorkCapabilities {
+    /**
+     * The Items surface: the Items tab, the `/items` routes, and the
+     * submission / import / export endpoints that operate on them.
+     * `labelKey` lets a kind keep the machinery but rename it — a blog's
+     * items are "posts", a website's are "pages".
+     */
+    readonly items: {
+        readonly enabled: boolean;
+        readonly labelKey: 'items' | 'posts' | 'pages';
+    };
+    /** Categories / tags / collections CRUD and their tiles. */
+    readonly taxonomy: boolean;
+    /** The comparison generator sub-tab and its endpoints. */
+    readonly comparisons: boolean;
+    /** Community pull-request intake settings and processing. */
+    readonly communityPr: boolean;
+    /** Bulk item import / export. */
+    readonly itemImportExport: boolean;
+    /** Source-URL validation for items. */
+    readonly sourceValidation: boolean;
+    /** The Deploy tab and deployment endpoints. */
+    readonly deploy: boolean;
+    /** The knowledge-base workbench. */
+    readonly kb: boolean;
+    /** Ordered metric tiles rendered on the Overview tab. */
+    readonly metrics: readonly WorkMetricId[];
+    /**
+     * Which repositories this kind provisions.
+     *
+     * ⚠️ These keys are the PERSISTED `RepositoryRole` values and must not
+     * be renamed to match the newer UI labels. Mapping, for the avoidable
+     * confusion it saves: `data` → "Data Repository", `work` → the
+     * "{provider} Repository" shown to users, `website` → the "Work
+     * Repository" (the template output, which is not always a website).
+     */
+    readonly repos: {
+        readonly data: boolean;
+        readonly work: boolean;
+        readonly website: boolean;
+    };
+}
+declare const WORK_KIND_CAPABILITIES: Record<WorkKind, WorkCapabilities>;
+/**
+ * Capabilities for a possibly-unknown kind.
+ *
+ * ALWAYS use this instead of indexing `WORK_KIND_CAPABILITIES` directly.
+ * `work.kind` is an open string union — a server can ship a kind this build
+ * has never heard of, and indexing would hand back `undefined` and crash
+ * whatever destructured it.
+ */
+declare function getWorkCapabilities(kind?: string | null): WorkCapabilities;
+/** Convenience predicate — the Items tab / routes are meaningful here. */
+declare function workKindHasItems(kind?: string | null): boolean;
+
+export { DEFAULT_GOAL_KIND, type DomainAnalysis, DomainType, GOAL_KINDS, type GoalKind, type RelevanceAssessment, USER_SELECTABLE_WORK_KINDS, type UserSelectableWorkKind, WORK_KINDS, WORK_KIND_CAPABILITIES, WORK_METRIC_DEFINITIONS, WORK_METRIC_IDS, type WebPageData, type WorkCapabilities, type WorkKind, type WorkMetricDefinition, type WorkMetricFormat, type WorkMetricId, type WorkMetricLabelKey, type WorkMetricSource, type WorkMetricState, type WorkMetricValue, getWorkCapabilities, getWorkMetricDefinition, isDeliveryGoalKind, isGoalKind, isRepositoryWorkKind, isUserSelectableWorkKind, normalizeGoalKind, normalizeWorkKind, workKindHasItems };

package/dist/domain/index.d.ts

@@ -0,0 +1,316 @@
+/**
+ * Domain type classification for work content
+ */
+declare enum DomainType {
+    SOFTWARE = "software",
+    ECOMMERCE = "ecommerce",
+    SERVICES = "services",
+    GENERAL = "general"
+}
+/**
+ * Result of domain analysis for a work
+ */
+interface DomainAnalysis {
+    /** The detected domain type */
+    readonly domain_type: DomainType;
+    /** Confidence score from 0.0 to 1.0 */
+    readonly confidence: number;
+    /** The noun used to describe items in this domain (e.g., "tool", "product") */
+    readonly item_noun?: string;
+    /** Expected attributes for items in this domain */
+    readonly expected_attributes?: readonly string[];
+    /** URL patterns that indicate official sources */
+    readonly official_source_patterns?: readonly string[];
+    /** Domains known to be aggregators rather than official sources */
+    readonly aggregator_domains?: readonly string[];
+}
+/**
+ * Web page data retrieved during content extraction
+ */
+interface WebPageData {
+    /** The source URL of the page */
+    readonly source_url: string;
+    /** ISO date string when the content was retrieved */
+    readonly retrieved_at: string;
+    /** Raw content extracted from the page */
+    readonly raw_content: string;
+}
+/**
+ * Relevance assessment for a piece of content
+ */
+interface RelevanceAssessment {
+    /** Whether the content is relevant */
+    readonly relevant: boolean;
+    /** Relevance score from 0.0 to 1.0 */
+    readonly relevance_score: number;
+    /** Human-readable reason for the assessment */
+    readonly reason: string;
+}
+
+/**
+ * Work "kind" vocabulary — the single source of truth shared by the API,
+ * the agent package and the web app.
+ *
+ * This lives in `@ever-works/contracts` rather than in the TypeORM entity
+ * because `apps/web` deliberately does not depend on `@ever-works/agent`;
+ * contracts is the only package both sides import at runtime. The entity
+ * (`packages/agent/src/entities/work.entity.ts`) re-exports from here so
+ * there is exactly one list to extend when a new kind ships.
+ */
+/**
+ * Kinds a user can pick from the chip catalog at creation time.
+ *
+ * `company` is deliberately absent: Company Works are minted only through
+ * the dedicated Register-Company flow (`WorkLifecycleService.createCompanyWork`),
+ * never through the general create path.
+ *
+ * `repo` (chip label "Repository") is the one selectable kind that is NOT a
+ * generated site: it registers an EXISTING code repository — the platform
+ * monorepo, a template repo, a website repo — as a first-class Work so
+ * Tasks, Goals and fleet runs can attach to it (self-build slice D,
+ * EW-766). Its data repository IS the code repository; see
+ * `WORK_KIND_CAPABILITIES.repo`.
+ */
+declare const USER_SELECTABLE_WORK_KINDS: readonly ["website", "landing-page", "blog", "directory", "awesome-repo", "repo"];
+type UserSelectableWorkKind = (typeof USER_SELECTABLE_WORK_KINDS)[number];
+/**
+ * Every kind a persisted `work.kind` may hold.
+ *
+ *   - `default` — the column default. Carried by every Work created before
+ *     the kind-aware create path shipped, which is the overwhelming majority
+ *     of existing rows. It must behave identically to `directory`; see
+ *     `WORK_KIND_CAPABILITIES` for why that invariant is load-bearing.
+ *   - `company` — see above.
+ *   - `campaign` — a go-to-market campaign Work: the artifact home for the
+ *     lead lists, drafts, and reports a go-to-market pipeline produces. Like
+ *     `company` it is minted by a dedicated flow (template activation), not
+ *     by the general create path, so it stays out of the chip catalog.
+ */
+declare const WORK_KINDS: readonly ["website", "landing-page", "blog", "directory", "awesome-repo", "repo", "company", "campaign", "default"];
+type WorkKind = (typeof WORK_KINDS)[number];
+/**
+ * Coerce an arbitrary value into a known `WorkKind`.
+ *
+ * `work.kind` is persisted as `varchar(32)` and modelled as an open string
+ * union so the server can ship a new kind without a coordinated web deploy.
+ * Every consumer must therefore route unknown values through here and get
+ * the safe generic `default` behaviour rather than crashing or silently
+ * mis-rendering.
+ *
+ * `landing` is accepted as an alias for `landing-page`.
+ *
+ * NEVER throws.
+ */
+declare function normalizeWorkKind(value?: string | null): WorkKind;
+/** True when `value` is a kind the create-path chip catalog offers. */
+declare function isUserSelectableWorkKind(value?: string | null): value is UserSelectableWorkKind;
+/**
+ * True when `value` names the Repository kind (`repo`) — the one kind whose
+ * data repository is a code repository the user already owns rather than
+ * something the platform generated (self-build slice D, EW-766).
+ *
+ * This is deliberately a KIND test rather than a capability test. The
+ * content pipelines (item generation, README regeneration, deployment) are
+ * not capability-gated for any kind today; what is special about a
+ * Repository Work is not "it has no items" — a Company Work has none either
+ * — but that running the directory pipeline against its data repository
+ * would write generated scaffolding into a human's source tree. Callers
+ * that must never touch that repository check this predicate. Accepts the
+ * same loose input as `normalizeWorkKind` and never throws.
+ */
+declare function isRepositoryWorkKind(value?: string | null): boolean;
+
+/**
+ * Goal "kind" vocabulary — the single source of truth shared by the API,
+ * the agent package, the MCP server and the web app.
+ *
+ * Lives in `@ever-works/contracts` for the same reason `work-kind.ts` does:
+ * `apps/web` deliberately does not depend on `@ever-works/agent`, and
+ * contracts is the only package every side imports. The Goal entity
+ * (`packages/agent/src/entities/goal.entity.ts`) re-exports from here so
+ * there is exactly one list to extend when a new kind ships.
+ *
+ *   - `metric`   — the original Goal: reads a number from a metrics-provider
+ *                  plugin on a schedule and completes when the comparator is
+ *                  satisfied against `targetValue`. Every row that predates
+ *                  the `goalKind` column is a metric Goal.
+ *   - `delivery` — "ship feature X across three repos": there is NO metric,
+ *                  no comparator and no target value. The Goal completes on
+ *                  its approved Definition of Done alone — every approved
+ *                  criterion done or waived — and is otherwise driven by the
+ *                  same iteration loop and budget rules as a metric Goal.
+ */
+declare const GOAL_KINDS: readonly ["metric", "delivery"];
+type GoalKind = (typeof GOAL_KINDS)[number];
+/** The column default, and what every pre-existing Goal row reads as. */
+declare const DEFAULT_GOAL_KIND: GoalKind;
+/**
+ * Type guard for WRITE paths. Fail closed: an unknown kind is rejected by
+ * the caller, never coerced — a Goal that is neither metric nor delivery
+ * has no completion rule and must not be persisted.
+ */
+declare function isGoalKind(value: unknown): value is GoalKind;
+/**
+ * Coerce an arbitrary value into a known `GoalKind` for READ paths only.
+ *
+ * `goals.goalKind` is `varchar(16)`, so a row written by a newer server (or
+ * by hand) may carry a value this build does not know. Rendering it as the
+ * generic `metric` behaviour is the safe default for a display surface; a
+ * write path must use {@link isGoalKind} instead.
+ *
+ * NEVER throws.
+ */
+declare function normalizeGoalKind(value?: string | null): GoalKind;
+/** True when `value` names the Delivery kind. Accepts loose input; never throws. */
+declare function isDeliveryGoalKind(value?: string | null): boolean;
+
+/**
+ * Per-Work-kind metric vocabulary.
+ *
+ * A Work's headline statistics depend on what the Work *is*: counting
+ * "Total Items" on a landing page is noise, and counting "Comparisons" on a
+ * blog is meaningless. The kind → metric mapping lives in
+ * `work-capabilities.ts`; this module defines the metrics themselves.
+ *
+ * Definitions are data, not components — `@ever-works/contracts` is
+ * framework-free and must stay importable from the API, the agent package
+ * and the web app alike. The web app maps `WorkMetricDefinition.id` to a
+ * Lucide icon in its own presentation layer.
+ */
+/** Every metric the platform can render on a Work. */
+declare const WORK_METRIC_IDS: readonly ["total-items", "posts", "categories", "tags", "comparisons", "generation-status", "deploy-status", "days-active", "registered-users", "team-members", "agents", "open-tasks", "works-owned", "page-views", "sessions", "conversions"];
+type WorkMetricId = (typeof WORK_METRIC_IDS)[number];
+/**
+ * Where a metric's value comes from. Drives which resolver runs and, when
+ * the value is unavailable, which remediation hint the UI offers.
+ */
+type WorkMetricSource = 
+/** Read straight off the Work row — always available. */
+'work-column'
+/** Computed from Work columns (e.g. days since creation). */
+ | 'derived'
+/** A cheap `COUNT(*)` against a table the platform owns. */
+ | 'db-count'
+/** Supplied by a connected metrics-provider plugin. */
+ | 'provider';
+/** How the raw number should be presented. */
+type WorkMetricFormat = 'integer' | 'percent' | 'duration-days' | 'status';
+/**
+ * Message keys under `dashboard.workDetail.stats`.
+ *
+ * A literal union rather than `string`: the web app looks these up through
+ * next-intl, whose `useTranslations` type-checks keys against the message
+ * catalogue at compile time. Widening this to `string` would silently opt
+ * every tile label out of that check.
+ */
+type WorkMetricLabelKey = 'totalItems' | 'posts' | 'categories' | 'tags' | 'comparisons' | 'generationStatus' | 'deployStatus' | 'daysActive' | 'registeredUsers' | 'teamMembers' | 'agents' | 'openTasks' | 'worksOwned' | 'pageViews' | 'sessions' | 'conversions';
+interface WorkMetricDefinition {
+    readonly id: WorkMetricId;
+    /**
+     * Key under `dashboard.workDetail.stats` in the web app's messages.
+     * Kept as a key rather than a label so contracts stays locale-free.
+     */
+    readonly labelKey: WorkMetricLabelKey;
+    readonly source: WorkMetricSource;
+    readonly format: WorkMetricFormat;
+}
+/**
+ * The resolution state of a single metric.
+ *
+ * Distinguishing these from a plain `0` is the whole point: a Website Work
+ * that has never had analytics connected has *unknown* page views, not zero
+ * page views, and showing "0" reads as a broken product.
+ */
+type WorkMetricState = 'ok'
+/** No analytics/metrics provider is connected to this Work yet. */
+ | 'not_configured'
+/** Metric needs a deployment that does not exist yet. */
+ | 'not_deployed'
+/** Metric needs content generation that has not run yet. */
+ | 'not_generated'
+/** Resolution failed. Never fatal — the tile degrades, the page renders. */
+ | 'error';
+interface WorkMetricValue {
+    readonly id: WorkMetricId;
+    readonly state: WorkMetricState;
+    /** Present only when `state === 'ok'`. */
+    readonly value?: number | string;
+    /**
+     * Change versus the previous comparable period, as a signed ratio
+     * (`0.12` = +12%). Omitted when a comparison is unavailable or would be
+     * expensive.
+     */
+    readonly delta?: number;
+}
+declare const WORK_METRIC_DEFINITIONS: Record<WorkMetricId, WorkMetricDefinition>;
+/** Definition lookup that tolerates an unknown id from a newer server. */
+declare function getWorkMetricDefinition(id: string): WorkMetricDefinition | undefined;
+
+/**
+ * What a Work of a given kind actually has.
+ *
+ * Before this registry, "given `work.kind`, what does this Work support?"
+ * was answered independently in half a dozen places — the create-page chip
+ * catalogs, the website-template resolver, and (mostly) nowhere at all,
+ * because every surface simply assumed a directory. That is why a Landing
+ * Page Work shows an Items tab and a "Total Items: 0" tile.
+ *
+ * Every kind-conditional decision in the platform should route through
+ * `getWorkCapabilities()` rather than testing `kind === 'directory'` inline.
+ */
+interface WorkCapabilities {
+    /**
+     * The Items surface: the Items tab, the `/items` routes, and the
+     * submission / import / export endpoints that operate on them.
+     * `labelKey` lets a kind keep the machinery but rename it — a blog's
+     * items are "posts", a website's are "pages".
+     */
+    readonly items: {
+        readonly enabled: boolean;
+        readonly labelKey: 'items' | 'posts' | 'pages';
+    };
+    /** Categories / tags / collections CRUD and their tiles. */
+    readonly taxonomy: boolean;
+    /** The comparison generator sub-tab and its endpoints. */
+    readonly comparisons: boolean;
+    /** Community pull-request intake settings and processing. */
+    readonly communityPr: boolean;
+    /** Bulk item import / export. */
+    readonly itemImportExport: boolean;
+    /** Source-URL validation for items. */
+    readonly sourceValidation: boolean;
+    /** The Deploy tab and deployment endpoints. */
+    readonly deploy: boolean;
+    /** The knowledge-base workbench. */
+    readonly kb: boolean;
+    /** Ordered metric tiles rendered on the Overview tab. */
+    readonly metrics: readonly WorkMetricId[];
+    /**
+     * Which repositories this kind provisions.
+     *
+     * ⚠️ These keys are the PERSISTED `RepositoryRole` values and must not
+     * be renamed to match the newer UI labels. Mapping, for the avoidable
+     * confusion it saves: `data` → "Data Repository", `work` → the
+     * "{provider} Repository" shown to users, `website` → the "Work
+     * Repository" (the template output, which is not always a website).
+     */
+    readonly repos: {
+        readonly data: boolean;
+        readonly work: boolean;
+        readonly website: boolean;
+    };
+}
+declare const WORK_KIND_CAPABILITIES: Record<WorkKind, WorkCapabilities>;
+/**
+ * Capabilities for a possibly-unknown kind.
+ *
+ * ALWAYS use this instead of indexing `WORK_KIND_CAPABILITIES` directly.
+ * `work.kind` is an open string union — a server can ship a kind this build
+ * has never heard of, and indexing would hand back `undefined` and crash
+ * whatever destructured it.
+ */
+declare function getWorkCapabilities(kind?: string | null): WorkCapabilities;
+/** Convenience predicate — the Items tab / routes are meaningful here. */
+declare function workKindHasItems(kind?: string | null): boolean;
+
+export { DEFAULT_GOAL_KIND, type DomainAnalysis, DomainType, GOAL_KINDS, type GoalKind, type RelevanceAssessment, USER_SELECTABLE_WORK_KINDS, type UserSelectableWorkKind, WORK_KINDS, WORK_KIND_CAPABILITIES, WORK_METRIC_DEFINITIONS, WORK_METRIC_IDS, type WebPageData, type WorkCapabilities, type WorkKind, type WorkMetricDefinition, type WorkMetricFormat, type WorkMetricId, type WorkMetricLabelKey, type WorkMetricSource, type WorkMetricState, type WorkMetricValue, getWorkCapabilities, getWorkMetricDefinition, isDeliveryGoalKind, isGoalKind, isRepositoryWorkKind, isUserSelectableWorkKind, normalizeGoalKind, normalizeWorkKind, workKindHasItems };