@kelpie/server 0.12.0 → 0.13.0

package/src/modules/sample-data/service.ts

@@ -1,28 +1,31 @@
-import { and, count, eq, inArray } from 'drizzle-orm'
+import { and, eq, inArray } from 'drizzle-orm'
 
 import { toEventActor } from '../../lib/actor.ts'
+import { UNIQUE_VIOLATION, postgresErrorCode } from '../../lib/database.ts'
 import type { Database } from '../../lib/database.ts'
 import { AppError } from '../../lib/errors.ts'
 import type { IdFactory } from '../../lib/ids.ts'
+import type { EntitlementRegistry } from '../../runtime/entitlements.ts'
+import { moduleCapabilityName } from '../../runtime/moduleConfig.ts'
 import type { TransactionScope } from '../../runtime/transaction.ts'
 import type { Actor } from '../auth/actor.ts'
 import { requireWorkspaceId } from '../auth/actor.ts'
 import * as authRepository from '../auth/repository.ts'
 import { companies } from '../companies/schema.ts'
 import { deals } from '../deals/schema.ts'
-import { candidates, roles } from '../hiring/schema.ts'
-import { notes } from '../notes/schema.ts'
 import { enquiries } from '../enquiries/schema.ts'
+import { attendances, eventAssociations, events } from '../events/schema.ts'
+import { candidates, roles } from '../hiring/schema.ts'
 import { opportunities } from '../opportunities/schema.ts'
 import { partnerships } from '../partnerships/schema.ts'
 import { people, personLinks } from '../people/schema.ts'
+import { notes } from '../notes/schema.ts'
 import { pipelineStages } from '../pipelines/schema.ts'
 import { planItems } from '../plans/schema.ts'
 import { positions } from '../positions/schema.ts'
 import { raises } from '../raises/schema.ts'
 import { parseMemberRole, roleAllows } from '../workspace/roles.ts'
 import { SAMPLE_DATA_FIXTURE } from './fixture.ts'
-import type { Fixture } from './fixture.ts'
 
 /**
  * Installs the sample workspace, in one transaction.
@@ -30,9 +33,13 @@ import type { Fixture } from './fixture.ts'
  * The whole seed is one write. A failure part-way through rolls the whole
  * thing back, so a workspace never ends up with half of it.
  *
- * Idempotent by refusal: a workspace that already holds any companies or
- * people gets a 409. Installing twice would double the fixture, which is not
- * what an "install once" button says.
+ * Existing companies and people stay. The fixture is inserted next to them.
+ * A second install of the same fixture still fails: people emails and company
+ * domains are unique per workspace, and that unique violation becomes a 409.
+ *
+ * A workspace that has switched a toggleable module off (deals, opportunities,
+ * raises, partnerships, events) does not get fixture rows for that module.
+ * Companies, people, hiring, and enquiries still install.
  */
 
 export interface SampleDataDependencies {
@@ -40,6 +47,7 @@ export interface SampleDataDependencies {
   readonly transaction: TransactionScope
   readonly createId: IdFactory
   readonly now: () => Date
+  readonly entitlements: EntitlementRegistry
 }
 
 export interface SampleDataCounts {
@@ -55,6 +63,8 @@ export interface SampleDataCounts {
   readonly enquiries: number
   readonly roles: number
   readonly candidates: number
+  readonly events: number
+  readonly attendances: number
 }
 
 export interface SampleDataService {
@@ -97,6 +107,15 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
     }
   }
 
+  async function moduleIsOn(workspaceId: string, moduleId: string): Promise<boolean> {
+    const entitlement = await dependencies.entitlements.check(
+      workspaceId,
+      moduleCapabilityName(moduleId),
+    )
+
+    return entitlement.kind === 'flag' ? entitlement.granted : true
+  }
+
   return {
     async install(actor, workspaceId) {
       // The path parameter must match the actor's workspace, and it must be an
@@ -106,26 +125,15 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
       await requireAdmin(actor, workspaceId)
 
       const fixture = SAMPLE_DATA_FIXTURE
-
-      return dependencies.transaction(
-        async ({ tx }) => {
-          const [companiesTally] = await tx
-            .select({ value: count() })
-            .from(companies)
-            .where(eq(companies.workspaceId, workspaceId))
-
-          const [peopleTally] = await tx
-            .select({ value: count() })
-            .from(people)
-            .where(eq(people.workspaceId, workspaceId))
-
-          const alreadyHasData =
-            (companiesTally?.value ?? 0) > 0 || (peopleTally?.value ?? 0) > 0
-
-          if (alreadyHasData) {
-            throw AppError.conflict('This workspace already has CRM data')
-          }
-
+      const includeDeals = await moduleIsOn(workspaceId, 'deals')
+      const includeOpportunities = await moduleIsOn(workspaceId, 'opportunities')
+      const includeRaises = await moduleIsOn(workspaceId, 'raises')
+      const includePartnerships = await moduleIsOn(workspaceId, 'partnerships')
+      const includeEvents = await moduleIsOn(workspaceId, 'events')
+
+      try {
+        return await dependencies.transaction(
+          async ({ tx }) => {
           // Every stage this workspace carries, grouped by kind so a deal, an
           // opportunity, a raise and a partnership all resolve their fixture
           // stage slugs against the same read.
@@ -165,6 +173,10 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
           const enquiryIds = new Map<string, string>()
           const roleIds = new Map<string, string>()
           const candidateIds = new Map<string, string>()
+          let planItemCount = 0
+          let notesWritten = 0
+          let eventCount = 0
+          let attendanceCount = 0
 
           for (const record of fixture.companies) {
             const id = dependencies.createId('company')
@@ -179,8 +191,7 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
               description: record.description,
               stage: record.stage,
               sizeBand: record.sizeBand,
-              hq: record.hq,
-              website: record.website,
+              addresses: [...record.addresses],
               accountType: record.accountType,
               icpFit: record.icpFit,
               techStack: [...record.techStack],
@@ -202,7 +213,7 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
               firstName: record.firstName,
               lastName: record.lastName,
               email: record.email,
-              location: record.location,
+              addresses: [...record.addresses],
               preferredChannel: record.preferredChannel,
               influence: record.influence,
               relationship: record.relationship,
@@ -234,6 +245,7 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
             })
           }
 
+          if (includeDeals) {
           for (const record of fixture.deals) {
             const stageId = stageIdByKindAndSlug.get(stageLookupKey('deal', record.stageSlug))
             const companyId = companyIds.get(record.companyKey)
@@ -289,7 +301,9 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
               })
             }
           }
+          }
 
+          if (includeOpportunities) {
           for (const record of fixture.opportunities) {
             const stageId = stageIdByKindAndSlug.get(
               stageLookupKey('opportunity', record.stageSlug),
@@ -327,7 +341,9 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
               updatedAt: now,
             })
           }
+          }
 
+          if (includeRaises) {
           for (const record of fixture.raises) {
             const stageId = stageIdByKindAndSlug.get(stageLookupKey('raise', record.stageSlug))
             const companyId = companyIds.get(record.companyKey)
@@ -381,7 +397,9 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
               })
             }
           }
+          }
 
+          if (includePartnerships) {
           for (const record of fixture.partnerships) {
             const stageId = stageIdByKindAndSlug.get(
               stageLookupKey('partnership', record.stageSlug),
@@ -437,6 +455,7 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
               })
             }
           }
+          }
 
           for (const record of fixture.enquiries) {
             const stageId = stageIdByKindAndSlug.get(
@@ -552,7 +571,81 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
             })
           }
 
+          if (includeEvents) {
+          for (const record of fixture.events) {
+            const startsAt = new Date(now.getTime() + record.startOffsetHours * 60 * 60 * 1000)
+            const endsAt = new Date(startsAt.getTime() + record.durationHours * 60 * 60 * 1000)
+            const id = dependencies.createId('crmEvent')
+            eventCount += 1
+
+            await tx.insert(events).values({
+              id,
+              workspaceId,
+              name: record.name,
+              kind: record.kind,
+              startsAt,
+              endsAt,
+              timezone: record.timezone,
+              location: record.location,
+              meetingUrl: record.meetingUrl,
+              format: record.format,
+              details: record.details,
+              status: record.status,
+              summary: record.summary,
+              tags: [...record.tags],
+              createdAt: now,
+              updatedAt: now,
+            })
+
+            if (record.dealKey !== null && includeDeals) {
+              const dealId = dealIds.get(record.dealKey)
+
+              if (dealId === undefined) {
+                throw new Error(
+                  `Sample event "${record.name}" names unknown deal "${record.dealKey}"`,
+                )
+              }
+
+              await tx.insert(eventAssociations).values({
+                id: dependencies.createId('eventAssociation'),
+                workspaceId,
+                eventId: id,
+                targetType: 'deal',
+                targetId: dealId,
+                createdAt: now,
+              })
+            }
+
+            for (const attendee of record.attendees) {
+              const personId = personIds.get(attendee.personKey)
+
+              if (personId === undefined) {
+                throw new Error(
+                  `Sample event "${record.name}" names unknown person "${attendee.personKey}"`,
+                )
+              }
+
+              attendanceCount += 1
+
+              await tx.insert(attendances).values({
+                id: dependencies.createId('attendance'),
+                workspaceId,
+                eventId: id,
+                personId,
+                status: attendee.status,
+                source: attendee.source,
+                createdAt: now,
+                updatedAt: now,
+              })
+            }
+          }
+          }
+
           for (const record of fixture.plans) {
+            if (!includeDeals) {
+              continue
+            }
+
             const dealId = dealIds.get(record.targetDealKey)
 
             if (dealId === undefined) {
@@ -561,6 +654,8 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
               )
             }
 
+            planItemCount += 1
+
             await tx.insert(planItems).values({
               id: dependencies.createId('planItem'),
               workspaceId,
@@ -587,11 +682,17 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
             })
 
             if (targetId === undefined) {
+              if (isOptionalModuleNoteTarget(record.targetType)) {
+                continue
+              }
+
               throw new Error(
                 `Sample note names unknown ${record.targetType} "${record.targetKey}"`,
               )
             }
 
+            notesWritten += 1
+
             await tx.insert(notes).values({
               id: dependencies.createId('note'),
               workspaceId,
@@ -604,10 +705,34 @@ export function createSampleDataService(dependencies: SampleDataDependencies): S
             })
           }
 
-          return countsFor(fixture)
-        },
-        { workspaceId, actor: toEventActor(actor) },
-      )
+          return {
+            companies: fixture.companies.length,
+            people: fixture.people.length,
+            positions: fixture.positions.length,
+            deals: dealIds.size,
+            planItems: planItemCount,
+            notes: notesWritten,
+            opportunities: opportunityIds.size,
+            raises: raiseIds.size,
+            partnerships: partnershipIds.size,
+            enquiries: enquiryIds.size,
+            roles: roleIds.size,
+            candidates: candidateIds.size,
+            events: eventCount,
+            attendances: attendanceCount,
+          }
+          },
+          { workspaceId, actor: toEventActor(actor) },
+        )
+      } catch (error: unknown) {
+        if (postgresErrorCode(error) === UNIQUE_VIOLATION) {
+          throw AppError.conflict(
+            'A company domain or person email in the sample set already exists in this workspace',
+          )
+        }
+
+        throw error
+      }
     },
   }
 }
@@ -661,19 +786,11 @@ function stageLookupKey(kind: string, slug: string): string {
   return `${kind}::${slug}`
 }
 
-function countsFor(fixture: Fixture): SampleDataCounts {
-  return {
-    companies: fixture.companies.length,
-    people: fixture.people.length,
-    positions: fixture.positions.length,
-    deals: fixture.deals.length,
-    planItems: fixture.plans.length,
-    notes: fixture.notes.length,
-    opportunities: fixture.opportunities.length,
-    raises: fixture.raises.length,
-    partnerships: fixture.partnerships.length,
-    enquiries: fixture.enquiries.length,
-    roles: fixture.roles.length,
-    candidates: fixture.candidates.length,
-  }
+function isOptionalModuleNoteTarget(targetType: string): boolean {
+  return (
+    targetType === 'deal' ||
+    targetType === 'opportunity' ||
+    targetType === 'raise' ||
+    targetType === 'partnership'
+  )
 }

package/src/modules/sample-data/tools.ts

@@ -8,8 +8,9 @@ import type { SampleDataService } from './service.ts'
 /**
  * `sample_data_install`: the MCP mirror of `POST /v1/workspaces/:id/sample-data`.
  *
- * Same admin check, same conflict on a workspace that already has data. The
- * tool takes no arguments: it installs into the actor's own workspace.
+ * Same admin check. Adds the fixture next to existing records. Fails when a
+ * sample email or domain is already in the workspace. The tool takes no
+ * arguments: it installs into the actor's own workspace.
  */
 
 const installArgs = z.strictObject({})
@@ -21,7 +22,7 @@ export function registerSampleDataTools(
   mcp.tool({
     name: 'sample_data_install',
     description:
-      'Populate this workspace with a small sample of companies, people, positions, deals, plans and notes. Refuses if the workspace already has data.',
+      'Populate this workspace with a small sample of companies, people, and other CRM records. Adds them next to existing records. Skips objects for modules that are switched off. Fails if a sample email or domain already exists.',
     inputSchema: installArgs,
     async invoke(_args, actor) {
       const counts = await service.install(actor, requireWorkspaceId(actor))

package/src/modules/search/index.ts

@@ -4,7 +4,7 @@ import { createSearchService } from './service.ts'
 import { registerSearchTools } from './tools.ts'
 
 /**
- * One box across ten collections.
+ * One box across twelve collections.
  *
  * It contributes no tables and calls no `context.schema`. The `search_vector`
  * column each searchable table carries belongs to that table's own module, which
@@ -34,6 +34,7 @@ export function createSearchModule(): KelpieModule {
       'opportunities',
       'partnerships',
       'raises',
+      'events',
       'hiring',
       'plans',
       'decisions',

package/src/modules/search/repository.ts

@@ -18,6 +18,7 @@ import { pipelineStages } from '../pipelines/schema.ts'
 import { planItems } from '../plans/schema.ts'
 import { positions } from '../positions/schema.ts'
 import { raises } from '../raises/schema.ts'
+import { events } from '../events/schema.ts'
 
 /**
  * The reads behind `GET /v1/search`: one query per collection, each against that
@@ -211,7 +212,7 @@ function byPlanItem(
   db: Queryable,
   workspaceId: string,
   query: SQL,
-  targetType: 'deal' | 'opportunity' | 'raise' | 'enquiry',
+  targetType: 'deal' | 'opportunity' | 'raise' | 'enquiry' | 'event',
 ) {
   return db
     .select({ id: planItems.targetId, rank: relatedRank(planItems.searchVector, query).as('rank') })
@@ -370,6 +371,36 @@ export async function searchPartnerships(
   return collect('partnership', rows)
 }
 
+export async function searchEvents(
+  db: Queryable,
+  workspaceId: string,
+  query: SQL,
+  limit: number,
+): Promise<CollectionHits> {
+  const own = db
+    .select({ id: events.id, rank: rank(events.searchVector, query).as('rank') })
+    .from(events)
+    .where(and(eq(events.workspaceId, workspaceId), matches(events.searchVector, query)))
+
+  const hits = unionAll(own, byPlanItem(db, workspaceId, query, 'event')).as('hits')
+
+  const rows = await db
+    .select({
+      id: events.id,
+      title: events.name,
+      subtitle: events.kind,
+      snippetSource: events.summary,
+      total,
+    })
+    .from(hits)
+    .innerJoin(events, eq(events.id, hits.id))
+    .groupBy(events.id)
+    .orderBy(desc(bestRank(hits.rank)), asc(events.id))
+    .limit(limit)
+
+  return collect('event', rows)
+}
+
 export async function searchDecisions(
   db: Queryable,
   workspaceId: string,

package/src/modules/search/service.ts

@@ -11,6 +11,7 @@ import {
   searchDeals,
   searchDecisions,
   searchEnquiries,
+  searchEvents,
   searchHandbookPages,
   searchOpportunities,
   searchPartnerships,
@@ -21,7 +22,7 @@ import {
 import type { CollectionHits } from './repository.ts'
 
 /**
- * One box across ten collections, ranked per collection rather than merged.
+ * One box across twelve collections, ranked per collection rather than merged.
  *
  * A single merged ranking would need `ts_rank` values from different tables to
  * mean the same thing, and they do not: a handbook page is a thousand words and a
@@ -50,7 +51,7 @@ export interface SearchResults {
   readonly limit: number
   /** Across every group. The number a "12 results" heading is built from. */
   readonly total: number
-  /** Always all ten, in `SEARCH_COLLECTIONS` order, empty ones included. */
+  /** Always every collection, in `SEARCH_COLLECTIONS` order, empty ones included. */
   readonly groups: readonly SearchGroup[]
 }
 
@@ -95,6 +96,7 @@ const SEARCHES: Readonly<Record<SearchCollection, CollectionSearch>> = {
   opportunity: searchOpportunities,
   raise: searchRaises,
   partnership: searchPartnerships,
+  event: searchEvents,
   decision: searchDecisions,
 }
 
@@ -136,8 +138,8 @@ export function createSearchService(dependencies: SearchServiceDependencies): Se
       const query = compileQuery(tsQuery)
       const words = searchWords(request.term)
 
-      // Ten independent reads with nothing to share but the compiled query. Run
-      // in sequence they would be ten round trips deep rather than wide.
+      // Independent reads with nothing to share but the compiled query. Run
+      // in sequence they would be round trips deep rather than wide.
       const groups = await Promise.all(
         wanted.map(async (collection) =>
           toGroup(await SEARCHES[collection](dependencies.db, workspaceId, query, limit), words),

package/src/modules/smtp-email/index.ts

@@ -15,6 +15,12 @@ import type { KelpieModule } from '../../runtime/module.ts'
  * or another provider module's name). Reads `EMAIL_FROM` and `SMTP_*` from the
  * environment; missing or malformed values fail boot.
  *
+ * `SMTP_USER` and `SMTP_PASSWORD` are optional and go together. Set both to
+ * authenticate against the relay. Omit both to connect without SMTP AUTH,
+ * which is how local catch-alls (maildev, MailHog, smtp4dev) work. Setting
+ * exactly one fails boot: a half-configured credential pair is a bug, not a
+ * mode.
+ *
  * A commercial email integration (Resend, Postmark) belongs in its own module
  * following the same shape, registered under a different name.
  */
@@ -27,14 +33,26 @@ export const SMTP_EMAIL_PROVIDER = 'smtp'
 
 export type { EmailMessage } from '../../lib/email.ts'
 
-const smtpEmailConfigSchema = z.object({
-  EMAIL_FROM: z.string().min(1),
-  SMTP_HOST: z.string().min(1),
-  SMTP_PORT: z.coerce.number().int().positive().max(65535),
-  SMTP_SECURE: z.enum(['true', 'false']).transform((value) => value === 'true'),
-  SMTP_USER: z.string().min(1),
-  SMTP_PASSWORD: z.string().min(1),
-})
+export const smtpEmailConfigSchema = z
+  .object({
+    EMAIL_FROM: z.string().min(1),
+    SMTP_HOST: z.string().min(1),
+    SMTP_PORT: z.coerce.number().int().positive().max(65535),
+    SMTP_SECURE: z.enum(['true', 'false']).transform((value) => value === 'true'),
+    SMTP_USER: z.string().min(1).optional(),
+    SMTP_PASSWORD: z.string().min(1).optional(),
+  })
+  .superRefine((config, ctx) => {
+    // A half-set pair is a misconfiguration, not a mode. Report both keys so
+    // the operator sees which side of the pair is missing without having to
+    // guess.
+    if ((config.SMTP_USER === undefined) !== (config.SMTP_PASSWORD === undefined)) {
+      const message = 'SMTP_USER and SMTP_PASSWORD must be set together, or both omitted for an unauthenticated relay'
+
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message, path: ['SMTP_USER'] })
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message, path: ['SMTP_PASSWORD'] })
+    }
+  })
 
 export type SmtpEmailConfig = z.infer<typeof smtpEmailConfigSchema>
 
@@ -54,11 +72,13 @@ export interface SmtpTransport {
 }
 
 function createNodemailerTransport(config: SmtpEmailConfig): SmtpTransport {
+  const authenticated = config.SMTP_USER !== undefined && config.SMTP_PASSWORD !== undefined
+
   return nodemailer.createTransport({
     host: config.SMTP_HOST,
     port: config.SMTP_PORT,
     secure: config.SMTP_SECURE,
-    auth: { user: config.SMTP_USER, pass: config.SMTP_PASSWORD },
+    ...(authenticated ? { auth: { user: config.SMTP_USER, pass: config.SMTP_PASSWORD } } : {}),
   })
 }
 
@@ -100,7 +120,9 @@ export interface SmtpEmailModuleOptions {
  * The built-in SMTP module. Registers a factory under `SMTP_EMAIL_PROVIDER`;
  * the factory reads the SMTP environment and builds the nodemailer sender, but
  * only if the assembly's `email.provider` picks this module. Boot fails loudly
- * if any SMTP variable is missing or malformed at that point.
+ * on a missing or malformed required variable, or on a half-set
+ * `SMTP_USER` / `SMTP_PASSWORD` pair. Omitting both credentials is valid and
+ * makes the module connect without SMTP AUTH.
  *
  * The module stays in `coreModules` unconditionally: on any other provider
  * (e.g. `EMAIL_PROVIDER=log`) the factory never runs, so the SMTP environment

package/src/modules/workspace/repository.ts

@@ -6,6 +6,7 @@ import { users } from '../auth/schema.ts'
 import { consentPurposes } from '../consent-purposes/schema.ts'
 import { deals } from '../deals/schema.ts'
 import { decisions } from '../decisions/schema.ts'
+import { events } from '../events/schema.ts'
 import { handbookPages } from '../handbook/schema.ts'
 import { notes } from '../notes/schema.ts'
 import { opportunities } from '../opportunities/schema.ts'
@@ -138,6 +139,7 @@ export async function countMemberReferences(
 ): Promise<readonly { readonly type: string; readonly count: number }[]> {
   const sources = [
     { type: 'deal', table: deals, column: deals.ownerId, workspaceId: deals.workspaceId },
+    { type: 'event', table: events, column: events.ownerId, workspaceId: events.workspaceId },
     { type: 'opportunity', table: opportunities, column: opportunities.ownerId, workspaceId: opportunities.workspaceId },
     { type: 'partnership', table: partnerships, column: partnerships.ownerId, workspaceId: partnerships.workspaceId },
     { type: 'raise', table: raises, column: raises.ownerId, workspaceId: raises.workspaceId },
@@ -366,6 +368,22 @@ export async function deleteInvite(db: Queryable, id: string): Promise<void> {
   await db.delete(invites).where(eq(invites.id, id))
 }
 
+export async function deleteAllHandbookPages(db: Queryable, workspaceId: string): Promise<number> {
+  const deleted = await db
+    .delete(handbookPages)
+    .where(eq(handbookPages.workspaceId, workspaceId))
+    .returning({ id: handbookPages.id })
+
+  return deleted.length
+}
+
+export async function listHandbookPages(
+  db: Queryable,
+  workspaceId: string,
+): Promise<(typeof handbookPages.$inferSelect)[]> {
+  return db.select().from(handbookPages).where(eq(handbookPages.workspaceId, workspaceId))
+}
+
 export async function insertHandbookPages(
   db: Queryable,
   values: readonly (typeof handbookPages.$inferInsert)[],

package/src/modules/workspace/routes.ts

@@ -9,6 +9,7 @@ import { resolveActorFrom } from '../auth/credentials.ts'
 import type { CredentialDependencies } from '../auth/credentials.ts'
 import { INVITABLE_ROLES, MEMBER_ROLES } from './roles.ts'
 import type { InviteView, MemberView, ModuleSettingView, WorkspaceService, WorkspaceView } from './service.ts'
+import { HANDBOOK_TEMPLATE_IDS } from './starters.ts'
 
 /** Wire shapes for `/v1/workspaces`, per `onboarding.md`'s API sketch. */
 
@@ -21,6 +22,11 @@ const createBody = z.object({
   timezone: timezoneSchema,
 })
 
+const seedHandbookBodySchema = z.object({
+  handbook_template: z.enum(HANDBOOK_TEMPLATE_IDS),
+  replace: z.boolean().optional().default(false),
+})
+
 export const updateBody = z
   .object({
     name: z.string().min(1),
@@ -106,6 +112,16 @@ export function mountWorkspaceRoutes(router: Hono, dependencies: WorkspaceRoutes
     return context.json(workspaceResponse(workspace), 201)
   })
 
+  router.post('/workspaces/:id/handbook/seed', async (context) => {
+    const body = await readBody(context, seedHandbookBodySchema)
+    const result = await dependencies.service.seedHandbook(await requireActor(context), context.req.param('id'), {
+      handbookTemplate: body.handbook_template,
+      replace: body.replace,
+    })
+
+    return context.json({ handbook_pages: result.handbookPages }, 201)
+  })
+
   router.get('/workspaces/:id', async (context) => {
     const workspace = await dependencies.service.get(await requireActor(context), context.req.param('id'))