@things-factory/ai-assistant 10.1.6 → 10.1.7

package/client/components/board-ai-chat.ts

@@ -30,7 +30,7 @@ import {
   injectMentionUserIds,
   stripMentionRefids
 } from './markdown.js'
-import { buildChatMutationInput } from './chat-input-builder.js'
+import { buildAssistantChatInput, buildChatMutationInput } from './chat-input-builder.js'
 import { receiveRemoteMessage, reconcileSentLine, remoteMessageToLine } from './chat-echo-dedup.js'
 import './mention-popup.js'
 import {
@@ -57,6 +57,7 @@ import {
  * 뜨지 않는 것이 맞다.
  */
 import { chatDefaults } from './chat-defaults.js'
+import { availableTriggers, type TriggerChip } from './chat-triggers.js'
 
 interface ChatLine {
   role: 'user' | 'assistant' | 'system'
@@ -125,6 +126,30 @@ const BOARD_AI_CHAT_MUTATION = gql`
   }
 `
 
+/*
+ * The neutral door. Selected by `chatEndpoint`, and it asks for fewer fields because there is
+ * less to ask for: no patch, no scene actions, no patch id — this surface has no document.
+ *
+ * `offeredTools` has no counterpart on the board side. It is what the server actually put in
+ * front of the model this turn, so a surface that granted a category and sees it missing knows
+ * the registration never happened, instead of reading a vague answer as a refusal.
+ */
+const ASSISTANT_CHAT_MUTATION = gql`
+  mutation AssistantChat($input: AssistantChatInput!) {
+    assistantChat(input: $input) {
+      reply
+      clientId
+      sessionId
+      userMessageId
+      assistantMessageId
+      toolUsages
+      offeredTools
+      proposals
+      groundingWarnings
+    }
+  }
+`
+
 const CHAT_MESSAGES_QUERY = gql`
   query ChatMessages($sessionId: String!, $limit: Int, $offset: Int) {
     chatMessages(sessionId: $sessionId, limit: $limit, offset: $offset) {
@@ -291,6 +316,31 @@ export class OxBoardAIChat extends LitElement {
   @property({ type: Boolean, attribute: 'board-tools' })
   boardTools = true
 
+  /*
+   * Which server operation this surface talks to. A closed set of two, named after the operations
+   * themselves so a reader can grep either way.
+   *
+   *   boardAIChat    board authoring — lives in @things-factory/board-ai, carries the board model,
+   *                  returns patches and scene actions
+   *   assistantChat  a surface with no document of its own — lives here, runs registered tools only
+   *
+   * Default stays `boardAIChat`: every existing consumer is a board surface, and a default that
+   * changed under them would move their conversation to a door with no board tools behind it.
+   *
+   * A host that has no board must pass `assistantChat` **and** `systemPrompt`. Until it does, the
+   * chat calls a mutation that lives in a package it may not even load — which is how
+   * operato-figure got `Cannot query field "boardAIChat" on type "Mutation"` (2026-09-11).
+   */
+  @property({ type: String, attribute: 'chat-endpoint' })
+  chatEndpoint: 'boardAIChat' | 'assistantChat' = 'boardAIChat'
+
+  /**
+   * Who the assistant is on this surface, in the host's words. Required by `assistantChat`; the
+   * board conversation carries its own persona on the server and ignores this.
+   */
+  @property({ type: String, attribute: 'system-prompt' })
+  systemPrompt?: string
+
   /**
    * 라이브 상태를 다루는 대화면인가 — true 면 **첫 턴에 도구 호출을 강제**한다.
    *
@@ -1953,7 +2003,7 @@ export class OxBoardAIChat extends LitElement {
       // 로드된 메시지 id 를 seen 에 등록 — 이후 방송 에코 dedup 기준.
       this._seenMessageIds = new Set<string>(msgs.map((m: any) => m.id).filter(Boolean))
     } catch (e: any) {
-      this.errorMessage = `${i18next.t('board-ai.text.failed-to-load-history')}: ${e.message ?? e}`
+      this.errorMessage = `${i18next.t('ai-assistant.text.failed-to-load-history')}: ${e.message ?? e}`
     }
   }
 
@@ -1984,9 +2034,9 @@ export class OxBoardAIChat extends LitElement {
           const showActions = line.role !== 'system' && !line.pending && content.length > 0
           return html`
             ${showLabel
-              ? html`<div class="msg-label">${i18next.t('board-ai.label.ai')}</div>`
+              ? html`<div class="msg-label">${i18next.t('ai-assistant.label.ai')}</div>`
               : showSenderLabel
-                ? html`<div class="msg-label sender">${line.senderName || i18next.t('board-ai.label.participant')}</div>`
+                ? html`<div class="msg-label sender">${line.senderName || i18next.t('ai-assistant.label.participant')}</div>`
                 : nothing}
             <div class="msg-wrap ${line.role} ${isOther ? 'other' : ''}">
               <div
@@ -2000,7 +2050,7 @@ export class OxBoardAIChat extends LitElement {
                     : line.role === 'system'
                       ? html`<span
                           class="sys-text"
-                          title=${i18next.t('board-ai.text.toggle-system-note', { defaultValue: '눌러서 펼치기' })}
+                          title=${i18next.t('ai-assistant.text.toggle-system-note', { defaultValue: '눌러서 펼치기' })}
                           @click=${() => this.toggleSystemNote(idx)}
                           >${content}</span
                         >`
@@ -2011,14 +2061,14 @@ export class OxBoardAIChat extends LitElement {
                         <md-icon>check_circle</md-icon>
                         <span class="summary-text">
                           ${this.revertedPatchIds.has(line.patchId)
-                            ? i18next.t('board-ai.text.reverted')
-                            : i18next.t('board-ai.text.applied-changes')}
+                            ? i18next.t('ai-assistant.text.reverted')
+                            : i18next.t('ai-assistant.text.applied-changes')}
                         </span>
                         <button
                           class="revert-btn"
                           ?disabled=${this.revertedPatchIds.has(line.patchId)}
                           @click=${() => line.patchId && this.onRevertClick(line.patchId)}>
-                          ${i18next.t('board-ai.button.revert')}
+                          ${i18next.t('ai-assistant.button.revert')}
                         </button>
                       </div>
                     `
@@ -2047,7 +2097,7 @@ export class OxBoardAIChat extends LitElement {
               ${this.lastFailedInput
                 ? html`
                     <button class="retry-btn" @click=${this.retryLastSend}>
-                      ${i18next.t('board-ai.button.retry')}
+                      ${i18next.t('ai-assistant.button.retry')}
                     </button>
                   `
                 : nothing}
@@ -2062,11 +2112,11 @@ export class OxBoardAIChat extends LitElement {
                 <button
                   class="action"
                   @click=${() => (this.examplesOpen = !this.examplesOpen)}
-                  title=${i18next.t('board-ai.text.show-examples-tooltip')}>
+                  title=${i18next.t('ai-assistant.text.show-examples-tooltip')}>
                   <md-icon>${this.examplesOpen ? 'close' : 'lightbulb'}</md-icon>
                   ${this.examplesOpen
-                    ? i18next.t('board-ai.button.close')
-                    : i18next.t('board-ai.button.examples')}
+                    ? i18next.t('ai-assistant.button.close')
+                    : i18next.t('ai-assistant.button.examples')}
                 </button>
               </div>
               ${this.examplesOpen ? this.renderInlineExamples() : nothing}
@@ -2085,7 +2135,7 @@ export class OxBoardAIChat extends LitElement {
               }}
               ?disabled=${this.busy}
               rows="1"
-              placeholder=${this.placeholder ?? i18next.t('board-ai.text.input-placeholder')}></textarea>
+              placeholder=${this.placeholder ?? i18next.t('ai-assistant.text.input-placeholder')}></textarea>
             ${this.mentionOpen
               ? html`
                   <ox-mention-popup
@@ -2109,7 +2159,7 @@ export class OxBoardAIChat extends LitElement {
           <button
             ?disabled=${this.busy || !this.input.trim()}
             @click=${this.send}
-            title=${i18next.t('board-ai.text.send-tooltip')}>
+            title=${i18next.t('ai-assistant.text.send-tooltip')}>
             ${this.busy
               ? html`<span class="spinner"></span>`
               : html`<md-icon>arrow_upward</md-icon>`}
@@ -2343,7 +2393,7 @@ export class OxBoardAIChat extends LitElement {
       ])
     } else {
       this.showToast(
-        i18next.t('board-ai.text.mention-not-found', {
+        i18next.t('ai-assistant.text.mention-not-found', {
           token,
           defaultValue: `#${token} 을(를) 찾을 수 없습니다`
         })
@@ -2438,29 +2488,38 @@ export class OxBoardAIChat extends LitElement {
     }))
   }
 
+  /** 이 표면이 실제로 쓸 수 있는 트리거 — 판정은 `chat-triggers.ts` 가 하고 여기서는 사실만 읽는다. */
+  private get triggerChips(): TriggerChip[] {
+    return availableTriggers({
+      hasMentionableThings: !!(this.boardProvider || this.currentBoard || this.knownTypes?.length),
+      hasSession: !!this.sessionId,
+      slashTemplateCount: chatDefaults.slashTemplates.length
+    })
+  }
+
   private static readonly EXAMPLE_GROUPS: Array<{
     labelKey: string
     itemKeys: string[]
   }> = [
     {
-      labelKey: 'board-ai.label.create',
+      labelKey: 'ai-assistant.label.create',
       itemKeys: [
-        'board-ai.example.create-monitoring-dashboard',
-        'board-ai.example.create-welcome-screen'
+        'ai-assistant.example.create-monitoring-dashboard',
+        'ai-assistant.example.create-welcome-screen'
       ]
     },
     {
-      labelKey: 'board-ai.label.edit',
+      labelKey: 'ai-assistant.label.edit',
       itemKeys: [
-        'board-ai.example.edit-align-distribute',
-        'board-ai.example.edit-resize-board'
+        'ai-assistant.example.edit-align-distribute',
+        'ai-assistant.example.edit-resize-board'
       ]
     },
     {
-      labelKey: 'board-ai.label.style',
+      labelKey: 'ai-assistant.label.style',
       itemKeys: [
-        'board-ai.example.style-dark-mode',
-        'board-ai.example.style-rounded-shadow'
+        'ai-assistant.example.style-dark-mode',
+        'ai-assistant.example.style-rounded-shadow'
       ]
     }
   ]
@@ -2473,7 +2532,7 @@ export class OxBoardAIChat extends LitElement {
       <div class="session-tabs" role="tablist">
         ${this.sessions.map((s, i) => {
           const isActive = s.id === this.sessionId
-          const fallback = i18next.t('board-ai.text.session-tab-label', {
+          const fallback = i18next.t('ai-assistant.text.session-tab-label', {
             n: i + 1,
             defaultValue: `세션 ${i + 1}`
           })
@@ -2494,12 +2553,12 @@ export class OxBoardAIChat extends LitElement {
         })}
         <button
           class="session-tab-new"
-          title=${i18next.t('board-ai.button.new-chat', {
+          title=${i18next.t('ai-assistant.button.new-chat', {
             defaultValue: '새 대화'
           })}
           @click=${this._onSessionCreateClick}>
           <md-icon>add</md-icon>
-          <span>${i18next.t('board-ai.button.new-chat', { defaultValue: '새 대화' })}</span>
+          <span>${i18next.t('ai-assistant.button.new-chat', { defaultValue: '새 대화' })}</span>
         </button>
       </div>
     `
@@ -2552,36 +2611,30 @@ export class OxBoardAIChat extends LitElement {
       <div class="empty">
         <div class="header">
           <md-icon class="icon">auto_awesome</md-icon>
-          <div class="title">${this.intro?.title ?? i18next.t('board-ai.text.empty-title')}</div>
-          <div class="subtitle">${this.intro?.subtitle ?? i18next.t('board-ai.text.empty-subtitle')}</div>
+          <div class="title">${this.intro?.title ?? i18next.t('ai-assistant.text.empty-title')}</div>
+          <div class="subtitle">${this.intro?.subtitle ?? i18next.t('ai-assistant.text.empty-subtitle')}</div>
         </div>
 
-        <div class="trigger-row">
-          <div class="trigger-row-label">${i18next.t('board-ai.text.triggers-heading')}</div>
-          <div class="trigger-chips">
-            <button
-              class="trigger-chip"
-              title=${i18next.t('board-ai.text.trigger-component-tooltip')}
-              @click=${() => this.insertTrigger('#')}>
-              <span class="trigger-char">#</span>
-              <span class="trigger-desc">${i18next.t('board-ai.label.trigger-component')}</span>
-            </button>
-            <button
-              class="trigger-chip"
-              title=${i18next.t('board-ai.text.trigger-user-tooltip')}
-              @click=${() => this.insertTrigger('@')}>
-              <span class="trigger-char">@</span>
-              <span class="trigger-desc">${i18next.t('board-ai.label.trigger-user')}</span>
-            </button>
-            <button
-              class="trigger-chip"
-              title=${i18next.t('board-ai.text.trigger-insert-tooltip')}
-              @click=${() => this.insertTrigger('/')}>
-              <span class="trigger-char">/</span>
-              <span class="trigger-desc">${i18next.t('board-ai.label.trigger-insert')}</span>
-            </button>
-          </div>
-        </div>
+        ${this.triggerChips.length > 0
+          ? html`
+              <div class="trigger-row">
+                <div class="trigger-row-label">${i18next.t('ai-assistant.text.triggers-heading')}</div>
+                <div class="trigger-chips">
+                  ${this.triggerChips.map(
+                    trigger => html`
+                      <button
+                        class="trigger-chip"
+                        title=${i18next.t(trigger.tooltipKey)}
+                        @click=${() => this.insertTrigger(trigger.char)}>
+                        <span class="trigger-char">${trigger.char}</span>
+                        <span class="trigger-desc">${i18next.t(trigger.labelKey)}</span>
+                      </button>
+                    `
+                  )}
+                </div>
+              </div>
+            `
+          : ''}
 
         ${this.exampleGroups.map(
           group => html`
@@ -2599,11 +2652,12 @@ export class OxBoardAIChat extends LitElement {
         )}
 
         <div class="footer">
-          <span class="badge">${i18next.t('board-ai.label.korean-supported')}</span>
-          <span class="badge">${i18next.t('board-ai.label.multi-command')}</span>
-          <span class="badge">${i18next.t('board-ai.label.review-able')}</span>
-          <br />
-          ${i18next.t('board-ai.text.empty-footer-notice')}
+          <span class="badge">${i18next.t('ai-assistant.label.korean-supported')}</span>
+          <span class="badge">${i18next.t('ai-assistant.label.multi-command')}</span>
+          <span class="badge">${i18next.t('ai-assistant.label.review-able')}</span>
+          ${chatDefaults.footerNoticeKey
+            ? html`<br />${i18next.t(chatDefaults.footerNoticeKey)}`
+            : ''}
         </div>
       </div>
     `
@@ -2680,15 +2734,15 @@ export class OxBoardAIChat extends LitElement {
         <button
           class="msg-action ${isCopied ? 'confirmed' : ''}"
           title=${isCopied
-            ? i18next.t('board-ai.text.copied')
-            : i18next.t('board-ai.button.copy')}
+            ? i18next.t('ai-assistant.text.copied')
+            : i18next.t('ai-assistant.button.copy')}
           @click=${() => this.copyMessage(idx, content)}>
           <md-icon>${isCopied ? 'check' : 'content_copy'}</md-icon>
         </button>
         <button
           class="msg-action"
           ?disabled=${this.busy}
-          title=${i18next.t('board-ai.button.regenerate')}
+          title=${i18next.t('ai-assistant.button.regenerate')}
           @click=${() => this.regenerateAssistant(idx)}>
           <md-icon>refresh</md-icon>
         </button>
@@ -2713,19 +2767,19 @@ export class OxBoardAIChat extends LitElement {
         <md-icon>unfold_less</md-icon>
         <span class="fn-text">
           ${folded.summarized
-            ? i18next.t('board-ai.text.history-folded-summarized', {
+            ? i18next.t('ai-assistant.text.history-folded-summarized', {
                 count: folded.omitted,
                 defaultValue: '대화가 길어져 앞부분 {count}개가 요약으로 접혔습니다. 다른 주제라면 새 대화가 낫습니다.'
               })
-            : i18next.t('board-ai.text.history-folded', {
+            : i18next.t('ai-assistant.text.history-folded', {
                 count: folded.omitted,
                 defaultValue: '대화가 길어져 앞부분 {count}개가 생략되었습니다. 다른 주제라면 새 대화가 낫습니다.'
               })}
         </span>
         <button class="fn-new" @click=${this.startNewFromNotice}>
-          ${i18next.t('board-ai.button.new-chat')}
+          ${i18next.t('ai-assistant.button.new-chat')}
         </button>
-        <button class="fn-close" title=${i18next.t('board-ai.button.close')} @click=${() => (this.foldNoticeDismissed = true)}>
+        <button class="fn-close" title=${i18next.t('ai-assistant.button.close')} @click=${() => (this.foldNoticeDismissed = true)}>
           <md-icon>close</md-icon>
         </button>
       </div>
@@ -2767,8 +2821,8 @@ export class OxBoardAIChat extends LitElement {
                 class="run"
                 ?disabled=${sent}
                 @click=${() => this.executeProposal(p, key)}>
-                ${sent ? i18next.t('board-ai.text.proposal-sent', { defaultValue: '실행 요청됨' })
-                       : i18next.t('board-ai.button.run-proposal', { defaultValue: '실행' })}
+                ${sent ? i18next.t('ai-assistant.text.proposal-sent', { defaultValue: '실행 요청됨' })
+                       : i18next.t('ai-assistant.button.run-proposal', { defaultValue: '실행' })}
               </button>
             </div>
           `
@@ -2829,7 +2883,7 @@ export class OxBoardAIChat extends LitElement {
       <div class="grounding-warning" role="note">
         <md-icon>report</md-icon>
         <span>
-          ${i18next.t('board-ai.text.ungrounded-mention', {
+          ${i18next.t('ai-assistant.text.ungrounded-mention', {
             defaultValue: '확인되지 않은 대상을 언급했습니다 — 실제 데이터에 없습니다:'
           })}
           <span class="ids">${ids.join(', ')}</span>
@@ -2851,7 +2905,7 @@ export class OxBoardAIChat extends LitElement {
     const open = !!line.toolUsagesOpen
     const readCount = usages.filter(u => u.kind === 'read').length
     const writeCount = usages.filter(u => u.kind === 'write').length
-    const toolsLabel = i18next.t('board-ai.text.tools-used', { defaultValue: '도구 사용' })
+    const toolsLabel = i18next.t('ai-assistant.text.tools-used', { defaultValue: '도구 사용' })
     /* 눈에 걸려야 하는 것을 머리줄에 올린다 — 거절·접힘이 있으면 펼치기 전에 보인다.
      * (이번 사고들이 전부 그것이었다: 인자 빠진 호출이 거절됐고, 중복 제안이 접혔다.) */
     const problems = usages.filter(u => u.outcome === 'rejected' || u.outcome === 'error').length
@@ -2867,12 +2921,12 @@ export class OxBoardAIChat extends LitElement {
             <strong>${usages.length}</strong> ${toolsLabel}
             <span class="tool-usages-counts">
               · read ${readCount} · write ${writeCount}${problems
-                ? html` · <span class="tu-flag bad">${i18next.t('board-ai.text.tool-rejected-count', {
+                ? html` · <span class="tu-flag bad">${i18next.t('ai-assistant.text.tool-rejected-count', {
                     count: problems,
                     defaultValue: '거절 {count}'
                   })}</span>`
                 : nothing}${folded
-                ? html` · <span class="tu-flag">${i18next.t('board-ai.text.tool-folded-count', {
+                ? html` · <span class="tu-flag">${i18next.t('ai-assistant.text.tool-folded-count', {
                     count: folded,
                     defaultValue: '접힘 {count}'
                   })}</span>`
@@ -2916,7 +2970,7 @@ export class OxBoardAIChat extends LitElement {
     return html`
       ${newTurn
         ? html`<li class="tu-turn">
-            ${i18next.t('board-ai.text.tool-turn', { n: (u.iter ?? 0) + 1, defaultValue: '{n}번째 판단' })}
+            ${i18next.t('ai-assistant.text.tool-turn', { n: (u.iter ?? 0) + 1, defaultValue: '{n}번째 판단' })}
           </li>`
         : nothing}
       <li class="tool-usage-item kind-${u.kind} outcome-${outcome}">
@@ -2942,12 +2996,12 @@ export class OxBoardAIChat extends LitElement {
   /** 배지 문구 — 코드가 아니라 사람 말로. */
   private outcomeLabel(outcome: string): string {
     const map: Record<string, [string, string]> = {
-      ok: ['board-ai.text.outcome-ok', '조회'],
-      rejected: ['board-ai.text.outcome-rejected', '거절'],
-      queued: ['board-ai.text.outcome-queued', '적용 예정'],
-      proposed: ['board-ai.text.outcome-proposed', '제안'],
-      folded: ['board-ai.text.outcome-folded', '중복 접힘'],
-      error: ['board-ai.text.outcome-error', '오류']
+      ok: ['ai-assistant.text.outcome-ok', '조회'],
+      rejected: ['ai-assistant.text.outcome-rejected', '거절'],
+      queued: ['ai-assistant.text.outcome-queued', '적용 예정'],
+      proposed: ['ai-assistant.text.outcome-proposed', '제안'],
+      folded: ['ai-assistant.text.outcome-folded', '중복 접힘'],
+      error: ['ai-assistant.text.outcome-error', '오류']
     }
     const [key, fallback] = map[outcome] ?? map.ok
     return i18next.t(key, { defaultValue: fallback })
@@ -3008,7 +3062,7 @@ export class OxBoardAIChat extends LitElement {
       // 클립보드에는 marker 제거된 깨끗한 텍스트
       await navigator.clipboard.writeText(stripMentionRefids(content))
       this.copiedIdx = idx
-      this.showToast(i18next.t('board-ai.text.copied'))
+      this.showToast(i18next.t('ai-assistant.text.copied'))
       setTimeout(() => {
         if (this.copiedIdx === idx) this.copiedIdx = undefined
       }, 1500)
@@ -3128,30 +3182,41 @@ export class OxBoardAIChat extends LitElement {
       const liveBoard = this.boardProvider ? this.boardProvider() : this.currentBoard
 
       // mentions 는 위에서 이미 계산해 user line 에 thread — 그대로 mutation 입력으로 재사용.
+      const neutral = this.chatEndpoint === 'assistantChat'
       const result = await client.mutate({
-        mutation: BOARD_AI_CHAT_MUTATION,
+        mutation: neutral ? ASSISTANT_CHAT_MUTATION : BOARD_AI_CHAT_MUTATION,
         variables: {
-          input: buildChatMutationInput({
-            sessionId: this.sessionId,
-            history,
-            liveBoard,
-            scopes: this.scopes,
-            truncateAfterMessageId: this._truncateAfterId,
-            hostContext: this.hostContext,
-            toolCategories: this.toolCategories,
-            boardTools: this.boardTools,
-            requireGroundingTools: this.requireGroundingTools,
-            knownTypes: this.knownTypes,
-            categories: this.categories,
-            componentSchemas: this.componentSchemas,
-            selectedRefids: this.selectedRefids ?? [],
-            mentions
-          })
+          input: neutral
+            ? buildAssistantChatInput({
+                sessionId: this.sessionId,
+                history,
+                systemPrompt: this.systemPrompt!,
+                truncateAfterMessageId: this._truncateAfterId,
+                hostContext: this.hostContext,
+                toolCategories: this.toolCategories,
+                requireGroundingTools: this.requireGroundingTools
+              })
+            : buildChatMutationInput({
+                sessionId: this.sessionId,
+                history,
+                liveBoard,
+                scopes: this.scopes,
+                truncateAfterMessageId: this._truncateAfterId,
+                hostContext: this.hostContext,
+                toolCategories: this.toolCategories,
+                boardTools: this.boardTools,
+                requireGroundingTools: this.requireGroundingTools,
+                knownTypes: this.knownTypes,
+                categories: this.categories,
+                componentSchemas: this.componentSchemas,
+                selectedRefids: this.selectedRefids ?? [],
+                mentions
+              })
         }
       })
 
-      const out = result.data?.boardAIChat
-      if (!out) throw new Error(i18next.t('board-ai.text.empty-response'))
+      const out = neutral ? result.data?.assistantChat : result.data?.boardAIChat
+      if (!out) throw new Error(i18next.t('ai-assistant.text.empty-response'))
 
       /* 대화가 길어졌다는 서버 보고 — 닫지 않았다면 안내를 띄운다. */
       this.historyFolded = out.historyFolded ?? undefined

package/client/components/chat-defaults.ts

@@ -16,6 +16,18 @@
 export interface ChatDefaults {
   catalogEntries: any[]
   slashTemplates: any[]
+  /**
+   * 빈 화면 맨 아래 한 줄의 **i18n 키**. 없으면 그 줄을 안 그린다.
+   *
+   * 문장이 아니라 키를 받는 이유: 호스트의 client barrel 은 모듈 로드 시점에 돌고, 그때 i18next 가
+   * 아직 언어를 안 잡았을 수 있다. 키로 받아 **그릴 때** 번역한다.
+   *
+   * 왜 호스트 것인가: 여기 있던 기본 문장이 「AI 응답은 항상 **보드에** 적용 전 미리보기로 확인
+   * 가능합니다」였다. 보드가 없는 제품에서는 거짓이고(figure 에서 실제로 그렇게 떴다), 그 약속은
+   * 보드 저작기가 patch 를 미리보기로 거는 **기계가 있어서** 할 수 있는 말이다. 기계를 가진 쪽이
+   * 그 말을 한다.
+   */
+  footerNoticeKey?: string
 }
 
 export const chatDefaults: ChatDefaults = { catalogEntries: [], slashTemplates: [] }
@@ -24,4 +36,5 @@ export const chatDefaults: ChatDefaults = { catalogEntries: [], slashTemplates:
 export function registerChatDefaults(defaults: Partial<ChatDefaults>): void {
   if (defaults.catalogEntries) chatDefaults.catalogEntries = defaults.catalogEntries
   if (defaults.slashTemplates) chatDefaults.slashTemplates = defaults.slashTemplates
+  if (defaults.footerNoticeKey) chatDefaults.footerNoticeKey = defaults.footerNoticeKey
 }

package/client/components/chat-input-builder.test.ts

@@ -0,0 +1,81 @@
+/*
+ * What this guards: **the two doors take different inputs, and neither one leaks into the other.**
+ *
+ * The chat component talks to one of two server operations. `boardAIChat` is board authoring and
+ * carries the board model; `assistantChat` is for a surface with no document of its own. Sending
+ * a board field to the neutral door, or dropping a required one, produces a GraphQL error the
+ * user sees as "the assistant is broken".
+ *
+ * The required system prompt is the one that would be silent. A conversation with no persona
+ * still answers — as nobody, on a surface that never said what it is — and that reads as a poor
+ * model rather than a missing argument.
+ */
+import { buildAssistantChatInput, buildChatMutationInput } from './chat-input-builder'
+
+const history = [{ role: 'user', content: 'what figures do we have' }]
+
+const args = (over: any = {}) => ({ history, systemPrompt: 'you help someone draw a figure', ...over })
+
+describe('the neutral door carries no document', () => {
+  it('★ no board field reaches assistantChat', () => {
+    const input = buildAssistantChatInput(args({ sessionId: 's-1' }))
+
+    for (const field of ['currentBoard', 'selectedRefids', 'boardTools', 'knownTypes', 'componentSchemas', 'scopes', 'mentions']) {
+      expect(input).not.toHaveProperty(field)
+    }
+  })
+
+  it('carries the conversation, the session and the persona', () => {
+    const input = buildAssistantChatInput(args({ sessionId: 's-1' }))
+
+    expect(input.sessionId).toBe('s-1')
+    expect(input.messages).toBe(history)
+    expect(input.systemPrompt).toBe('you help someone draw a figure')
+  })
+
+  it('a one-off question has no session — null, not absent, so the server reads it as ad-hoc', () => {
+    expect(buildAssistantChatInput(args()).sessionId).toBeNull()
+  })
+})
+
+describe('the system prompt is required', () => {
+  it('★ refuses an empty prompt instead of sending one', () => {
+    expect(() => buildAssistantChatInput(args({ systemPrompt: '' }))).toThrow(/systemPrompt is required/)
+    expect(() => buildAssistantChatInput(args({ systemPrompt: '   ' }))).toThrow(/systemPrompt is required/)
+    expect(() => buildAssistantChatInput(args({ systemPrompt: undefined }))).toThrow(/systemPrompt is required/)
+  })
+})
+
+describe('optional fields are sent only when they mean something', () => {
+  it('an unset tool category list is left out — the server default is every registered category', () => {
+    expect(buildAssistantChatInput(args())).not.toHaveProperty('toolCategories')
+  })
+
+  it('★ an empty tool category list is sent — it means none, which is a different answer', () => {
+    expect(buildAssistantChatInput(args({ toolCategories: [] })).toolCategories).toEqual([])
+  })
+
+  it('grounding is sent only when required — false is the server default', () => {
+    expect(buildAssistantChatInput(args())).not.toHaveProperty('requireGroundingTools')
+    expect(buildAssistantChatInput(args({ requireGroundingTools: true })).requireGroundingTools).toBe(true)
+  })
+
+  it('host context and truncation travel when given', () => {
+    const input = buildAssistantChatInput(args({ hostContext: { figureId: 'fig-1' }, truncateAfterMessageId: 'm-9' }))
+
+    expect(input.hostContext).toEqual({ figureId: 'fig-1' })
+    expect(input.truncateAfterMessageId).toBe('m-9')
+  })
+})
+
+describe('the board door is unchanged', () => {
+  it('★ still carries selectedRefids — a missing one was why the AI did not know what was selected', () => {
+    const input = buildChatMutationInput({ history, liveBoard: null, selectedRefids: [3, 7] } as any)
+    expect(input.selectedRefids).toEqual([3, 7])
+  })
+
+  it('does not take a system prompt — the board conversation has its persona on the server', () => {
+    const input = buildChatMutationInput({ history, liveBoard: null, selectedRefids: [] } as any)
+    expect(input).not.toHaveProperty('systemPrompt')
+  })
+})