---
phase: 36-voice-pipeline-foundation
plan: "02"
subsystem: shared-validators
tags:
  - voice-mode
  - schema
  - types
  - nexus-settings
dependency_graph:
  requires: []
  provides:
    - voiceMode field on createMessageSchema
    - VoiceMode type and VOICE_MODES constant
    - voiceMode on ChatMessage interface
    - voiceMode and telegramToken in nexus-settings schema
  affects:
    - server/src/routes/chat.ts (createMessageSchema.parse preserves voiceMode)
    - nexus-settings.json (reads voiceMode with default "text")
tech_stack:
  added: []
  patterns:
    - Zod enum with optional() for optional validated enum fields
    - Zod schema exported for direct testing without mocking file system
    - nexusSettingsSchema.parse({}) for consistent defaults in catch blocks
key_files:
  created:
    - server/src/__tests__/36-voice-schema.test.ts
  modified:
    - packages/shared/src/validators/chat.ts
    - packages/shared/src/types/chat.ts
    - server/src/services/nexus-settings.ts
decisions:
  - Export nexusSettingsSchema named export to enable direct Zod schema testing without file system mocking
  - Use nexusSettingsSchema.parse({}) in catch/fallback blocks for consistent Zod defaults
metrics:
  duration_minutes: 7
  completed_date: "2026-04-04T01:24:07Z"
  tasks_completed: 2
  tasks_total: 2
  files_created: 1
  files_modified: 3
requirements_completed:
  - VPIPE-05
---

# Phase 36 Plan 02: Voice Schema Foundation Summary

**One-liner:** voiceMode enum field added to createMessageSchema and ChatMessage, plus nexus-settings extended with voiceMode (default "text"), telegramToken, piperBinaryPath, and whisperBinaryPath.

## Completed Tasks

| Task | Name | Commit | Files |
|------|------|--------|-------|
| 1 | Extend shared validators and types with voiceMode field | 390034c7 | packages/shared/src/validators/chat.ts, packages/shared/src/types/chat.ts, server/src/__tests__/36-voice-schema.test.ts |
| 2 | Extend nexus-settings schema with voiceMode and telegramToken | 044e3dad | server/src/services/nexus-settings.ts, server/src/__tests__/36-voice-schema.test.ts |

## What Was Built

### packages/shared/src/validators/chat.ts

Added `VOICE_MODES` constant, `VoiceMode` type, and optional `voiceMode` field to `createMessageSchema`:

```typescript
export const VOICE_MODES = ["text", "voice_input", "full_voice"] as const;
export type VoiceMode = (typeof VOICE_MODES)[number];

// In createMessageSchema:
voiceMode: z.enum(VOICE_MODES).optional(),
```

### packages/shared/src/types/chat.ts

Added optional `voiceMode` field to `ChatMessage` interface:

```typescript
voiceMode?: "text" | "voice_input" | "full_voice" | null;
```

### server/src/services/nexus-settings.ts

Extended `nexusSettingsSchema` with four new fields, exported the schema for testing, updated fallback logic:

```typescript
export const nexusSettingsSchema = z.object({
  mode: z.enum(NEXUS_MODES).default("both"),
  voiceEnabled: z.boolean().default(false),
  voiceMode: z.enum(VOICE_MODES).default("text"),
  telegramToken: z.string().optional(),
  piperBinaryPath: z.string().optional(),
  whisperBinaryPath: z.string().optional(),
});
```

### server/src/__tests__/36-voice-schema.test.ts

11 tests covering:
- createMessageSchema voiceMode enum validation (6 tests)
- nexusSettingsSchema voiceMode defaults and telegramToken (5 tests)

## Verification

All verification checks pass:

- `pnpm --filter @paperclipai/server test --run` exits 0 for 36-voice-schema.test.ts (11/11 tests)
- `grep "voiceMode" packages/shared/src/validators/chat.ts` shows the field
- `grep "voiceMode" packages/shared/src/types/chat.ts` shows the field
- `grep "voiceMode" server/src/services/nexus-settings.ts` shows the field
- `grep "telegramToken" server/src/services/nexus-settings.ts` shows the field

## Deviations from Plan

None — plan executed exactly as written.

## Known Stubs

None — this plan adds schema/type foundations only. No UI rendering or data flow is introduced.

## Self-Check: PASSED

- packages/shared/src/validators/chat.ts — FOUND, contains voiceMode
- packages/shared/src/types/chat.ts — FOUND, contains voiceMode
- server/src/services/nexus-settings.ts — FOUND, contains voiceMode and telegramToken
- server/src/__tests__/36-voice-schema.test.ts — FOUND, 11 passing tests
- Commit 390034c7 — FOUND
- Commit 044e3dad — FOUND