# KIMU 5.2.0 Comprehensive Technical Build Specification R3 — Feature Locked **Document status:** Controlling specification **Revision:** R3 **Published:** 29 July 2026 **Release baseline:** Increment 40 R1 **Product architecture:** Flask + SQLite + fully vendored React PWA **Primary chat models:** Kimi K2.6 and Kimi K2.7 Coder **Feature-lock authority:** Dr S ## 1. Authority, supersession and change control This R3 document supersedes the prior R2 requirements wherever this document is more specific. All previously locked KIMU requirements not explicitly changed here remain in force. The following rules are mandatory: 1. A locked requirement must not be removed, weakened, silently substituted, renamed to obscure its meaning or represented as implemented before verification. 2. Any change requires explicit user authorisation, a new specification revision, an updated feature-lock register and a recorded change rationale. 3. Placeholders remain visibly labelled **Placeholder** until implementation and acceptance evidence exist. 4. Documentation, comments, mock screens and disabled controls do not constitute implementation. 5. KIMU must preserve working chat functionality while later modules are implemented. 6. Model-specific controls must adapt automatically and unsupported controls must be disabled rather than ignored. 7. UK spelling, en-GB user-facing conventions and mobile-first behaviour are required. ## 2. Product objective KIMU is a private, installable AI workspace designed for Android-first use. It combines persistent chat, files, code execution, tools, realtime voice conversation, website creation and controlled multi-agent work in one coherent application. The product must feel like a cutting-edge native Android application while remaining a Flask-hosted, fully vendored React PWA. It must remain usable without runtime CDNs and must maintain truthful offline, provider and feature status indicators. ## 3. Controlling implementation order The following order is feature locked: 1. **Tools Runtime** 2. **Whisper + Sonic 3 Conversation Mode** 3. **Website Builder** 4. **Agent Swarm** Website Builder and Swarm must not bypass or duplicate the shared Tools Runtime. Swarm must not be enabled until tool permissions, approvals, budgets, cancellation, idempotency and audit evidence pass their release gates. ## 4. Current operational baseline Increment 40 provides the following operational foundations: - Owner bootstrap, authentication, CSRF protection and private sessions. - Persistent conversations, messages, reasoning and text export. - Switchable Kimi K2.6 and Kimi K2.7 Coder profiles. - Adaptive model preferences, with K2.7 Coder reasoning and preserved-thinking constraints locked to its profile. - Streaming Together chat responses and stop control. - Encrypted server-side file bodies and encrypted derived private metadata. - Safe ZIP inventory and file attachment workflows. - IndexedDB drafts and supported offline mutation queueing. - Idempotent replay, incremental sync and explicit 409 conflict handling. - Together Code Interpreter foundation, scoped memory and versioned draft skills. This baseline does not imply completion of the modules specified below. ## 5. Architecture lock ### 5.1 Runtime - Python Flask backend. - SQLite with WAL mode. - Fully vendored React frontend; no Preact. - Installable PWA shell. - No runtime JavaScript, CSS, font or icon CDN. - HTTPS is mandatory for production microphone, PWA and secure-session behaviour. - Provider credentials remain server-side for server-mediated features. ### 5.2 Data and storage - SQLite stores durable application records and operational metadata. - Private file bodies and derived private content use authenticated encryption. - IndexedDB stores drafts, offline queue records and cached application state. - The browser queue must never be described as application-level encrypted unless that encryption is implemented and verified. - Every asynchronous operation uses stable identifiers and terminal states. ### 5.3 Realtime gateway Flask must expose an authenticated application WebSocket gateway for Conversation Mode. The React client connects to KIMU, not directly to Together. The gateway owns upstream Whisper and Sonic WebSocket sessions, model-response cancellation, turn identifiers, quotas, diagnostics and audit records. ## 6. Model and provider lock ### 6.1 Selectable chat models Only these primary chat profiles are selectable: | Profile | Required use | Configuration | |---|---|---| | Kimi K2.6 | General chat, planning, review, coordination and conversational responses | Together model ID `moonshotai/Kimi-K2.6` | | Kimi K2.7 Coder | Coding, file modification, testing, website generation and release work | Deployment-configured Kimi K2.7 Coder model or dedicated endpoint identifier | K2.7 Coder availability and capabilities must be probed during configuration. The application must not falsely label an unverified endpoint as serverless or function-calling capable. ### 6.2 Model-aware settings - The model selector is available in Chat, Website Builder, Agents, Swarm and Conversation Mode where relevant. - K2.6 uses its supported reasoning and sampling controls. - K2.7 Coder keeps reasoning and preserved thinking enabled where required by its profile. - K2.7 Coder code, URL, diff and stack-trace speech is suppressed by default in TTS. - Switching profiles updates visible settings immediately and consistently across online and queued operations. ### 6.3 Audio models - Speech-to-text: Together Whisper Large v3, model ID `openai/whisper-large-v3`. - Text-to-speech: Together Cartesia Sonic 3, model ID `cartesia/sonic-3`. - Whisper is the exclusive STT engine for both dictation and Conversation Mode. - Browser SpeechRecognition and webkitSpeechRecognition are excluded from the locked target design. - Audio models appear in Audio settings and must not appear as selectable chat models. ## 7. Core chat requirements Chat must retain: - Persistent multi-turn conversations. - Separate reasoning display where supported. - Streaming response rendering. - Stop generation. - Text, image, code and ZIP attachments. - Draft recovery and offline queue status. - Export with attachment evidence. - Model-specific settings and honest provider readiness. Planned chat completion requirements include search, folders, tags, pinning, message editing, regeneration, branching and conversation-level tool history. These remain placeholders until implemented. ## 8. Tools Runtime — feature locked ### 8.1 Objective Provide one secure tool-execution framework shared by Chat, Website Builder, Code, Agents and Swarm. ### 8.2 Tool contract Every registered tool must define: - Stable tool ID and version. - Display name and purpose. - JSON Schema input contract. - Structured output contract. - Risk class. - Permission scope. - Approval policy. - Timeout and output-size limits. - Idempotency behaviour. - Cancellation behaviour. - Offline availability. - Compatible model profiles. - Audit and redaction rules. ### 8.3 Risk classes | Class | Required behaviour | |---|---| | Read | May run automatically only inside the active authorised scope | | Write | Requires explicit workspace/file scope and version checks | | Execute | Requires approval unless a narrow trusted policy applies | | External | Requires approval before contacting a non-provider external service | | Destructive | Requires per-action confirmation and cannot be permanently auto-approved | ### 8.4 Initial tool inventory - List, read and search authorised files. - Create files and directories inside an approved workspace. - Apply patches with version checks. - Rename or move files. - Delete with destructive-action confirmation. - Inspect and create ZIP archives using existing safe archive controls. - Read supported uploaded documents. - Run static checks and approved test commands. - Invoke Together Code Interpreter and reuse controlled sessions. - Create and manage artifacts. - Read approved memory scopes. - Record task progress, checkpoints and evidence. ### 8.5 Execution workflow 1. Model proposes a tool call. 2. KIMU validates the tool version and arguments. 3. KIMU evaluates risk, permission, scope and budget. 4. The user approves where required. 5. The runtime executes inside the authorised boundary. 6. Output is size-limited, sanitised and recorded. 7. The result is reinjected into the correct model turn. 8. An immutable audit record is committed. ### 8.6 Model behaviour - K2.6 may use native function calling for planning and general orchestration where the endpoint reports support. - K2.7 Coder is preferred for code/file tools. - K2.7 native tool support must be capability-probed. - When native tool calls are unavailable, KIMU may use a validated structured-output fallback; free-form pseudo-tool text must never execute. - Safe independent read calls may execute in parallel. Writes to overlapping files must not execute in parallel. ### 8.7 Tools acceptance gate Tools cannot be marked operational until invalid arguments are rejected, destructive actions cannot bypass approval, budgets are enforced, cancellation propagates, duplicate operation IDs do not execute twice, and every execution has attributable audit evidence. ## 9. Conversation Mode, TTS and STT — feature locked ### 9.1 Modes KIMU must provide two separate audio workflows: **Dictation mode** - Whisper transcribes captured or uploaded audio. - The transcript is inserted into the composer for review. - Dictation never automatically sends a message. **Conversation Mode** - Full-duplex, hands-free conversation. - Whisper continuously transcribes microphone audio. - Server VAD closes the user turn. - The final transcript is automatically submitted to the selected Kimi profile. - Sonic 3 streams the assistant response as speech. - True barge-in remains active while the assistant is speaking. ### 9.2 WebSocket topology 1. React captures microphone audio and sends 16-bit PCM at 16 kHz through an authenticated KIMU WebSocket. 2. Flask forwards audio to Together realtime Whisper over WebSocket. 3. Flask receives partial and final transcription events. 4. Flask streams the final transcript to K2.6 or K2.7 Coder. 5. Speakable response text is streamed to Sonic 3 over a persistent TTS WebSocket. 6. PCM audio frames are returned to the browser for low-latency Web Audio playback. The Together API key must never be exposed to browser storage or client JavaScript. ### 9.3 Turn state machine Required states: - Idle - Connecting - Listening - Speech detected - Transcribing - Thinking - Speaking - Barge-in - Reconnecting - Paused - Cancelled - Provider unavailable - Microphone blocked Every event carries session and turn identifiers. Events from superseded turns must be rejected. ### 9.4 Voice activity detection Server VAD is required and settings must include: - Detection threshold. - Minimum silence duration. - Minimum speech duration. - Maximum speech duration. - Speech padding. - Interrupt sensitivity. - Push-to-talk override. - Automatic turn submission toggle for Conversation Mode. Defaults must be tuned for Android mobile speech and remain configurable without reconnecting when the provider supports session updates. ### 9.5 True barge-in When user speech is detected while KIMU is speaking, KIMU must: 1. Stop browser playback immediately. 2. Clear all queued and decoded but unplayed audio. 3. Cancel the active Sonic context using `context.cancel`. 4. Cancel the active Kimi generation and prevent further TTS text enqueueing. 5. Continue microphone streaming to Whisper without losing the interrupting words. 6. Mark the previous assistant turn interrupted. 7. Reject stale audio, text and completion events from the cancelled turn. 8. Resume the normal listening/transcribing cycle. Muting the speaker without cancelling upstream work is not compliant barge-in. ### 9.6 TTS controls - Sonic 3 voice selector and voice preview. - Speech speed where supported. - Play, pause, resume and stop. - One active speaking turn per conversation. - Sentence/phrase streaming to reduce latency. - Pronunciation dictionary. - Automatic spoken replies default off outside Conversation Mode. - Reasoning is never spoken. - Code blocks, URLs, citations, tables, diffs and stack traces are filtered by default. - Usage, quota, latency, autoplay and provider diagnostics. ### 9.7 STT controls - Microphone permission requested only after user action. - Live partial transcript. - Final transcript evidence. - Recording timer and input-level indicator. - Pause, resume, cancel and push-to-talk. - Custom Whisper prompt for names and domain terminology. - K2.7 Coder profile adds programming vocabulary bias. - Uploaded audio transcription with supported type and size validation. ### 9.8 Conversation acceptance gate Conversation Mode cannot be marked operational until speech interrupts active playback and upstream generation, cancelled audio cannot resume, duplicate final transcripts cannot submit twice, reconnect does not duplicate turns, switching conversation or model safely terminates the old speaking context, and text chat remains usable when an audio provider fails. ## 10. Website Builder — feature locked ### 10.1 Objective Provide a mobile-first, wizard-based website workspace that uses K2.6 for requirements, content and review and K2.7 Coder for implementation, repair, tests and packaging. ### 10.2 Initial project types - Static HTML, CSS and JavaScript. - Multi-page static sites. - Landing pages, portfolios, documentation and small-business sites. - Approved fully vendored React templates. - PWA-capable projects. Flask-backed projects, authentication templates and data-backed sites may be enabled later through explicit templates and tool scopes. ### 10.3 Workflow 1. Describe objective and audience. 2. Choose project type. 3. Select pages and functions. 4. Select visual direction. 5. Review generated requirements and sitemap. 6. Approve the build plan. 7. Generate versioned files. 8. Preview in a restricted environment. 9. Run checks and review problems. 10. Revise through patch-based changes. 11. Roll back or compare versions. 12. Export a deployment-ready ZIP and evidence. ### 10.4 Workspace interface - Project dashboard and status cards. - Mobile, tablet and desktop preview modes. - File tree and code editor. - AI instruction composer. - Build activity and problems panel. - Asset library. - Version history, diffs and rollback. - Test and diagnostics evidence. ### 10.5 Preview security - Restricted iframe or separate preview origin where available. - No access to parent application storage. - Top-level navigation and uncontrolled downloads blocked. - Network requests blocked by default and explicitly allowlisted. - Preview caches isolated by project version. - KIMU secrets excluded from generated files and exports. ### 10.6 Persistence and versioning Projects, versions, file metadata, assets, builds, events, previews, requirements and test results must be durable. Large bodies use encrypted artifact storage. Every AI modification creates a parent-linked version, file diff, model attribution, tool trace, instruction and test result. No AI action silently overwrites the last working version. ### 10.7 Website Builder acceptance gate A user must be able to create, preview, edit, test, roll back and export a functioning multi-page site from the mobile interface. Imported ZIPs must use safe archive controls. Exported projects must contain no KIMU secrets and must include truthful build/test status. ## 11. Agent Swarm — feature locked ### 11.1 Objective Provide controlled multi-agent collaboration without uncontrolled autonomous execution. ### 11.2 Fixed initial roles | Role | Default model | Responsibility | |---|---|---| | Coordinator | K2.6 | Interpret objective, create task graph and manage dependencies | | Architect | K2.6 | Define design, constraints and interfaces | | Builder | K2.7 Coder | Create and modify implementation | | Tester | K2.7 Coder | Run checks, reproduce defects and validate fixes | | Reviewer | K2.6 | Independently review completeness, safety and evidence | | Release agent | K2.7 Coder | Package only reviewed, passing outputs | ### 11.3 Execution controls - Maximum agents and concurrency. - Token, time, cost, tool-call and iteration budgets. - Per-agent tool allowlists and file scopes. - Manual, balanced and bounded-autonomous approval modes. - Pause all, cancel agent, cancel swarm and resume checkpoint. - Stop-on-failure and mandatory-independent-review options. Destructive and external actions remain approval-gated in every mode. ### 11.4 Shared state Agents share structured task records rather than uncontrolled full transcripts: - Parent objective and constraints. - Task graph and dependencies. - Assigned roles, models, tools and files. - Findings, decisions, evidence and artifacts. - Test results, blockers and completion status. ### 11.5 Conflict prevention - File leases before edits. - Optimistic version checks. - Patch-based changes. - Merge queue for overlapping work. - Dedicated conflict-resolution task. - One release agent controls final packaging. ### 11.6 Failure and recovery - Automatically retry only idempotent operations. - Cap repeated repair loops. - Detect duplicate tasks and circular dependencies. - Escalate conflicting conclusions to Reviewer. - Persist checkpoints and last valid state. - Never label completion without configured evidence and review gates. ### 11.7 Swarm acceptance gate Two agents must not silently overwrite the same file. Budgets must stop further work when exhausted. Cancellation must stop new operations. Every result must be attributable to a task, role, model and tool trace. Completion requires review and test evidence, and a persisted swarm must resume safely after restart. ## 12. Remaining module catalogue The complete KIMU target continues to include: - Deep Research and RAG. - Code workspace and Code Interpreter. - Docs, Slides and Sheets. - Vision, Image Studio and Video Studio. - Files, ZIPs and Artifacts. - Agent Mode. - Memory and Skills. - Evaluation Centre. - Batch Centre. - Fine-tuning Laboratory. - Administration, diagnostics, audit, backups, retention and readiness. These modules retain their existing locked placeholders and acceptance obligations. The four modules detailed in Sections 8-11 now have controlling technical requirements and implementation order. ## 13. Security and privacy requirements - Provider secrets are never stored in frontend source or IndexedDB. - Authentication, CSRF and secure cookies remain enforced. - WebSocket handshakes require authenticated sessions, origin checks and short-lived connection tokens. - Audio sessions have quotas, maximum duration and idle timeout. - Tool and swarm actions use least privilege and immutable audit records. - Generated previews are isolated from KIMU storage and credentials. - Uploaded files and generated private artifacts retain authenticated encryption. - Sensitive admin changes require reauthentication. - Logs redact provider keys, raw authentication data and sensitive file content. ## 14. Reliability and observability The application must record: - Provider readiness and model capability probes. - WebSocket connection, reconnect and closure reasons. - STT partial/final latency and TTS first-audio latency. - Barge-in detection-to-playback-stop latency. - Tool execution duration, retries and cancellation. - Swarm budgets, agent state and checkpoint status. - Website build/test results and export checksums. - Errors using stable machine-readable codes and user-readable messages. No zero-cost or success fallback may be fabricated when pricing or provider results are unknown. ## 15. Mobile UX and accessibility - Android-first single-column layouts at phone widths. - Large touch targets and safe-area support. - Bottom navigation where appropriate. - Android Back closes transient layers before navigating away. - Conversation Mode has clear listening, thinking, speaking, interrupted and reconnecting states. - Reduced-motion preference is respected. - Keyboard, focus, label and screen-reader behaviour must be verified. - Enter must not unexpectedly submit multi-line composer content. ## 16. Release gates Each increment must include: - Static checks. - Frontend tests and production bundle validation. - Backend unit and integration tests. - Schema migration checks. - Security and regression checks. - Device/browser acceptance evidence where the feature depends on microphone, audio routing, PWA lifecycle or mobile gestures. - Updated implementation matrix. - Updated feature-lock register only when explicitly authorised. - Internal checksum manifest and independently verified release ZIP. A feature remains placeholder or partial when its required environment test could not run. ## 17. Planned increments ### Increment 41 — Tools Foundation Registry, schemas, permission engine, approvals, budgets, cancellation, idempotency, file tools and execution audit. ### Increment 42 — Realtime Conversation Mode Authenticated Flask WebSocket gateway, Whisper realtime STT, Sonic 3 realtime TTS, server VAD, full-duplex state machine, true barge-in and mobile audio diagnostics. ### Increment 43 — Website Builder Wizard, project/version model, file workspace, restricted preview, checks, rollback and ZIP import/export. ### Increment 44 — Agent Swarm Persistent task graph, fixed roles, file leases, budgets, approvals, checkpoints, review loop, test gate and release provenance. ## 18. External technical references The provider-specific requirements in this revision were checked against official Together AI documentation current on 29 July 2026: - Realtime transcription WebSocket: https://docs.together.ai/reference/audio-transcriptions-realtime - Streaming transcription: https://docs.together.ai/docs/inference/transcription/streaming - Voice activity detection: https://docs.together.ai/docs/inference/transcription/voice-activity-detection - TTS WebSocket and context cancellation: https://docs.together.ai/docs/inference/text-to-speech/websocket - Serverless model catalogue: https://docs.together.ai/docs/serverless/models - Recommended audio models: https://docs.together.ai/docs/inference/recommended-models - Parallel function calling: https://docs.together.ai/docs/inference/function-calling/parallel - Reasoning model profile: https://docs.together.ai/docs/inference/chat/reasoning ## 19. Certification statement This specification feature-locks the required design. It does not certify the four modules as implemented. Tools Runtime, Conversation Mode, Website Builder and Swarm remain placeholders until their respective acceptance gates pass and are documented in a later verified release.