@kernhq/module-quire 0.14.0 → 0.16.0

package/src/client/mock.ts

@@ -24,6 +24,11 @@ import type {
   RecentEntry,
   RowRef,
   Space,
+  Template,
+  TemplateChoice,
+  TemplateKind,
+  TemplateResult,
+  TemplateVariable,
   TransferCounts,
   View,
   ViewConfig,
@@ -1136,6 +1141,91 @@ export function createMockQuireApi() {
     row.finishedAt = new Date().toISOString()
   }
 
+  /**
+   * The five starters, **in English only**.
+   *
+   * The real ones are constants on the server with a five-locale table beside them, resolved against
+   * the reader's own locale — `server/services/templates.ts` explains why they cannot live in this
+   * package's message bundle. This mock has no server and no principal, so it carries the English
+   * names and nothing else: it is the demo interface, and a demo of the picker is a demo of the
+   * shape rather than of the translation. Anything that needs to see a starter in Persian needs a
+   * server.
+   */
+  const STARTER_NAMES: Array<[string, string, string, string]> = [
+    ['meeting-notes', 'users', 'Meeting notes', 'Who was there, what was decided, and who does what next.'],
+    [
+      'decision-record',
+      'flag',
+      'Decision record',
+      'One decision, why it was taken, and what it commits you to.',
+    ],
+    [
+      'requirements',
+      'target',
+      'Requirements',
+      'What a piece of work has to do, and what it deliberately does not.',
+    ],
+    [
+      'retrospective',
+      'refresh-cw',
+      'Retrospective',
+      'What went well, what got in the way, and what to change.',
+    ],
+    ['how-to', 'wrench', 'How-to', 'A task somebody can follow from start to finish.'],
+  ]
+
+  /**
+   * One template somebody in this workspace already saved, so the picker is not five shipped entries
+   * and nothing else — the interesting half of the feature is the one a colleague made.
+   */
+  const templateRows: Template[] = [
+    {
+      id: uid(700),
+      workspaceId: '' as Template['workspaceId'],
+      spaceId: uid(1),
+      kind: 'page',
+      key: null,
+      builtIn: false,
+      name: 'Weekly review',
+      description: 'What moved this week, and what is stuck.',
+      icon: 'calendar-days',
+      doc: {
+        type: 'doc',
+        content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Week {{week}} · {{author}}' }] }],
+      },
+      variables: [
+        {
+          name: 'week',
+          label: 'Which week',
+          type: 'text',
+          options: [],
+          default: null,
+          required: true,
+        },
+      ],
+      createdBy: COLLEAGUE as Template['createdBy'],
+      createdAt: iso(9e6),
+      updatedAt: iso(9e6),
+    },
+  ]
+
+  const templateChoice = (row: Template): TemplateChoice => ({
+    id: row.id,
+    key: row.key,
+    builtIn: row.builtIn,
+    kind: row.kind,
+    spaceId: row.spaceId,
+    name: row.name,
+    description: row.description,
+    icon: row.icon,
+    variables: row.variables,
+    updatedAt: row.updatedAt,
+  })
+
+  /** The same single-pass, text-only substitution the server does — see `services/templates.ts`. */
+  const fill = (text: string, values: Record<string, string>) =>
+    text.replace(/\{\{\s*([a-z][a-z0-9_]*)\s*\}\}/g, (whole, name: string) => values[name] ?? whole)
+
   return {
     spaces: {
       list: async ({ includeArchived = false }: { includeArchived?: boolean } = {}) =>
@@ -1698,6 +1788,190 @@ export function createMockQuireApi() {
       },
     },
 
+    /**
+     * What somebody writes with.
+     *
+     * The starters and the rows come back as one list with the override rule applied, exactly as the
+     * server does it — a row carrying a starter's key stands in that starter's place rather than
+     * appearing beside it, which is the whole shape a picker has to draw.
+     *
+     * `instantiate` makes a real page in the tree. It cannot write a *body*: there is no collab
+     * service behind `dev:mock`, and a page's prose lives there rather than in this list. So the
+     * title is substituted and the page appears where it should, and the body is the one thing a
+     * demo of this feature cannot show.
+     */
+    templates: {
+      list: async ({
+        kind = 'page',
+        spaceId = null,
+      }: {
+        kind?: TemplateKind
+        spaceId?: string | null
+      } = {}) => {
+        const rows = templateRows.filter(
+          (row) => row.kind === kind && (row.spaceId === null || row.spaceId === spaceId),
+        )
+        const byKey = new Map(rows.filter((row) => row.key).map((row) => [row.key as string, row]))
+        const out: TemplateChoice[] = []
+        if (kind === 'page')
+          for (const [key, icon, name, description] of STARTER_NAMES) {
+            const override = byKey.get(key)
+            out.push(
+              override
+                ? templateChoice(override)
+                : {
+                    id: null,
+                    key,
+                    builtIn: true,
+                    kind: 'page',
+                    spaceId: null,
+                    name,
+                    description,
+                    icon,
+                    variables: [],
+                    updatedAt: null,
+                  },
+            )
+          }
+        for (const row of rows)
+          if (!row.key || !STARTER_NAMES.some(([key]) => key === row.key)) out.push(templateChoice(row))
+        return out
+      },
+
+      get: async ({ templateId }: { templateId: string }) => {
+        const row = templateRows.find((t) => t.id === templateId)
+        if (!row) throw notFound('Template')
+        return row
+      },
+
+      createFromPage: async (input: {
+        kind?: TemplateKind
+        sourceId: string
+        spaceId?: string | null
+        name: string
+        description?: string
+        icon?: string | null
+        variables?: TemplateVariable[]
+        key?: string | null
+      }) => {
+        if (input.key && templateRows.some((t) => t.key === input.key))
+          throw Object.assign(new Error('This workspace already has its own version of that template'), {
+            code: 'CONFLICT',
+          })
+        const source = input.kind === 'space' ? null : found(input.sourceId)
+        const row: Template = {
+          id: nextId(),
+          workspaceId: '' as Template['workspaceId'],
+          spaceId: input.kind === 'space' ? null : (input.spaceId ?? null),
+          kind: input.kind ?? 'page',
+          key: input.key ?? null,
+          builtIn: Boolean(input.key),
+          name: input.name,
+          description: input.description ?? '',
+          icon: input.icon ?? null,
+          // No collab service, so there is no body to read — the title stands in for the prose, which
+          // is enough for the picker and honest about what a mock can know.
+          doc:
+            input.kind === 'space'
+              ? { pages: [] }
+              : {
+                  type: 'doc',
+                  content: [{ type: 'paragraph', content: [{ type: 'text', text: source?.title ?? '' }] }],
+                },
+          variables: input.variables ?? [],
+          createdBy: ME as Template['createdBy'],
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        }
+        templateRows.push(row)
+        return row
+      },
+
+      update: async ({ templateId, ...patch }: { templateId: string } & Partial<Template>) => {
+        const row = templateRows.find((t) => t.id === templateId)
+        if (!row) throw notFound('Template')
+        Object.assign(row, patch, { updatedAt: new Date().toISOString() })
+        return row
+      },
+
+      remove: async ({ templateId }: { templateId: string }) => {
+        const at = templateRows.findIndex((t) => t.id === templateId)
+        if (at < 0) throw notFound('Template')
+        templateRows.splice(at, 1)
+        return { ok: true as const }
+      },
+
+      instantiate: async (input: {
+        templateId?: string | null
+        starterKey?: string | null
+        spaceId?: string | null
+        parentId?: string | null
+        afterId?: string | null
+        title?: string
+        key?: string | null
+        name?: string
+        values?: Record<string, string>
+      }): Promise<TemplateResult> => {
+        const row = input.templateId
+          ? templateRows.find((t) => t.id === input.templateId)
+          : templateRows.find((t) => t.key === input.starterKey)
+        const starter = STARTER_NAMES.find(([key]) => key === input.starterKey)
+        if (!row && !starter) throw notFound('Template')
+
+        const values: Record<string, string> = {
+          date: new Date().toLocaleDateString(),
+          time: new Date().toLocaleTimeString(),
+          author: 'You',
+          space: spaces.find((s) => s.id === input.spaceId)?.name ?? '',
+          ...(input.values ?? {}),
+        }
+        for (const variable of row?.variables ?? [])
+          if (variable.required && !values[variable.name])
+            throw Object.assign(new Error(`"${variable.label}" is needed before this can be made`), {
+              code: 'BAD_REQUEST',
+            })
+
+        if (row?.kind === 'space') {
+          if (!input.key || !input.name)
+            throw Object.assign(new Error('A space template needs a name and an address'), {
+              code: 'BAD_REQUEST',
+            })
+          const space: Space = {
+            id: nextId(),
+            workspaceId: '' as Space['workspaceId'],
+            key: input.key,
+            name: fill(input.name, values),
+            description: '',
+            icon: null,
+            visibility: 'open',
+            homepageId: null,
+            createdBy: ME as Space['createdBy'],
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            archivedAt: null,
+          }
+          spaces.push(space)
+          return { spaceId: space.id, pageId: null, pageCount: 0 }
+        }
+
+        const spaceId = input.spaceId
+        if (!spaceId) throw Object.assign(new Error('A page template needs a space'), { code: 'BAD_REQUEST' })
+        const siblings = pages
+          .filter((p) => p.spaceId === spaceId && p.parentId === (input.parentId ?? null) && !p.deletedAt)
+          .sort((a, b) => (a._order < b._order ? -1 : 1))
+        const title = fill(input.title || row?.name || starter?.[2] || '', values)
+        const created = page(++seq, spaceId, title, `${siblings.at(-1)?._order ?? 'a'}m`, null, {
+          icon: row?.icon ?? starter?.[1] ?? null,
+        })
+        created.id = uid(seq)
+        created.parentId = input.parentId ?? null
+        created.createdAt = new Date().toISOString()
+        created.updatedAt = created.createdAt
+        pages.push(created)
+        return { spaceId, pageId: created.id, pageCount: 1 }
+      },
+    },
+
     publishing: {
       publish: async ({ pageId, label = null }: { pageId: string; label?: string | null }) => {
         const row = found(pageId)

package/src/client/pages/PageView.svelte

@@ -27,6 +27,7 @@ import FavoriteStar from '../components/FavoriteStar.svelte'
 import PageEditor from '../components/PageEditor.svelte'
 import PageLabels from '../components/PageLabels.svelte'
 import PublishDialog from '../components/PublishDialog.svelte'
+import SaveAsTemplateDialog from '../components/SaveAsTemplateDialog.svelte'
 import VersionHistory from '../components/VersionHistory.svelte'
 import { type CoreApi, toPerson } from '../core-api.js'
 import DatabaseView from '../database/DatabaseView.svelte'
@@ -78,6 +79,19 @@ const membersQuery = createQuery(() => ({
   queryFn: () => core.workspaces.members.list({ workspaceId, limit: 200 }),
 }))
 
+/*
+ * The space by name, for the one sentence that needs it: "offered only in Handbook".
+ *
+ * The same query key the sidebar already holds, so this is a cache read rather than a request —
+ * and the key is what the URL carries, which is not a thing to show somebody in a sentence.
+ */
+const spacesQuery = createQuery(() => ({
+  queryKey: quireKeys.spaces(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.spaces.list({ workspaceId, includeArchived: false }),
+}))
+const spaceName = $derived((spacesQuery.data ?? []).find((space) => space.key === spaceKey)?.name ?? spaceKey)
+
 const query = createQuery(() => ({
   queryKey: quireKeys.page(workspaceId, pageId),
   enabled: Boolean(workspaceId && pageId),
@@ -276,6 +290,14 @@ const canPublish = $derived(canQuire('pagePublish'))
  */
 let exportOpen = $state(false)
 
+/**
+ * Saving this page as something to write with again.
+ *
+ * A flag and a menu entry, exactly like the export above: what a template needs to know is the
+ * dialog's business, and it reads the starters and the space list itself when it opens.
+ */
+let templateOpen = $state(false)
+
 const publicationsQuery = createQuery(() => ({
   queryKey: quireKeys.publications(workspaceId, doc?.spaceId ?? ''),
   enabled: canPublish && Boolean(workspaceId && doc?.spaceId),
@@ -621,6 +643,23 @@ async function undoTrash(workspace: string, id: string, spaceId: string, title:
                 },
               ]
             : []),
+          /*
+           * `space.manage`, not `page.edit`, matching what `templates.createFromPage` asks — and the
+           * asymmetry is the point. A template changes what everybody in the space is offered the
+           * next time they make a page, which is the space's furniture rather than this page's
+           * content, exactly as a label is. Somebody who may write here is not thereby somebody who
+           * may add to everybody else's picker.
+           */
+          ...(canQuire('spaceManage')
+            ? [
+                {
+                  id: 'save-template',
+                  label: t('template_menu'),
+                  icon: 'clipboard-list',
+                  onSelect: () => (templateOpen = true),
+                },
+              ]
+            : []),
           {
             id: 'watch',
             label: watching ? t('watch_stop') : t('watch'),
@@ -793,6 +832,17 @@ async function undoTrash(workspace: string, id: string, spaceId: string, title:
     page={{ id: doc.id, title: doc.title }}
   />
 
+  {#if canQuire('spaceManage')}
+    <SaveAsTemplateDialog
+      bind:open={templateOpen}
+      {workspaceId}
+      spaceId={doc.spaceId}
+      {spaceName}
+      pageId={doc.id}
+      pageTitle={doc.title}
+    />
+  {/if}
+
   <!--
     The body says nothing about numbers until it knows them. Naming a count before the tree has
     loaded would be the same silent lie in a smaller size — "it goes to the trash" for a page that

package/src/client/pages/SpacePage.svelte

@@ -2,6 +2,7 @@
 import { Button, EmptyState, navigation, Skeleton, session } from '@kernhq/ui'
 import { createQuery } from '@tanstack/svelte-query'
 import { getQuireApi } from '../api-instance.js'
+import TemplatePicker from '../components/TemplatePicker.svelte'
 import { t } from '../i18n.js'
 import { canQuire } from '../permissions.js'
 import { quireKeys } from '../query.js'
@@ -57,6 +58,16 @@ const firstPageId = $derived(
 )
 
 let creating = $state(false)
+/**
+ * The first page of an empty space is the one page most worth offering a template for — a handbook
+ * that starts as a how-to is a handbook somebody kept writing. The picker still opens on **Blank
+ * page**, so nothing about starting from nothing got slower.
+ */
+let pickerOpen = $state(false)
+
+const open = (pageId: string) =>
+  void navigation.go(`/${workspaceSlug}/quire/${encodeURIComponent(spaceKey)}/${encodeURIComponent(pageId)}`)
+
 async function createFirst() {
   if (!space || creating) return
   creating = true
@@ -70,9 +81,7 @@ async function createFirst() {
       icon: null,
       afterId: null,
     })
-    void navigation.go(
-      `/${workspaceSlug}/quire/${encodeURIComponent(spaceKey)}/${encodeURIComponent(created.id)}`,
-    )
+    open(created.id)
   } finally {
     creating = false
   }
@@ -96,11 +105,18 @@ async function createFirst() {
     <EmptyState icon="file-text" title={t('space_empty')} description={t('space_empty_desc')}>
       {#snippet actions()}
         {#if canQuire('pageCreate')}
-          <Button disabled={creating} onclick={createFirst}>{t('new_page')}</Button>
+          <Button aria-busy={creating} onclick={() => (pickerOpen = true)}>{t('new_page')}</Button>
         {/if}
       {/snippet}
     </EmptyState>
   </div>
+  <TemplatePicker
+    bind:open={pickerOpen}
+    {workspaceId}
+    spaceId={space.id}
+    onBlank={() => void createFirst()}
+    onMade={(result) => result.pageId && open(result.pageId)}
+  />
 {/if}
 
 <style>

package/src/client/query.ts

@@ -54,6 +54,23 @@ export const quireKeys = {
     ['quire', 'publication', workspaceId, spaceId] as const,
   site: (workspaceId: string, slug: string) => ['quire', 'publication', workspaceId, 'site', slug] as const,
 
+  /**
+   * What may be made here.
+   *
+   * `template` is the entity `templates.createFromPage|update|remove` announce, so somebody saving a
+   * page as a template puts it in everybody else's picker without a reload — which matters more here
+   * than for most lists, because the whole point of a template is that a colleague finds it.
+   *
+   * Keyed by space *and* kind: a space-scoped template is offered in one space and not the next, so
+   * one key for the workspace would serve the Handbook's list to Engineering. `spaceId` is null for
+   * the workspace-wide question the "New space" picker asks, which is a different answer and
+   * therefore a different key.
+   */
+  templates: (workspaceId: string, kind: string, spaceId: string | null) =>
+    ['quire', 'template', workspaceId, kind, spaceId ?? 'workspace'] as const,
+  template: (workspaceId: string, templateId: string) =>
+    ['quire', 'template', workspaceId, templateId] as const,
+
   /** the schema — properties and views — which every open tab of a database is drawing */
   database: (workspaceId: string, databaseId: string) =>
     ['quire', 'database', workspaceId, databaseId] as const,

package/src/contract/models.ts

@@ -473,4 +473,195 @@ export const ImportJob = z.object({
 })
 export type ImportJob = z.infer<typeof ImportJob>
 
+// =====================================================================================
+// Templates
+// =====================================================================================
+
+/**
+ * What a template makes.
+ *
+ * `page` — one page; the body is a page doc.
+ * `space` — a whole space; the body is a tree of pages, each with its own body.
+ *
+ * Two rather than one with a "just make the root" flag, because they are made from different places
+ * and answer different questions: a page template is offered on "New page" inside a space that
+ * already exists, and a space template is what somebody reaches for when there is no space yet.
+ */
+export const TemplateKind = z.enum(['page', 'space'])
+export type TemplateKind = z.infer<typeof TemplateKind>
+
+/**
+ * The starters this module ships.
+ *
+ * **They are constants in the module, not rows in a customer's database**, and the key is what a
+ * constant has instead of an id. `migrations/0011_templates.sql` argues the choice at length; the
+ * short of it is that a migration runs once per *database* and has no workspace to seed into, that a
+ * seeded row is frozen at the release that wrote it, and that a row holds one language in a product
+ * that ships five.
+ *
+ * A workspace edits a starter by **overriding** it: a `Template` row carrying one of these keys takes
+ * that starter's place in the picker rather than sitting beside it, so the first edit writes one row,
+ * a workspace that never touches them has none, and resetting is deleting the row.
+ *
+ * `Template.key` is deliberately **not** this enum — see the comment there.
+ */
+export const TemplateStarterKey = z.enum([
+  'meeting-notes',
+  'decision-record',
+  'requirements',
+  'retrospective',
+  'how-to',
+])
+export type TemplateStarterKey = z.infer<typeof TemplateStarterKey>
+export const TEMPLATE_STARTER_KEYS = TemplateStarterKey.options
+
+/**
+ * What a variable's type decides, which is **the control somebody is shown and not the storage**.
+ *
+ * Every filled value is substituted into prose as text, whatever the type: `{{sprint}}` in a heading
+ * becomes characters in a heading. The type is what turns "type the date" into a date picker and
+ * "type one of these four" into a menu — the difference between a form somebody fills correctly and
+ * one they fill approximately.
+ */
+export const TemplateVariableType = z.enum(['text', 'number', 'date', 'select', 'user'])
+export type TemplateVariableType = z.infer<typeof TemplateVariableType>
+
+/**
+ * The names a template author may not take, because the module already fills them.
+ *
+ * `date` and `author` are the two the plan names. The other three are reserved now rather than
+ * later, and that is the whole reason the list is longer than it needs to be today: adding
+ * `{{time}}` in a future release would silently change what an existing template renders if some
+ * author had already declared a variable of that name. Reserving a name costs an author one
+ * synonym; taking one back costs somebody a document that used to be right.
+ */
+export const TEMPLATE_BUILT_IN_VARIABLES = ['date', 'time', 'author', 'space', 'workspace'] as const
+
+/**
+ * What appears between the braces.
+ *
+ * ASCII, lowercase, no spaces — the same shape as `Space.key` and for the same reason: this string
+ * is matched against the body, so `{{Sprint}}` and `{{sprint}}` being two variables is exactly the
+ * near-duplicate that `labels_ws_space_name_uq` refuses next door. An author's own language belongs
+ * in `label`, which is the half a person actually reads.
+ */
+export const TemplateVariableName = z
+  .string()
+  .min(1)
+  .max(40)
+  .regex(/^[a-z][a-z0-9_]*$/, 'lowercase letters, digits and underscores, starting with a letter')
+  .refine(
+    (name) => !(TEMPLATE_BUILT_IN_VARIABLES as readonly string[]).includes(name),
+    'that name is filled by the module itself',
+  )
+
+/**
+ * One thing somebody is asked before the page is made.
+ *
+ * Every field but `name`, `label` and `type` defaults, so a variable written by an older client
+ * still parses. Note what that does to the *output* type: it makes them required, so anything
+ * constructing a variable supplies all six — which is the point, and the reason a widened contract
+ * is additive for parsing and breaking for constructing.
+ */
+export const TemplateVariable = z.object({
+  name: TemplateVariableName,
+  /** what the person filling it in reads; their own language goes here, not in `name` */
+  label: z.string().min(1).max(120),
+  type: TemplateVariableType,
+  /** the menu, for `select`; empty for every other type */
+  options: z.array(z.string().min(1).max(120)).max(50).default([]),
+  /** what the field starts with — text whatever the type, because substitution is textual */
+  default: z.string().max(2000).nullable().default(null),
+  /** whether the page can be made without it */
+  required: z.boolean().default(false),
+})
+export type TemplateVariable = z.infer<typeof TemplateVariable>
+
+/**
+ * One page of a space template, and everything under it.
+ *
+ * Recursive because a space is a tree and flattening it into a list with parent pointers would mean
+ * inventing local ids that exist only inside the column — an identifier nothing outside this
+ * document ever resolves. The depth is bounded by the space it was made from.
+ *
+ * The type is written out and the schema annotated with it, rather than left to inference, because
+ * a self-referencing `const` has no type TypeScript can name on its own and the package emits
+ * declarations.
+ */
+export type TemplateSpaceNode = {
+  title: string
+  icon: string | null
+  doc: Record<string, unknown>
+  children: TemplateSpaceNode[]
+}
+export const TemplateSpaceNode: z.ZodType<TemplateSpaceNode, TemplateSpaceNode> = z.lazy(() =>
+  z.object({
+    title: z.string().max(300),
+    icon: z.string().max(64).nullable(),
+    /** the page's body, with the same `{{variables}}` in it as any other */
+    doc: RichDoc,
+    children: z.array(TemplateSpaceNode),
+  }),
+)
+
+/**
+ * The body of a `space` template: the tree, under one key.
+ *
+ * An object rather than a bare array so that `Template.doc` is a JSON object for both kinds — the
+ * column defaults to `'{}'`, and a default that is the wrong *type* for half the rows is a default
+ * that lies. It also means the two bodies are told apart by their keys rather than by `typeof`.
+ */
+export const TemplateSpaceBody = z.object({ pages: z.array(TemplateSpaceNode) })
+export type TemplateSpaceBody = z.infer<typeof TemplateSpaceBody>
+
+/**
+ * A page, or a whole space, saved so it can be made again.
+ *
+ * `doc` is left opaque here for the reason `RichDoc` is: this file is not what knows the shape of a
+ * document. It is a page doc when `kind` is `page` and a `TemplateSpaceBody` when `kind` is `space`,
+ * and the server parses the second with the schema above.
+ *
+ * A shipped starter is not one of these — it has no id, no workspace and no timestamps, because it
+ * is a constant. What the picker returns is the starters and these together, with a row carrying a
+ * starter's `key` standing in for that starter.
+ */
+export const Template = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  /** null is workspace-wide; a space id scopes it to one space. Always null when `kind` is `space`. */
+  spaceId: Id.nullable(),
+  kind: TemplateKind,
+  /**
+   * The starter this row replaces, or null for somebody's own template.
+   *
+   * `z.string()` and **not** `TemplateStarterKey`, deliberately. This is stored data: a release that
+   * stopped shipping a starter would turn every override of it into a parse failure, which is a
+   * picker that throws rather than a picker missing one entry. A key naming a starter that no longer
+   * exists is an ordinary custom template, and the read side treats it as one.
+   */
+  key: z.string().min(1).max(64).nullable(),
+  /** true exactly when `key` is set — the database holds the pair to that with a check constraint */
+  builtIn: z.boolean(),
+  name: z.string().min(1).max(120),
+  description: z.string().max(2000),
+  /** a Lucide icon name, or an emoji */
+  icon: z.string().max(64).nullable(),
+  doc: RichDoc,
+  variables: z.array(TemplateVariable),
+  createdBy: UserId.nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+})
+export type Template = z.infer<typeof Template>
+
+/**
+ * A template without its body.
+ *
+ * This exists so that opening a picker does not download every template's prose to draw a list of
+ * names — thirty page docs to render thirty rows, of which one is ever used. The body is fetched
+ * when a template is chosen.
+ */
+export const TemplateSummary = Template.omit({ doc: true })
+export type TemplateSummary = z.infer<typeof TemplateSummary>
+
 export const Ok = z.object({ ok: z.literal(true) })