@xemahq/biome-sdk 0.1.1

package/src/builder/lib/contribution-schemas.ts

@@ -0,0 +1,572 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Contribution-kind YAML schemas.
+//
+// Each schema validates ONE YAML file under a biome's content directory.
+// Used by both biome authors (build-time validation) and server-side
+// seeders (boot-time validation). Adding a new contribution kind:
+//   1. Define + export the Zod schema here.
+//   2. Add the directory field to BiomeContentSchema in biome-host-sdk.
+//   3. Add a seeder in llm-registry-api (or the relevant service) that
+//      walks the contribution directory using `walkContent()` and parses
+//      each file with this schema.
+//
+// Schemas are intentionally permissive on `description` / metadata fields
+// (string/optional) so biome authors get IDE help without being blocked
+// on documentation completeness. Behaviour fields are strict — the
+// closed-domain rule applies to enum-shaped values.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+// ── MCP service catalog entry (one per kernel canonical service) ──────
+
+export const ToolGroupSchema = z.enum([
+  'read',
+  'write',
+  'search',
+  'manage',
+  'execute',
+]);
+export type ToolGroup = z.infer<typeof ToolGroupSchema>;
+
+export const McpCatalogToolSchema = z
+  .object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    group: ToolGroupSchema,
+  })
+  .strict();
+
+/**
+ * Server-type discriminator mirroring the `McpServerType` enum in
+ * `mcp-gateway-api/src/gateway/mcp-gateway.types.ts`. Catalog YAMLs
+ * declare this so the gateway's boot reconciler knows whether to seed
+ * the system `OrgMcpServer` row as a Native MCP host (the upstream
+ * service self-hosts `/mcp`) or as an OpenAPI bridge (the gateway
+ * synthesizes `/mcp/<key>` on top of an OpenAPI document).
+ */
+export const McpCatalogServerTypeSchema = z.enum([
+  'native_mcp',
+  'openapi_bridge',
+]);
+export type McpCatalogServerType = z.infer<typeof McpCatalogServerTypeSchema>;
+
+/**
+ * Connection metadata for catalog entries that the gateway boot
+ * reconciler should materialize into a system `OrgMcpServer` row. When
+ * a YAML omits this block the entry is metadata-only (the gateway will
+ * NOT auto-seed a system row).
+ *
+ * `envVar` names the environment variable on the gateway pod whose
+ * value is the base URL of the upstream service (e.g. `MEMORY_API_URL`
+ * → `http://memory-api.xema-prod.svc.cluster.local`). The reconciler
+ * resolves `connectionUrl = process.env[envVar] + path` at boot and
+ * fail-fasts if the env var is missing — by design, since a missing
+ * upstream URL means the corresponding system server cannot be served.
+ */
+export const McpCatalogConnectionSchema = z
+  .object({
+    serverType: McpCatalogServerTypeSchema,
+    envVar: z
+      .string()
+      .min(1)
+      .regex(
+        /^[A-Z][A-Z0-9_]*$/,
+        'envVar must be UPPER_SNAKE_CASE',
+      ),
+    path: z.string().min(1).default('/mcp'),
+  })
+  .strict();
+export type McpCatalogConnection = z.infer<typeof McpCatalogConnectionSchema>;
+
+export const McpCatalogServiceSchema = z
+  .object({
+    key: z
+      .string()
+      .min(1)
+      .regex(/^[a-z][a-z0-9-]*$/, 'service key must be kebab-case'),
+    displayName: z.string().min(1),
+    purpose: z.string().min(1),
+    tools: z.array(McpCatalogToolSchema).min(1),
+    /**
+     * Optional. When present, the mcp-gateway boot reconciler upserts a
+     * system `OrgMcpServer` row using these fields. Catalogs without a
+     * `connection` block are advertised in the catalog API but are NOT
+     * automatically materialized as a system server.
+     */
+    connection: McpCatalogConnectionSchema.optional(),
+  })
+  .strict();
+
+export type McpCatalogService = z.infer<typeof McpCatalogServiceSchema>;
+
+// ── MCP tool profile (one per agent slug) ─────────────────────────────
+
+export const ServiceToolAccessSchema = z.union([
+  z.literal('*'),
+  z.array(ToolGroupSchema),
+  z
+    .object({
+      groups: z.union([z.literal('*'), z.array(ToolGroupSchema)]),
+      allowedTools: z.array(z.string()).optional(),
+      optional: z.boolean().optional(),
+    })
+    .strict(),
+]);
+export type ServiceToolAccess = z.infer<typeof ServiceToolAccessSchema>;
+
+export const ToolProfileSchema = z
+  .object({
+    agentSlug: z
+      .string()
+      .min(1)
+      .regex(/^[a-z][a-z0-9-_]*$/, 'agent slug must be kebab-case'),
+    /** Per-service access. Map of MCP service key → ServiceToolAccess. */
+    access: z.record(z.string(), ServiceToolAccessSchema),
+  })
+  .strict();
+export type ToolProfile = z.infer<typeof ToolProfileSchema>;
+
+// ── Role capability profile (kernel runtime only) ─────────────────────
+
+export const InvocationSurfaceSchema = z.enum([
+  'pipeline-run',
+  'agent-session',
+  'design-system-builder',
+  'gate-review',
+]);
+
+export const WritePolicySchema = z.enum([
+  'read-only',
+  'own-pages-only',
+  'full-write',
+]);
+
+export const RoleCapabilityProfileSchema = z
+  .object({
+    role: z
+      .string()
+      .min(1)
+      .regex(/^[a-z][a-z0-9-]*$/, 'role must be kebab-case'),
+    surface: InvocationSurfaceSchema,
+    writePolicy: WritePolicySchema,
+    mayEditRepos: z.enum(['never', 'when-granted']),
+    mayWriteKnowledgeBase: z.boolean(),
+    allowedXemaTools: z.array(z.string().min(1)),
+  })
+  .strict();
+export type RoleCapabilityProfile = z.infer<
+  typeof RoleCapabilityProfileSchema
+>;
+
+// ── Agent .md frontmatter ─────────────────────────────────────────────
+
+/**
+ * Closed enum of LLM-routing tiers consumed by llm-registry's
+ * model-strategy resolver. Each agent declares the *kind* of model its
+ * work needs; strategy entries map class → modelSlug.
+ *
+ * Distinct from `AgentRunRole` (the permissions/authority concept
+ * declared per workflow job and resolved through `RoleCapabilityProfile`).
+ *
+ * Adding a new class requires platform-side support (strategy seeder +
+ * dispatch logic), so the enum stays narrow.
+ *
+ * ─────────────────────────────────────────────────────────────────────
+ * SOURCE OF TRUTH: `ModelClass` enum in `@xemahq/kernel-contracts/workflow`
+ * (`packages/kernel/workflow-contracts/src/lib/model-ref.ts`).
+ *
+ * This copy is inlined because `biome-builder` publishes to the public
+ * npm registry and cannot depend on a GitHub-Packages-scoped kernel
+ * package — same reason `InvocationSurfaceSchema` and the `ProjectKit*`
+ * schemas above inline their values.
+ *
+ * MUST stay value-identical to the kernel `MODEL_CLASS_VALUES` list. The
+ * parity gate in
+ * `biomes/agent-runtime/api/llm-registry-api/tests/agent-definition/agent-frontmatter-shape.spec.ts`
+ * fails fast if the two drift.
+ * ─────────────────────────────────────────────────────────────────────
+ */
+export const ModelClassSchema = z.enum([
+  'utility',
+  'planning',
+  'creative',
+  'coding',
+  'review',
+]);
+export type ModelClass = z.infer<typeof ModelClassSchema>;
+
+export const AgentFrontmatterSchema = z
+  .object({
+    /** Kebab-case slug — must match the .md file basename. */
+    slug: z
+      .string()
+      .min(1)
+      .regex(/^[a-z][a-z0-9-_]*$/, 'agent slug must be kebab-case')
+      .optional(),
+    /**
+     * Single bio paragraph rendered in the agent profile UI and
+     * embedded in the seeded `description` column. The only display
+     * text on `AgentDefinition`; `title` and `shortBio` were removed
+     * in favour of one canonical field.
+     */
+    description: z.string().min(1),
+    /** OpenCode agent mode (primary, subagent, …). */
+    mode: z.enum(['primary', 'subagent', 'all']).optional(),
+    color: z.string().optional(),
+    temperature: z.number().min(0).max(2).optional(),
+    /** Max agentic iterations. */
+    steps: z.number().int().positive().optional(),
+    /**
+     * Hide this agent from user-facing pickers (talent pool, interactive
+     * session catalog). Internal-only agents (gate reviewers, leaf
+     * subagents) set this true. Stays invocable via `task` and workflow
+     * `agentRef:` — only human discovery surfaces filter on it.
+     */
+    hidden: z.boolean().optional(),
+
+    // ── Required platform metadata ────────────────────────────────────
+    displayName: z.string(),
+    /**
+     * LLM-routing tier. Closed enum (`ModelClass`). Required — the
+     * seeder fail-fasts when omitted.
+     */
+    modelClass: ModelClassSchema,
+
+    // ── Optional platform metadata ────────────────────────────────────
+    /** Skill slugs this agent uses. */
+    skills: z.array(z.string()).optional(),
+    /**
+     * MCP service keys the agent connects to at runtime. Optional —
+     * when omitted, the agent-definition seeder derives the set from
+     * the corresponding `<slug>.tool-profile.yaml` (the keys of its
+     * `access` map). Use this field when an agent has no tool-profile
+     * (e.g. interactive-primary agents) but still needs MCP servers.
+     */
+    mcpServices: z.array(z.string()).optional(),
+
+    // OpenCode tools/permissions blocks. Pass through any nested object.
+    tools: z.unknown().optional(),
+    permission: z.unknown().optional(),
+  })
+  // OpenCode itself parses tools/permission as nested objects. Use passthrough so
+  // unknown nested keys (e.g. permission.bash patterns) survive without strict-mode
+  // failures. Top-level unknown keys still fail through z.object's default behaviour.
+  .passthrough();
+
+export type AgentFrontmatter = z.infer<typeof AgentFrontmatterSchema>;
+
+// ── OpenCode skill SKILL.md frontmatter ───────────────────────────────
+
+/**
+ * Frontmatter shape on `SKILL.md` files inside an
+ * `<biome-root>/<openCodeSkills>/<skill-key>/` directory. The skill
+ * `key` is the directory name; the body of the markdown file is the
+ * skill content rendered into agent prompts.
+ */
+export const SkillFrontmatterSchema = z
+  .object({
+    /** Human-readable display name. */
+    name: z.string().min(1),
+    /** One-line summary used in capability catalogs. */
+    description: z.string().min(1),
+    /** Skill category (free-form short string for grouping). */
+    category: z.string().optional(),
+    /** Phase keys for which this skill is relevant. */
+    phases: z.array(z.string()).optional(),
+    /** Free-form tags for cataloguing. */
+    tags: z.array(z.string()).optional(),
+    /**
+     * Optional surface gate. Closed values mirror the kernel
+     * `SkillSurface` enum: `workflow`, `agent-session`. When omitted, the
+     * skill applies to BOTH surfaces. The always-on skill resolver in
+     * `llm-registry-api` filters its listing by this field against the
+     * requesting surface.
+     */
+    surfaces: z.array(z.enum(['workflow', 'agent-session'])).optional(),
+  })
+  .passthrough();
+export type SkillFrontmatter = z.infer<typeof SkillFrontmatterSchema>;
+
+// ── Project Kit definition (one per <root>/project-kits/*.yaml) ───────
+
+/**
+ * Wire values restated from the kernel `ProjectKit*` enums in
+ * `@xemahq/kernel-contracts/agent-workspace`. They are inlined (not imported)
+ * because `biome-builder` publishes to the public npm registry and must
+ * not depend on a GitHub-Packages-scoped kernel package — the same reason
+ * `InvocationSurfaceSchema` above inlines its values. The kernel enum is the
+ * source of truth; keep these literals value-identical with it.
+ */
+export const ProjectKitKindSchema = z.enum(['npm-dependency', 'shadcn-registry']);
+export const ProjectKitPurposeSchema = z.enum([
+  'component-library',
+  'generic-dependency',
+]);
+
+/**
+ * Registry visibility tier. Mirrors the kernel `RegistryVisibilityTier` enum
+ * in `@xemahq/kernel-contracts/project-kit`; restated as string literals because
+ * biome-builder publishes to the public npm registry and can't depend on a
+ * GitHub-Packages-scoped kernel package.
+ */
+export const RegistryVisibilityTierSchema = z.enum([
+  'system',
+  'system-shareable',
+  'org',
+  'external',
+]);
+
+/**
+ * Wallet-backed auth for a private kit source. `walletName` is resolved at
+ * session start; `tokenEnvVar` names the wallet entry holding the token.
+ */
+const ProjectKitAuthSchema = z
+  .object({
+    walletName: z
+      .string()
+      .regex(
+        /^[a-z][a-z0-9-]{0,62}$/,
+        'walletName must be a kebab-case wallet name',
+      ),
+    tokenEnvVar: z
+      .string()
+      .regex(
+        /^[A-Z][A-Z0-9_]*$/,
+        'tokenEnvVar must be a SCREAMING_SNAKE_CASE env-var name',
+      ),
+  })
+  .strict();
+
+const ProjectKitNpmRegistrySourceSchema = z
+  .object({
+    kind: z.literal('npm-registry'),
+    package: z.string().min(1),
+    versionRange: z.string().min(1),
+    registryUrl: z.string().url().optional(),
+    scope: z
+      .string()
+      .min(1)
+      .regex(/^@[a-z0-9-]+$/, 'scope must be a lowercase npm scope like @acme')
+      .optional(),
+    auth: ProjectKitAuthSchema.optional(),
+  })
+  .strict()
+  .refine((s) => (s.registryUrl ? Boolean(s.scope) : true), {
+    message: 'scope is required when registryUrl is set',
+    path: ['scope'],
+  });
+
+const ProjectKitGitSourceSchema = z
+  .object({
+    kind: z.literal('git'),
+    gitUrl: z.string().url(),
+    ref: z.string().min(1).optional(),
+    packageName: z.string().min(1).optional(),
+    auth: ProjectKitAuthSchema.optional(),
+  })
+  .strict();
+
+
+/** Shadcn style preset — closed set matching upstream's `--style` flag. */
+const ShadcnStyleSchema = z.enum(['default', 'new-york']);
+
+/** Shadcn base color palette — closed set matching upstream's `--base-color`. */
+const ShadcnBaseColorSchema = z.enum([
+  'neutral',
+  'stone',
+  'zinc',
+  'mauve',
+  'olive',
+  'mist',
+  'taupe',
+]);
+
+/** Icon library shadcn components import from. */
+const ShadcnIconLibrarySchema = z.enum(['lucide', 'radix']);
+
+/** One declared custom registry for shadcn's `components.json#registries` block. */
+const ShadcnCustomRegistrySchema = z
+  .object({
+    scope: z
+      .string()
+      .regex(
+        /^@[a-z0-9-]+$/,
+        'shadcn custom-registry scope must be a lowercase npm scope like @acme',
+      ),
+    url: z
+      .string()
+      .url()
+      .refine((u) => u.includes('{name}'), {
+        message:
+          'shadcn custom-registry url must contain {name} substitution token',
+      }),
+    auth: ProjectKitAuthSchema.optional(),
+  })
+  .strict();
+
+const ProjectKitShadcnRegistrySourceSchema = z
+  .object({
+    kind: z.literal('shadcn-registry'),
+    style: ShadcnStyleSchema,
+    baseColor: ShadcnBaseColorSchema,
+    components: z.array(z.string().min(1)).min(1),
+    iconLibrary: ShadcnIconLibrarySchema.optional(),
+    customRegistries: z.array(ShadcnCustomRegistrySchema).optional(),
+    typescript: z.boolean().optional(),
+    rsc: z.boolean().optional(),
+  })
+  .strict();
+
+export const ProjectKitSourceSchema = z.discriminatedUnion('kind', [
+  ProjectKitNpmRegistrySourceSchema,
+  ProjectKitGitSourceSchema,
+  ProjectKitShadcnRegistrySourceSchema,
+]);
+export type ProjectKitSourceYaml = z.infer<typeof ProjectKitSourceSchema>;
+
+/**
+ * One `project-kits/<slug>.yaml` file. A Project Kit is a reusable unit an
+ * interactive session installs into the user's project repo. `compatibleTargets`
+ * / `defaultForTargets` are opaque tech-stack tags — the consuming session type
+ * (webapp-studio) matches them against its own targets; the catalog stays
+ * domain-agnostic.
+ */
+export const ProjectKitDefinitionSchema = z
+  .object({
+    slug: z
+      .string()
+      .min(1)
+      .regex(/^[a-z][a-z0-9-]*$/, 'kit slug must be kebab-case'),
+    displayName: z.string().min(1),
+    description: z.string().optional(),
+    kitKind: ProjectKitKindSchema,
+    purpose: ProjectKitPurposeSchema,
+    /** Visibility scope of this kit definition. */
+    visibilityTier: RegistryVisibilityTierSchema.optional(),
+    /** Tech-stack tags the kit is valid for (at least one). */
+    compatibleTargets: z.array(z.string().min(1)).min(1),
+    /** Tags for which the kit is pre-selected on a new project. Subset of compatibleTargets. */
+    defaultForTargets: z.array(z.string().min(1)).default([]),
+    source: ProjectKitSourceSchema,
+    /** Skill slug mounted so the code-producing agent knows how to use the kit. */
+    enrichmentSkillSlug: z.string().min(1).optional(),
+  })
+  .strict()
+  .refine(
+    (k) => k.defaultForTargets.every((t) => k.compatibleTargets.includes(t)),
+    {
+      message: 'defaultForTargets must be a subset of compatibleTargets',
+      path: ['defaultForTargets'],
+    },
+  );
+export type ProjectKitDefinitionYaml = z.infer<
+  typeof ProjectKitDefinitionSchema
+>;
+
+// ── Workflow phase configuration ──────────────────────────────────────
+//
+// A sub-app biome that defines an ordered, gated delivery pipeline ships
+// ONE `phase-config.json` under its `workflow-config/` directory. It
+// declares the workflow's ordered stages, their hierarchy, and per-stage
+// gate reviewers. The kernel carries no domain phase enum; this is the
+// biome-owned source of truth, loaded at runtime by the platform
+// services that need it (llm-registry-api, opencode-pool-api).
+
+/** lifecycle vs delivery — mirrors `WorkflowStageCategory` in the kernel. */
+export const WorkflowPhaseCategorySchema = z.enum(['lifecycle', 'delivery']);
+export type WorkflowPhaseCategory = z.infer<typeof WorkflowPhaseCategorySchema>;
+
+/** One ordered phase: a free-form key + its engine category. */
+export const WorkflowPhaseSchema = z
+  .object({
+    key: z
+      .string()
+      .min(1)
+      .regex(/^[a-z][a-z0-9_]*$/, 'phase key must be lower_snake_case'),
+    category: WorkflowPhaseCategorySchema,
+  })
+  .strict();
+
+/**
+ * The `workflow-config/phase-config.json` document. Exactly one per
+ * biome that declares a gated phase pipeline.
+ *
+ * Per-phase gate-reviewer policy used to live here as a `gateReviewers`
+ * block (`{ guild, agentId, perspective, scopeRules }`). It was migrated
+ * to first-class Skill bundles under `biomes/<biome>/skills/gate-review/`
+ * so reviewer policy follows the same kernel primitive as every other
+ * agent capability. Workflow YAMLs attach the relevant skill on the
+ * reviewer recipient directly (`target: { agentRef, skills: [...] }`).
+ */
+export const WorkflowPhaseConfigSchema = z
+  .object({
+    schemaVersion: z.string().min(1),
+    /** Ordered phase list — first entry is the entry phase. */
+    phases: z.array(WorkflowPhaseSchema).min(1),
+    /**
+     * Phases that are configurable but run OUTSIDE the sequential
+     * pipeline (e.g. a direct-call analyst agent). Free-form keys.
+     */
+    directAgentPhases: z.array(z.string().min(1)).default([]),
+    /** Sub-phase coordinator agent slug → parent phase key. */
+    subPhaseToParent: z.record(z.string(), z.string().min(1)).default({}),
+    /** Phase key → required review-capability keys. */
+    reviewCapabilities: z
+      .record(z.string(), z.array(z.string().min(1)))
+      .default({}),
+  })
+  .strict()
+  .superRefine((cfg, ctx) => {
+    const phaseKeys = new Set(cfg.phases.map((p) => p.key));
+    // Every review-capability / sub-phase parent must name a declared
+    // phase — fail-fast on a typo'd phase key.
+    for (const key of Object.keys(cfg.reviewCapabilities)) {
+      if (!phaseKeys.has(key)) {
+        ctx.addIssue({
+          code: 'custom',
+          message: `reviewCapabilities references unknown phase "${key}"`,
+          path: ['reviewCapabilities', key],
+        });
+      }
+    }
+    for (const [slug, parent] of Object.entries(cfg.subPhaseToParent)) {
+      if (!phaseKeys.has(parent)) {
+        ctx.addIssue({
+          code: 'custom',
+          message: `subPhaseToParent["${slug}"] references unknown phase "${parent}"`,
+          path: ['subPhaseToParent', slug],
+        });
+      }
+    }
+  });
+export type WorkflowPhaseConfig = z.infer<typeof WorkflowPhaseConfigSchema>;
+export type WorkflowPhase = z.infer<typeof WorkflowPhaseSchema>;
+
+// ── Helper: parse YAML + validate against a contribution schema ───────
+
+export class ContributionParseError extends Error {
+  constructor(
+    public readonly contributionPath: string,
+    public readonly issues: readonly z.core.$ZodIssue[],
+  ) {
+    super(
+      `Invalid contribution file ${contributionPath}: ${issues
+        .map((i) => `[${i.path.join('.')}] ${i.message}`)
+        .join('; ')}`,
+    );
+    this.name = 'ContributionParseError';
+  }
+}
+
+export function parseContribution<T extends z.ZodTypeAny>(
+  schema: T,
+  raw: unknown,
+  contributionPath: string,
+): z.infer<T> {
+  const result = schema.safeParse(raw);
+  if (!result.success) {
+    throw new ContributionParseError(contributionPath, result.error.issues);
+  }
+  return result.data;
+}

package/src/builder/lib/define-biome.ts

@@ -0,0 +1,84 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// `defineBiome` — the in-biome entry point.
+//
+// Today (Epoch A) this is a thin marker that wraps imperative install
+// logic (e.g. registering pipeline agents into opencode-client's
+// agentRegistry). As more registries land in Epochs B–C, this helper
+// absorbs auto-install logic so a content-only biome does not need to
+// write any imperative code — the manifest's content directories are
+// enough.
+//
+// Biome install functions all share the same shape:
+//   `(ctx: BiomeInstallContext) => void | Promise<void>`
+//
+// `ctx` is opaque on purpose: each kernel registry passes its own context
+// when it loads the biome. Biome authors do not construct it.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { BiomeManifest } from '../../host';
+
+/**
+ * Loosely-typed context. Each registry that calls into a biome's
+ * install function passes its own ctx, with extra fields named to match
+ * what the registry needs. Biome authors cast to a more specific
+ * context type matching the registry they are extending. This keeps
+ * @xemahq/biome-builder free of import-time dependencies on every
+ * registry package.
+ */
+export interface BiomeInstallContext {
+  /** Biome manifest (already parsed + validated by biome-host). */
+  readonly manifest: BiomeManifest;
+  /** Absolute path to the biome's package root. */
+  readonly biomeRoot: string;
+  /** Free-form bag of registries — the calling host adds its own fields. */
+  [registryKey: string]: unknown;
+}
+
+export type BiomeInstallFn = (
+  ctx: BiomeInstallContext,
+) => void | Promise<void>;
+
+export interface BiomeDefinition {
+  readonly manifest: BiomeManifest;
+  readonly install: BiomeInstallFn;
+}
+
+export interface DefineBiomeOptions {
+  readonly manifest: BiomeManifest;
+  /**
+   * Imperative install hook. Called once when biome-host (or a kernel
+   * registry) loads the biome. May be omitted entirely for content-only
+   * biomes — the SDK auto-derives registrations from the manifest's
+   * content directories in that case.
+   */
+  readonly install?: BiomeInstallFn;
+}
+
+/**
+ * Defines a biome's runtime registration. Biome authors export the
+ * return value as a named export `install` (or default) from their
+ * `src/index.ts`; biome-host imports the module and invokes
+ * `install(ctx)` at boot.
+ *
+ * Example:
+ *
+ * ```ts
+ * import { defineBiome } from '@xemahq/biome-sdk/builder';
+ * import manifest from '../xema-biome.json' with { type: 'json' };
+ *
+ * export default defineBiome({
+ *   manifest,
+ *   install: async (ctx) => {
+ *     // Imperative bits go here. Most biomes don't need any — the
+ *     // manifest's content directories are the source of truth.
+ *   },
+ * });
+ * ```
+ */
+export function defineBiome(opts: DefineBiomeOptions): BiomeDefinition {
+  const noop: BiomeInstallFn = () => undefined;
+  return {
+    manifest: opts.manifest,
+    install: opts.install ?? noop,
+  };
+}

package/src/builder/lib/define-helpers.ts

@@ -0,0 +1,42 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Typed builders for in-biome imperative contributions.
+//
+// These helpers exist for the cases where a biome author chooses to
+// declare contributions in TS instead of YAML. They are pure pass-through
+// functions whose value is type-checking + IDE autocomplete via the
+// associated Zod schema. Each helper returns the value unchanged so the
+// biome can collect them into arrays for the install function to register.
+//
+// For purely declarative biomes (the common case), use the YAML files
+// under content directories instead — these helpers should be reserved
+// for rare imperative extension points.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import {
+  type AgentFrontmatter,
+  AgentFrontmatterSchema,
+  type McpCatalogService,
+  McpCatalogServiceSchema,
+  type RoleCapabilityProfile,
+  RoleCapabilityProfileSchema,
+  type ToolProfile,
+  ToolProfileSchema,
+} from './contribution-schemas';
+
+export function defineAgent(input: AgentFrontmatter): AgentFrontmatter {
+  return AgentFrontmatterSchema.parse(input);
+}
+
+export function defineToolProfile(input: ToolProfile): ToolProfile {
+  return ToolProfileSchema.parse(input);
+}
+
+export function defineMcpService(input: McpCatalogService): McpCatalogService {
+  return McpCatalogServiceSchema.parse(input);
+}
+
+export function defineRoleCapability(
+  input: RoleCapabilityProfile,
+): RoleCapabilityProfile {
+  return RoleCapabilityProfileSchema.parse(input);
+}