System Requirements Document for jarves-ai

1. Introduction

JARVES AI is a simple, powerful, voice-first AI OS. Its defining promise is stated in the user's own words: the user says "Jarves, ये क्या है?" and Jarves understands and answers. The product is built so that a person can Speak, Ask, Research, Create, Build, Control — and Jarves executes those requests with tools, permissions, and verified results.

The full vision spans voice command and phone control, web research, a best-answer engine, a multi-AI router, chat, memory, file intelligence with RAG, media search and editing agents, coding help, website/app builder, AI agents, tools/plugins, security and permissions, backend APIs, multilingual support, and UI/UX themes.

Development is explicitly phased. The first working version is deliberately small and must include: login, chat, voice input and output, a speaker button, basic web research, citations, best answer, basic history, basic memory, and file upload. Later phases progressively add multi-AI routing, coding help, AI agents, media search and editing agents, phone control, gallery search, and supported app integrations.

This document is written as a proposal ("Proposal se likho"), as the user explicitly requested.

Audience. The primary audience is the Jarves User — a multilingual (Hindi/English first), mobile-heavy everyday power user, researcher, or builder who wants to speak a command and receive a verified answer. The secondary audience is the Jarves Builder/Developer, who builds Jarves through the phased roadmap and progressively expands it.

2. System Overview

JARVES AI is delivered as a first-party application with custom UI and application-owned identity. The current delivery covers the Phase 1 working version plus the phase-expansion surfaces named in the roadmap, all reachable through a persistent in-app shell.

Actors.

• Jarves User — the end user who speaks or types to Jarves and expects it to understand and answer.
• Jarves Builder/Developer — the person building Jarves through the phased roadmap.

Accepted behavior at a glance.

• Anonymous visitors learn what Jarves is on Landing, then establish identity through Sign Up or return through Login.
• Authenticated users converse by typing in Chat and by speaking in Voice, with a speaker button controlling spoken output.
• Research returns web research results, citations, and a best answer.
• History provides a revisitable browse destination for prior conversations; Memory owns durable memory retained across interactions.
• Files owns file upload and retrieval-augmented file intelligence.
• AI Router owns multi-model routing; Coding provides a focused coding-assistance workspace; Agents owns invocation and management of AI agents and tools/plugins.
• Media owns media search and agent-assisted editing; Phone owns phone-control actions and gallery search; Integrations owns supported application connections and integrated actions.
• Permissions owns security and permission review required before executing actions; Languages owns multilingual interaction preferences; Themes owns UI/UX theme selection.

Ownership and narrow exclusions. Jarves owns identity, conversation, memory, file, and permission state. External web sources, third-party AI models, connected applications, and the device's own phone/gallery subsystems remain provider- or device-owned; Jarves owns the request, the permission gate, and the verified result it presents. This document does not add account-management, billing, social, or administrative capabilities that the source did not request.

2a. Product Interpretation and Delivery Boundary

JARVES AI is delivered as a first-party application with its own custom interface and its own identity. A visitor can read about Jarves anonymously on Landing; the moment they want durable conversation, memory, or files, they must establish identity — either by enrolling on Sign Up or by returning through Login. Every other destination in the product is protected and requires that identity, because conversation history, memory, uploaded files, permission grants, and language/theme preferences are all bound to the individual user and must remain theirs across sessions.

The product is voice-first but not voice-only: the same request can be typed in Chat or spoken in Voice, and the speaker button controls whether Jarves answers aloud. Research, citations, and the best answer are presented as first-class results rather than as a footnote. Actions that touch the device, connected apps, or external tools pass through Permissions before execution, and results are presented as verified.

Current vs. future boundary. Everything described in this document is current: the Phase 1 working version (login, chat, voice in/out, speaker button, basic web research, citations, best answer, basic history, basic memory, file upload) plus the phase-expansion surfaces the roadmap names (multi-AI router, coding help, AI agents, media search and editing agents, phone control, gallery search, supported app integrations, tools/plugins, security and permissions, backend APIs, multilingual support, UI/UX themes). The roadmap is written as a proposal, and the phasing constraint is binding: the small working version comes first, and later capabilities are added progressively rather than replacing it.

2b. Source Content Inventory

No reference directive in this project declares content_source; therefore no source content inventory is included.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Explains Jarves' voice-first purpose, its audience, and its core capabilities. Presents the wordmark JARVES with AI in outlined cyan stroke, the single muted line "बोलो — Jarves सुन रहा है।", and the four verbs Speak · Ask · Research · Build as a monospace HUD strip flush to the bottom viewport edge.
• Primary actions: Enter the Speak pill capsule to begin; navigate to Sign Up to enroll; navigate to Login to return.
• Supporting actions: Read the four-verb HUD strip as a status/navigation row; observe the voice orb's idle breathing state.
• Domain entities: Public capability summary, verb states (Speak, Ask, Research, Build), wordmark.
• Component responsibilities: Full-viewport radial hero composition with the WebGL voice orb dead-centre; headline arc-set above the orb; HUD verb strip pinned to the bottom edge; identity entry controls.
• States: Loading — orb initializes and the hero frame composes. Empty — no user state exists yet; the hero is the content. Success — visitor proceeds to Sign Up or Login. Error — if the hero subject cannot initialize, a static composed frame with the wordmark, the muted line, and the Speak capsule remains fully readable and operable. Recovery — the static frame is the reduced-motion and fallback state; identity entry remains available.

Login

• Information/state: Returning verification surface. Collects the credentials of an existing Jarves User and explains that protected Jarves state (conversations, memory, files, permissions, preferences) becomes available after verification.
• Primary actions: Submit credentials to verify identity and enter the protected workspace.
• Supporting actions: Navigate to Sign Up if the visitor has no account.
• Domain entities: User identity, verification attempt.
• Component responsibilities: Credential form; submit control; link to Sign Up; inline verification feedback.
• States: Loading — verification in progress with the submit control held. Empty — form presented with no prior input. Success — identity verified and the user is taken into the protected workspace. Error — invalid credentials are reported inline without revealing which field failed; the form remains filled and resubmittable. Recovery — the user may correct credentials and resubmit, or move to Sign Up.

Sign Up

• Information/state: Self-service enrollment surface. Establishes a new Jarves User identity so that durable conversation, memory, file, and preference state can be privately owned and resumed.
• Primary actions: Submit enrollment details to create the identity and enter the protected workspace.
• Supporting actions: Navigate to Login if the visitor already has an account.
• Domain entities: New user identity, enrollment attempt.
• Component responsibilities: Enrollment form; submit control; link to Login; inline validation feedback.
• States: Loading — enrollment in progress with the submit control held. Empty — form presented with no prior input. Success — identity created and the user enters the protected workspace. Error — validation or enrollment failure is reported inline with the specific field or reason; entered values are preserved. Recovery — the user corrects the reported issue and resubmits, or moves to Login.

Chat

• Information/state: The core conversational workspace for typed questions and answers. Shows the running conversation, the user's typed turns, Jarves' answers, and the current response state.
• Primary actions: Type a question and send it; read Jarves' answer.
• Supporting actions: Open the speaker button to hear the answer; move to Voice to speak instead; open the right HUD panel for citations, memory hits, file chunks, and permissions; continue the conversation.
• Domain entities: Conversation, message turn, answer, response state.
• Component responsibilities: Centre conversation column; composer with send control; speaker button; right HUD panel that slides in for citations, memory hits, file chunks, and permissions; persistent left rail.
• States: Loading — Jarves is composing an answer, shown as a thin cyan arc sweeping the orb. Empty — a new conversation with no turns yet, prompting the user to ask. Success — the answer is rendered in the conversation column and the turn is retained. Error — a failed answer is reported in place of the response with a retry affordance; the user's original question is preserved. Recovery — retry the turn, rephrase, or switch to Voice.

Voice

• Information/state: The voice-first surface. Owns spoken queries, voice responses, and the speaker control. Shows the live voice state — idle, listening, thinking, answering — through the orb and its rings.
• Primary actions: Open the mic to speak a query; hear Jarves' spoken answer.
• Supporting actions: Toggle the speaker button to control spoken output; read the live transcript as HUD data; move to Chat to type instead.
• Domain entities: Spoken query, transcript, voice state, spoken answer.
• Component responsibilities: Voice orb with three concentric hairline rings that expand on listening; waveform bars reacting to mic amplitude; live transcript; speaker button.
• States: Loading — the voice surface initializes and requests microphone access through the permission gate. Empty — idle breathing pulse with no active query. Success — the transcript is captured, Jarves answers, and the waveform ripples in sync with TTS. Error — if microphone access is denied or capture fails, the surface states the reason and offers typed input via Chat. Recovery — re-request permission, retry capture, or continue in Chat.

Research

• Information/state: Owns web research results, citations, and best-answer presentation. Presents the best answer first, with citations rendered as a HUD timeline on a vertical hairline rail with numbered cyan nodes.
• Primary actions: Submit a research query; read the best answer; open a citation.
• Supporting actions: Scrub the citation timeline with scroll; expand a citation node into a glass card showing domain, timestamp, and a verified badge; continue researching.
• Domain entities: Research query, best answer, citation (domain, timestamp, verification status), source.
• Component responsibilities: Query composer; best-answer block; citation HUD rail with numbered nodes and expandable glass cards; verified badge.
• States: Loading — research in progress with the query held and progress indicated. Empty — no query yet, prompting the user to research something. Success — best answer plus citation timeline rendered. Error — if research fails or returns nothing usable, the surface says so plainly and offers retry. Recovery — retry the query, narrow it, or continue in Chat.

History

• Information/state: A revisitable browse destination for prior conversations. Lists past conversations with enough metadata to recognize them.
• Primary actions: Browse prior conversations; open one to revisit it.
• Supporting actions: Continue a revisited conversation; move to Memory to review retained memory.
• Domain entities: Conversation record, timestamp, conversation title or summary.
• Component responsibilities: Conversation list; open/continue control; empty-state prompt.
• States: Loading — history is being retrieved. Empty — no prior conversations, with a prompt to start one. Success — conversations listed and openable. Error — retrieval failure is reported with a retry affordance. Recovery — retry retrieval or start a new conversation in Chat.

Memory

• Information/state: Owns review and use of durable memory retained across interactions. Shows what Jarves remembers and where that memory was used.
• Primary actions: Review retained memory items; use memory in a conversation.
• Supporting actions: Open the right HUD panel to see memory hits alongside a response; move to History to revisit the conversation where memory was formed.
• Domain entities: Memory item, memory hit, source interaction.
• Component responsibilities: Memory list; memory-hit display in the HUD panel; empty-state prompt.
• States: Loading — memory is being retrieved. Empty — nothing retained yet, with an explanation of how memory forms. Success — memory items listed and memory hits shown against responses. Error — retrieval failure is reported with a retry affordance. Recovery — retry retrieval or continue in Chat.

Files

• Information/state: Owns file upload and retrieval-augmented file intelligence. Shows uploaded files as glass thumbnails with monospace metadata overlays, and shows retrieved file chunks when they inform an answer.
• Primary actions: Upload a file; ask a question against uploaded files.
• Supporting actions: Open the right HUD panel to inspect retrieved file chunks; move to Chat to continue the conversation with file context.
• Domain entities: Uploaded file, file metadata, retrieved chunk, retrieval-augmented answer.
• Component responsibilities: Upload control; file list with glass thumbnails and monospace metadata; chunk display in the HUD panel; empty-state prompt.
• States: Loading — upload or indexing in progress with progress indicated. Empty — no files uploaded, with a prompt to upload. Success — file accepted, indexed, and available for retrieval-augmented answers. Error — unsupported file, oversized file, or failed upload/indexing is reported with the specific reason. Recovery — retry the upload, choose a different file, or continue without it.

AI Router

• Information/state: Owns multi-model routing for Jarves queries. Presented as a radial node map with the active model at the centre inside a luminous ring and candidate models orbiting it.
• Primary actions: Send a query through the router; observe which model is chosen.
• Supporting actions: Read the chosen model's name and latency in monospace; scrub the scroll to push the camera into the node map.
• Domain entities: Query, candidate model, active model, routing path, latency.
• Component responsibilities: Radial node map; centre active-model ring; orbiting candidate nodes; 1px cyan routing path with travelling light; monospace model/latency readout.
• States: Loading — routing in progress, shown as light travelling along the cyan path. Empty — no query routed yet, with the node map in its resting composition. Success — the chosen model is named at the centre with its latency. Error — if routing fails or no model is available, the failure is stated plainly with a retry affordance. Recovery — retry routing or continue in Chat.

Coding

• Information/state: A focused workspace for coding assistance. Presents code-oriented requests and Jarves' coding responses with monospace technical data.
• Primary actions: Submit a coding request; read the coding response.
• Supporting actions: Continue the exchange; move to Chat for general conversation.
• Domain entities: Coding request, code response, technical metadata.
• Component responsibilities: Coding request composer; response area with monospace rendering; continuation control.
• States: Loading — the coding response is being composed. Empty — no coding request yet, with a prompt to ask. Success — the coding response is rendered and retained. Error — a failed coding response is reported with a retry affordance and the request preserved. Recovery — retry, rephrase, or continue in Chat.

Agents

• Information/state: Owns invocation and management of AI agents and tools/plugins. Shows available agents and tools, their state, and their live activity.
• Primary actions: Invoke an agent or tool for a task; observe its progress and result.
• Supporting actions: Review an agent's live pulse; open the right HUD panel for the agent's outputs and any permission scopes it requires.
• Domain entities: Agent, tool/plugin, invocation, agent state, agent output.
• Component responsibilities: Agent and tool list; invocation control; live pulse indicator; output display; permission-scope handoff to Permissions.
• States: Loading — an agent invocation is starting or running. Empty — no agents or tools available yet, with an explanation. Success — the agent completes and its output is presented as a verified result. Error — an agent failure or a denied permission is reported with the reason. Recovery — retry the invocation, adjust the request, or grant the required permission in Permissions.

Media

• Information/state: Owns media search and agent-assisted editing workflows. Presents media results as glass thumbnails with monospace metadata overlays.
• Primary actions: Search media; request an agent-assisted edit.
• Supporting actions: Inspect media metadata; open the right HUD panel for edit results; hand off permission scopes to Permissions.
• Domain entities: Media item, media metadata, search query, edit request, edit result.
• Component responsibilities: Media search control; glass-thumbnail result grid; edit request composer; edit result display.
• States: Loading — search or edit in progress. Empty — no media results for the query, with a prompt to refine. Success — media results or the edited output are presented. Error — a failed search or edit is reported with the reason. Recovery — retry, refine the query, or grant a required permission in Permissions.

Phone

• Information/state: Owns phone-control actions and gallery search. Shows the device actions available and the gallery results retrieved.
• Primary actions: Issue a phone-control action; search the gallery.
• Supporting actions: Review gallery results as glass thumbnails with monospace metadata; hand off device permission scopes to Permissions.
• Domain entities: Phone action, gallery item, gallery metadata, device permission scope.
• Component responsibilities: Phone-action control; gallery search control; gallery result display; permission-scope handoff.
• States: Loading — the device action or gallery search is executing. Empty — no gallery results for the query, with a prompt to refine. Success — the action completes or gallery results are presented. Error — a denied device permission or failed action is reported with the reason. Recovery — retry, refine the query, or grant the required permission in Permissions.

Integrations

• Information/state: Owns supported application connections and integrated actions. Shows which applications are connected and what integrated actions are available.
• Primary actions: Connect a supported application; perform an integrated action.
• Supporting actions: Review connection state; hand off connection permission scopes to Permissions.
• Domain entities: Supported application, connection, integrated action, connection state.
• Component responsibilities: Application list; connect/disconnect control; integrated-action control; permission-scope handoff.
• States: Loading — a connection or integrated action is in progress. Empty — no supported applications connected yet, with an explanation. Success — the connection is established or the integrated action completes with a verified result. Error — a failed connection or denied scope is reported with the reason. Recovery — retry the connection or grant the required permission in Permissions.

Permissions

• Information/state: Owns security and permission review required before executing actions. Presents each scope in monospace (for example camera · gallery · contacts) as a glass consent sheet that slides up from the bottom.
• Primary actions: Choose Allow once, Always, or Deny for a requested scope.
• Supporting actions: Review the listed scopes before deciding; revisit previously granted scopes.
• Domain entities: Permission scope, consent decision (Allow once / Always / Deny), grant record.
• Component responsibilities: Glass consent sheet sliding up from the bottom; monospace scope list; three-capsule decision row; grant record display.
• States: Loading — the requested scopes are being resolved. Empty — no pending permission requests, with a summary of existing grants. Success — the decision is recorded and the requesting action proceeds or is blocked accordingly. Error — if the decision cannot be recorded, the action does not execute and the failure is stated plainly. Recovery — retry the decision; the requesting action remains blocked until a decision is recorded.

Languages

• Information/state: Owns multilingual interaction preferences and language use. Shows the current interaction language and the languages Jarves supports for interaction.
• Primary actions: Select the interaction language.
• Supporting actions: Confirm the selection takes effect in subsequent interaction; move to Chat or Voice to use it.
• Domain entities: Interaction language, language preference.
• Component responsibilities: Language selection control; current-language indicator; confirmation feedback.
• States: Loading — available languages are being retrieved. Empty — no preference set yet, with the default interaction language indicated. Success — the preference is saved and applied to subsequent interaction. Error — a failed save is reported with a retry affordance. Recovery — retry the save; the previous preference remains in effect.

Themes

• Information/state: Owns UI and UX theme selection. Shows the available themes and the currently applied theme.
• Primary actions: Select a theme.
• Supporting actions: Preview the applied theme across the interface; move to any other destination to see it applied.
• Domain entities: Theme, theme preference.
• Component responsibilities: Theme selection control; current-theme indicator; live preview.
• States: Loading — available themes are being retrieved. Empty — no preference set yet, with the default theme indicated. Success — the theme is applied and saved. Error — a failed save is reported with a retry affordance. Recovery — retry the save; the previous theme remains applied.

3. Functional Requirements

FR-1 — Voice-first understanding and answering (explicit) As a Jarves User, I should say "Jarves, ये क्या है?" and have Jarves understand the spoken query and answer it, so that the product's core promise works by voice alone.

• Trigger/input: The user opens the mic on Voice and speaks a query.
• Observable result: The query is captured as a live transcript, Jarves answers, and the answer is presented and spoken.
• Access state: Requires an established identity.
• Failure/recovery: If microphone access is denied or capture fails, the reason is stated and typed input via Chat remains available.
• Continuation: The user can ask a follow-up by voice or continue in Chat.

FR-2 — Login (explicit) As a Jarves User, I should log in, so that I can reach my protected Jarves state.

• Trigger/input: The user submits credentials on Login.
• Observable result: Identity is verified and the protected workspace becomes available.
• Access state: Anonymous entry; verification establishes access.
• Failure/recovery: Invalid credentials are reported inline without revealing which field failed; the form remains filled and resubmittable.
• Continuation: The user enters the protected workspace, or moves to Sign Up.

FR-3 — Self-service enrollment (required_inference) As a Jarves User, I should be able to create my own Jarves identity, so that my conversations, memory, files, and preferences are privately mine and resumable.

• Trigger/input: The user submits enrollment details on Sign Up.
• Observable result: A new identity is created and the user enters the protected workspace.
• Access state: Anonymous entry; enrollment establishes access.
• Failure/recovery: Validation or enrollment failure is reported inline with the specific field or reason, and entered values are preserved.
• Continuation: The user enters the protected workspace, or moves to Login.

FR-4 — Chat (explicit) As a Jarves User, I should chat with Jarves by typing, so that I can ask questions and read answers in a running conversation.

• Trigger/input: The user types a question in Chat and sends it.
• Observable result: Jarves' answer is rendered in the conversation column and the turn is retained.
• Access state: Requires an established identity.
• Failure/recovery: A failed answer is reported in place of the response with a retry affordance, and the original question is preserved.
• Continuation: The user continues the conversation, retries, or switches to Voice.

FR-5 — Voice input and output (explicit) As a Jarves User, I should speak to Jarves and hear Jarves answer, so that the interaction is genuinely voice-first.

• Trigger/input: The user opens the mic on Voice and speaks; Jarves responds.
• Observable result: The voice state moves through idle, listening, thinking, and answering, with rings expanding on listening and the waveform rippling in sync with TTS.
• Access state: Requires an established identity and microphone permission through Permissions.
• Failure/recovery: A denied microphone permission or failed capture is reported with the reason, and typed input remains available.
• Continuation: The user speaks again or continues in Chat.

FR-6 — Speaker button (explicit) As a Jarves User, I should control spoken output with a speaker button, so that I decide when Jarves answers aloud.

• Trigger/input: The user toggles the speaker button on Chat or Voice.
• Observable result: Spoken output is enabled or silenced for the answer, and the control reflects the current state.
• Access state: Requires an established identity.
• Failure/recovery: If audio output is unavailable, the state is reported and the written answer remains fully readable.
• Continuation: The user continues the conversation with the chosen output mode.

FR-7 — Basic web research (explicit) As a Jarves User, I should have Jarves perform web research, so that answers are grounded in sources rather than unsupported.

• Trigger/input: The user submits a research query on Research.
• Observable result: Research results are retrieved and presented with the best answer.
• Access state: Requires an established identity.
• Failure/recovery: If research fails or returns nothing usable, the surface says so plainly and offers retry.
• Continuation: The user retries, narrows the query, or continues in Chat.

FR-8 — Citations (explicit) As a Jarves User, I should see citations for researched answers, so that I can check where an answer came from.

• Trigger/input: A researched answer is presented on Research.
• Observable result: Citations render as a HUD timeline on a vertical hairline rail with numbered cyan nodes; each node expands into a glass card showing domain, timestamp, and a verified badge.
• Access state: Requires an established identity.
• Failure/recovery: If a citation cannot be resolved, the node states that plainly rather than presenting an unverified source as verified.
• Continuation: The user opens further citations or continues researching.

FR-9 — Best answer (explicit) As a Jarves User, I should receive a best answer, so that I do not have to assemble the conclusion myself from raw results.

• Trigger/input: A research query is submitted on Research.
• Observable result: A single best answer is presented ahead of the supporting citations.
• Access state: Requires an established identity.
• Failure/recovery: If no best answer can be determined, the surface says so and presents the available results instead of inventing a conclusion.
• Continuation: The user accepts the answer, opens citations, or refines the query.

FR-10 — Basic history (explicit) As a Jarves User, I should have my conversation history retained, so that I can revisit prior conversations.

• Trigger/input: The user opens History.
• Observable result: Prior conversations are listed and can be opened and continued.
• Access state: Requires an established identity; history is bound to that identity.
• Failure/recovery: A retrieval failure is reported with a retry affordance.
• Continuation: The user opens a conversation, continues it, or starts a new one in Chat.

FR-11 — Basic memory (explicit) As a Jarves User, I should have Jarves retain basic memory across interactions, so that it carries context forward.

• Trigger/input: The user interacts with Jarves and later opens Memory.
• Observable result: Retained memory items are listed, and memory hits are shown against responses in the right HUD panel.
• Access state: Requires an established identity; memory is bound to that identity.
• Failure/recovery: A retrieval failure is reported with a retry affordance.
• Continuation: The user reviews memory, uses it in a conversation, or revisits its source in History.

FR-12 — File upload (explicit) As a Jarves User, I should upload files, so that Jarves can work with my own material.

• Trigger/input: The user uploads a file on Files.
• Observable result: The file is accepted, indexed, and shown as a glass thumbnail with monospace metadata.
• Access state: Requires an established identity; files are bound to that identity.
• Failure/recovery: Unsupported, oversized, or failed uploads are reported with the specific reason.
• Continuation: The user asks a question against the file or uploads another.

FR-13 — File intelligence with RAG (explicit) As a Jarves User, I should ask questions against my uploaded files, so that answers are grounded in my own material.

• Trigger/input: The user asks a question with uploaded files available.
• Observable result: Retrieved file chunks are shown in the right HUD panel and inform the answer.
• Access state: Requires an established identity.
• Failure/recovery: If no relevant chunk is retrieved, the answer states that the files did not cover the question rather than fabricating a source.
• Continuation: The user refines the question, uploads more material, or continues in Chat.

FR-14 — Multi-AI router (explicit) As a Jarves User, I should have my queries routed across multiple AI models, so that the best-suited model answers.

• Trigger/input: The user sends a query through AI Router.
• Observable result: The radial node map shows routing as light travelling along a 1px cyan path, and the chosen model is named at the centre with its latency in monospace.
• Access state: Requires an established identity.
• Failure/recovery: If routing fails or no model is available, the failure is stated plainly with a retry affordance.
• Continuation: The user retries routing or continues in Chat.

FR-15 — Coding help (explicit) As a Jarves User, I should get coding help, so that I can work through code problems with Jarves.

• Trigger/input: The user submits a coding request on Coding.
• Observable result: A coding response is rendered with monospace technical data and retained.
• Access state: Requires an established identity.
• Failure/recovery: A failed coding response is reported with a retry affordance and the request preserved.
• Continuation: The user continues the exchange or moves to Chat.

FR-16 — AI agents (explicit) As a Jarves User, I should invoke AI agents, so that multi-step work is carried out on my behalf.

• Trigger/input: The user invokes an agent on Agents.
• Observable result: The agent's live pulse is shown while it runs, and its output is presented as a verified result.
• Access state: Requires an established identity, plus any permission scope the agent requires through Permissions.
• Failure/recovery: An agent failure or a denied permission is reported with the reason.
• Continuation: The user retries the invocation, adjusts the request, or grants the required permission.

FR-17 — Tools and plugins (explicit) As a Jarves User, I should use tools and plugins, so that Jarves can act beyond plain conversation.

• Trigger/input: The user selects a tool or plugin on Agents.
• Observable result: The tool runs and its output is presented as a verified result.
• Access state: Requires an established identity, plus any permission scope the tool requires through Permissions.
• Failure/recovery: A tool failure or denied scope is reported with the reason.
• Continuation: The user retries, chooses another tool, or grants the required permission.

FR-18 — Media search (explicit) As a Jarves User, I should search media, so that I can find media items through Jarves.

• Trigger/input: The user submits a media search on Media.
• Observable result: Media results are presented as glass thumbnails with monospace metadata overlays.
• Access state: Requires an established identity.
• Failure/recovery: A failed search is reported with the reason; an empty result set prompts refinement.
• Continuation: The user refines the query or requests an edit.

FR-19 — Media editing agents (explicit) As a Jarves User, I should have agents edit media, so that I can produce edited media without leaving Jarves.

• Trigger/input: The user requests an agent-assisted edit on Media.
• Observable result: The edited output is presented and can be inspected.
• Access state: Requires an established identity, plus any permission scope the edit requires through Permissions.
• Failure/recovery: A failed edit is reported with the reason.
• Continuation: The user retries the edit, adjusts the request, or grants the required permission.

FR-20 — Phone control (explicit) As a Jarves User, I should control my phone through Jarves, so that device actions can be issued by voice or request.

• Trigger/input: The user issues a phone-control action on Phone.
• Observable result: The action executes and its outcome is reported.
• Access state: Requires an established identity, plus the relevant device permission scope through Permissions.
• Failure/recovery: A denied device permission or failed action is reported with the reason.
• Continuation: The user retries or grants the required permission.

FR-21 — Gallery search (explicit) As a Jarves User, I should search my gallery, so that I can find my own media through Jarves.

• Trigger/input: The user submits a gallery search on Phone.
• Observable result: Gallery results are presented as glass thumbnails with monospace metadata.
• Access state: Requires an established identity, plus gallery permission through Permissions.
• Failure/recovery: A denied gallery permission or failed search is reported with the reason; an empty result set prompts refinement.
• Continuation: The user refines the query or grants the required permission.

FR-22 — Supported app integrations (explicit) As a Jarves User, I should connect supported applications, so that Jarves can act inside the apps I already use.

• Trigger/input: The user connects a supported application on Integrations.
• Observable result: The connection is established and integrated actions become available; integrated actions return verified results.
• Access state: Requires an established identity, plus the connection's permission scopes through Permissions.
• Failure/recovery: A failed connection or denied scope is reported with the reason.
• Continuation: The user retries the connection, grants the required permission, or performs an integrated action.

FR-23 — Security and permissions (explicit) As a Jarves User, I should review and decide on permission scopes before actions execute, so that Jarves never acts on my device or accounts without my consent.

• Trigger/input: An action requires a scope; the glass consent sheet slides up from the bottom on Permissions with the scope listed in monospace.
• Observable result: The user chooses Allow once, Always, or Deny; the decision is recorded and the requesting action proceeds or is blocked accordingly.
• Access state: Requires an established identity.
• Failure/recovery: If the decision cannot be recorded, the action does not execute and the failure is stated plainly.
• Continuation: The user retries the decision; the requesting action remains blocked until a decision is recorded.

FR-24 — Permission checks and security validation before execution (required_inference) As a Jarves User, I should have permission checks and security validation run before any action executes, so that execution only happens against a recorded grant.

• Trigger/input: Any action that requires a scope is requested.
• Observable result: The action executes only when a valid grant exists; otherwise the consent sheet is presented and execution is held.
• Access state: Requires an established identity.
• Failure/recovery: A validation failure blocks execution and reports the reason.
• Continuation: The user grants the scope and retries, or abandons the action.

FR-25 — Verified results (required_inference) As a Jarves User, I should receive verified results for executable requests, so that I can trust that an action actually happened and an answer is actually grounded.

• Trigger/input: A tool, integration, agent, or research action completes.
• Observable result: The result is presented with its verification status — the verified badge on citations, and a stated outcome for executed actions.
• Access state: Requires an established identity.
• Failure/recovery: When a result cannot be verified, it is presented as unverified rather than as verified.
• Continuation: The user accepts the result, retries, or refines the request.

FR-26 — Backend APIs (explicit) As a Jarves Builder/Developer, I should have backend APIs, so that the client surfaces and the execution layer communicate through a defined interface.

• Trigger/input: A client surface issues a request.
• Observable result: The API returns the requested state or result, or a defined error.
• Access state: Requests carry the identity context of the authenticated user.
• Failure/recovery: API errors are returned as defined failures and surfaced to the user with a retry affordance where the surface supports it.
• Continuation: The client retries or reports the failure.

FR-27 — Multilingual support (explicit) As a Jarves User, I should use Jarves in my own language, so that I can speak and read in the language I think in.

• Trigger/input: The user selects an interaction language on Languages.
• Observable result: The preference is saved and applied to subsequent interaction, including voice input and answers.
• Access state: Requires an established identity.
• Failure/recovery: A failed save is reported with a retry affordance, and the previous preference remains in effect.
• Continuation: The user continues interacting in the selected language.

FR-28 — UI/UX themes (explicit) As a Jarves User, I should choose a UI/UX theme, so that the interface suits how I want to work.

• Trigger/input: The user selects a theme on Themes.
• Observable result: The theme is applied across the interface and saved to the user's identity.
• Access state: Requires an established identity.
• Failure/recovery: A failed save is reported with a retry affordance, and the previous theme remains applied.
• Continuation: The user continues working in the selected theme.

FR-29 — Phased development (explicit) As a Jarves Builder/Developer, I should build the small working version first and add later capabilities progressively, so that the roadmap constraint is honored.

• Trigger/input: A development phase begins.
• Observable result: Phase 1 delivers login, chat, voice in/out, speaker button, basic web research, citations, best answer, basic history, basic memory, and file upload; later phases add multi-AI routing, coding, agents, media editing, phone control, gallery search, and supported app integrations.
• Access state: Not applicable to end users.
• Failure/recovery: If a later-phase capability is not yet delivered, its surface is not presented as working.
• Continuation: The next phase proceeds on top of the working version.

FR-30 — Proposal-form roadmap (explicit) As a Jarves Builder/Developer, I should have the roadmap written as a proposal, so that the plan is reviewable before and during build.

• Trigger/input: The roadmap is produced.
• Observable result: The roadmap is presented in proposal form.
• Access state: Not applicable.
• Failure/recovery: Not applicable.
• Continuation: The roadmap guides phased development.

4. User Personas

Jarves User

Product context. The Jarves User is the end user who speaks or types to Jarves — "Jarves, ये क्या है?" — and expects it to understand and answer. They are multilingual (Hindi/English first) and mobile-heavy, and they expect the product to feel like a sci-fi instrument rather than a SaaS dashboard, while permissions and verified results must still read clearly.

Primary goal. To say Speak, Ask, Research, Create, Build, Control and have Jarves execute those requests with tools, permissions, and verified results.

Distinct accepted responsibilities. Asking questions by voice or chat; uploading files for intelligence and RAG; using web research with citations and a best answer; relying on memory and history; and, as phases land, invoking coding help, media search and editing, phone control, gallery search, and supported app integrations. The Jarves User is also the person who decides on permission scopes — the trust moment belongs to them, not to the system.

Relevant inputs and decisions. Spoken or typed queries; uploaded files; research queries; permission decisions (Allow once, Always, Deny); language selection; theme selection; choice of model routing outcome; choice of agent or tool.

Interactions with other accepted participants. The Jarves User is the sole human participant in the product's accepted journeys. Their counterparties are non-persona actors: external web sources, third-party AI models, connected applications, and the device's own phone and gallery subsystems. The Jarves User initiates every request, makes every consent decision, and receives every result.

Observable success. A spoken query is understood and answered; a researched answer arrives with a best answer and openable citations; an uploaded file informs an answer with retrieved chunks visible; a device or app action executes only after a recorded permission decision and returns a verified result; the conversation, memory, and files are still there on return.

Jarves Builder/Developer

Product context. The Jarves Builder/Developer is the person building Jarves through the phased roadmap. They start with a small working version and progressively expand it.

Primary goal. A working, progressively expanded voice-first AI OS.

Distinct accepted responsibilities. Delivering Phase 1 exactly as scoped — login, chat, voice in/out, speaker button, basic web research, citations, best answer, basic history, basic memory, file upload — and then adding multi-AI routing, coding, agents, media editing, phone control, gallery search, and supported app integrations. They also own the backend APIs that connect the client surfaces to the execution layer, and they must ensure that actions execute with tools, permissions, and verified results.

Relevant inputs and decisions. The phased roadmap; the phase boundary between the working version and later additions; the API contract between client surfaces and the execution layer; the permission and verification model that every executable action must pass through.

Interactions with other accepted participants. The Jarves Builder/Developer builds the surfaces the Jarves User uses, but does not act on the Jarves User's behalf and does not gain differentiated control or visibility over any individual user's conversation, memory, files, or permission grants.

Observable success. The small working version runs end to end, and each later phase lands on top of it without breaking it.

5. Core User Flows

Flow 1 — A visitor learns what Jarves is and enrolls (Jarves User)

1. The visitor arrives at Landing with no identity. The full-viewport dark stage composes: the WebGL voice orb dead-centre, breathing slowly, its outer ring in slow orbit; the wordmark JARVES with AI in outlined cyan stroke arcs above it; the muted line "बोलो — Jarves सुन रहा है।" sits beneath; the Speak pill capsule with a live waveform sits directly under the orb; the four verbs Speak · Ask · Research · Build run as a monospace HUD strip flush to the bottom viewport edge.
2. The visitor reads the hero and the verb strip to understand that Jarves is a voice-first AI OS for speaking, asking, researching, and building.
3. The visitor chooses Sign Up and submits enrollment details.
4. Observable result: the identity is created and the visitor enters the protected workspace. Next step: the visitor asks their first question.
5. Failure/recovery: if enrollment fails validation, the specific field or reason is reported inline and the entered values are preserved; the visitor corrects the issue and resubmits, or moves to Login.
6. Reduced-motion / fallback: if the hero subject cannot initialize, the static composed frame — wordmark, muted line, Speak capsule, verb strip — remains fully readable and operable, and enrollment is unaffected.

Flow 2 — A returning user logs in (Jarves User)

1. The returning user arrives at Login.
2. The user submits their credentials.
3. Observable result: identity is verified and the protected workspace opens with the user's conversations, memory, files, permissions, and preferences intact. Next step: the user resumes where they left off.
4. Failure/recovery: invalid credentials are reported inline without revealing which field failed; the form remains filled and resubmittable, and the user may move to Sign Up instead.

Flow 3 — The user asks by voice and hears the answer (Jarves User)

1. The authenticated user opens Voice. The orb is in its idle breathing pulse.
2. The user opens the mic. The orb expands into three concentric hairline rings and the waveform bars react to mic amplitude.
3. The user speaks: "Jarves, ये क्या है?" The query is captured as a live transcript.
4. Jarves moves to thinking — a thin cyan arc sweeps the orb — and then to answering, with the waveform rippling in sync with TTS.
5. Observable result: the answer is presented and spoken, and the turn is retained. Next step: the user asks a follow-up by voice, or toggles the speaker button to silence spoken output and continues in Chat.
6. Failure/recovery: if microphone access is denied, the glass consent sheet on Permissions presents the scope in monospace with the Allow once / Always / Deny capsule row; if the user denies, or capture fails, the reason is stated and typed input via Chat remains available.

Flow 4 — The user asks by typing (Jarves User)

1. The authenticated user opens Chat.
2. The user types a question in the composer and sends it.
3. Observable result: Jarves' answer is rendered in the centre conversation column and the turn is retained. Next step: the user continues the conversation, or opens the right HUD panel to inspect citations, memory hits, file chunks, and permissions attached to the answer.
4. Failure/recovery: a failed answer is reported in place of the response with a retry affordance, and the original question is preserved; the user retries, rephrases, or switches to Voice.

Flow 5 — The user researches and checks the citations (Jarves User)

1. The authenticated user opens Research and submits a research query.
2. Jarves performs the web research. While it works, the query is held and progress is indicated.
3. Observable result: a single best answer is presented ahead of the supporting citations. The citations render as a HUD timeline on a vertical hairline rail with numbered cyan nodes.
4. The user scrubs the citation timeline with scroll and expands a node into a glass card showing the domain, the timestamp, and a magenta verified badge.
5. Next step: the user accepts the answer, opens further citations, or refines the query.
6. Failure/recovery: if research fails or returns nothing usable, the surface says so plainly and offers retry; if no best answer can be determined, the available results are presented instead of an invented conclusion; if a citation cannot be resolved, its node states that plainly rather than showing a verified badge.

Flow 6 — The user uploads a file and asks against it (Jarves User)

1. The authenticated user opens Files and uploads a file.
2. Observable result: the file is accepted, indexed, and shown as a glass thumbnail with a monospace metadata overlay.
3. The user asks a question with the file available.
4. Jarves retrieves relevant chunks; the retrieved file chunks appear in the right HUD panel and inform the answer.
5. Next step: the user refines the question, uploads more material, or continues in Chat.
6. Failure/recovery: an unsupported, oversized, or failed upload is reported with the specific reason and the user retries or chooses a different file; if no relevant chunk is retrieved, the answer states that the files did not cover the question rather than fabricating a source.

Flow 7 — The user revisits history and memory (Jarves User)

1. The authenticated user opens History.
2. Observable result: prior conversations are listed with enough metadata to recognize them.
3. The user opens a conversation and continues it, or opens Memory to review what Jarves retained.
4. Observable result: retained memory items are listed, and memory hits are shown against responses in the right HUD panel.
5. Next step: the user uses the memory in a new conversation, or returns to History to revisit the conversation where it was formed.
6. Failure/recovery: a retrieval failure on either surface is reported with a retry affordance; an empty History or Memory explains the state and prompts the user to start a conversation.

Flow 8 — The user routes a query across models (Jarves User)

1. The authenticated user opens AI Router. The radial node map rests with the active model at the centre inside a luminous ring and candidate models orbiting it.
2. The user sends a query.
3. Observable result: routing is shown as light travelling along a 1px cyan path, and the chosen model's name and latency appear at the centre in JetBrains Mono.
4. Next step: the user continues in Chat with the routed answer.
5. Failure/recovery: if routing fails or no model is available, the failure is stated plainly with a retry affordance.

Flow 9 — The user gets coding help (Jarves User)

1. The authenticated user opens Coding and submits a coding request.
2. Observable result: a coding response is rendered with monospace technical data and retained.
3. Next step: the user continues the exchange or moves to Chat.
4. Failure/recovery: a failed coding response is reported with a retry affordance and the request preserved.

Flow 10 — The user invokes an agent or tool (Jarves User)

1. The authenticated user opens Agents and selects an agent or tool for a task.
2. If the agent or tool requires a scope, the glass consent sheet slides up from the bottom on Permissions, listing the scope in monospace (for example camera · gallery · contacts) with the Allow once / Always / Deny capsule row.
3. The user makes the decision. Observable result: the decision is recorded and the invocation proceeds or is blocked accordingly.
4. While the agent runs, its live pulse is shown.
5. Observable result: the agent completes and its output is presented as a verified result. Next step: the user continues in Chat or invokes another agent.
6. Failure/recovery: an agent failure or a denied permission is reported with the reason; the user retries the invocation, adjusts the request, or grants the required permission. If the decision cannot be recorded, the action does not execute and the failure is stated plainly.

Flow 11 — The user searches and edits media (Jarves User)

1. The authenticated user opens Media and submits a media search.
2. Observable result: media results are presented as glass thumbnails with monospace metadata overlays.
3. The user requests an agent-assisted edit. If the edit requires a scope, the consent sheet on Permissions presents it and the user decides.
4. Observable result: the edited output is presented and can be inspected. Next step: the user refines the query or requests another edit.
5. Failure/recovery: a failed search is reported with the reason and an empty result set prompts refinement; a failed edit is reported with the reason and the user retries, adjusts the request, or grants the required permission.

Flow 12 — The user controls the phone and searches the gallery (Jarves User)

1. The authenticated user opens Phone and issues a phone-control action, or submits a gallery search.
2. The relevant device permission scope is presented on Permissions as a glass consent sheet with the scope in monospace and the Allow once / Always / Deny capsule row.
3. The user makes the decision. Observable result: the decision is recorded and the action executes or is blocked accordingly.
4. Observable result: the action's outcome is reported, or gallery results are presented as glass thumbnails with monospace metadata. Next step: the user issues another action or refines the gallery query.
5. Failure/recovery: a denied device permission or failed action is reported with the reason; an empty gallery result set prompts refinement; the user retries or grants the required permission.

Flow 13 — The user connects a supported application (Jarves User)

1. The authenticated user opens Integrations and selects a supported application to connect.
2. The connection's permission scopes are presented on Permissions and the user decides.
3. Observable result: the connection is established and integrated actions become available.
4. The user performs an integrated action. Observable result: the action completes and returns a verified result. Next step: the user performs another integrated action or continues in Chat.
5. Failure/recovery: a failed connection or denied scope is reported with the reason; the user retries the connection or grants the required permission.

Flow 14 — The user sets language and theme (Jarves User)

1. The authenticated user opens Languages and selects the interaction language.
2. Observable result: the preference is saved and applied to subsequent interaction, including voice input and answers. Next step: the user speaks or types in the selected language.
3. The user opens Themes and selects a theme.
4. Observable result: the theme is applied across the interface and saved to the user's identity. Next step: the user continues working in the selected theme.
5. Failure/recovery: a failed save on either surface is reported with a retry affordance, and the previous preference or theme remains in effect.

Flow 15 — The builder delivers the phased roadmap (Jarves Builder/Developer)

1. The builder starts from the proposal-form roadmap.
2. The builder delivers the Phase 1 working version: login, chat, voice in/out, speaker button, basic web research, citations, best answer, basic history, basic memory, and file upload — with backend APIs connecting the client surfaces to the execution layer.
3. Observable result: the small working version runs end to end.
4. The builder then adds, progressively: multi-AI routing, coding help, AI agents, media search and editing agents, phone control, gallery search, and supported app integrations — each executable action passing through permission checks and security validation and returning verified results.
5. Next step: the next phase proceeds on top of the working version.
6. Failure/recovery: if a later-phase capability is not yet delivered, its surface is not presented as working.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. Muse: Gleb Kuznetsov — motion-first interface for future tech. Headline idea: a luminous instrument in deep space. JARVES is rendered as a voice-first AI OS that looks like a sci-fi instrument, not a SaaS dashboard, while citations, permissions, and verified results stay legible and serious through a monospace data layer.

Colour tokens — dark mode

Usage rules. The deep navy-black ground #05070E covers roughly 70% of every screen. Glass panels are #0C1222 at 70% opacity with a 1px rgba(0,229,255,0.18) luminous border. Electric cyan #00E5FF is the primary signal — the voice orb, active states, waveform, links, focus rings. Magenta #FF2FB3 is the hot accent, used sparingly and for one thing at a time: the recording state, the verified badge, an agent's live pulse. Body text is #EAF2FF on dark (contrast > 14:1). Secondary text and metadata use #7C8BA6 only at 14px+ or as uppercase micro-labels. Cyan and magenta text are never placed directly on each other. No blue-indigo (#2563EB family) appears anywhere.

Typography

• Headings: Space Grotesk — wide geometric grotesk. Uppercase for micro-labels at 11px with 0.18em tracking; mixed case for display at weight 500–700 with -0.02em tracking. Display headlines are large and airy, never condensed.
• Body: Space Grotesk.
• Numeric and technical data: JetBrains Mono at 12–13px with 0.06em tracking — citations, model names, token counts, permission scopes.
• Scale: 1.25 modular on a 4px baseline — 12 / 13 (mono) / 14 / 16 / 20 / 25 / 32 / 40 / 56 / 72.
• Applied sizes: hero display clamp(40px, 8vw, 88px); section headings clamp(28px, 4vw, 44px); body 16px/1.65; micro-labels 11px uppercase.

Shape language

Radial and orbital. A central voice orb (perfect circle, 220–360px) with 3 concentric hairline rings that expand on listening. Glass panels are rounded rectangles with 20px radius and a 1px luminous edge. Buttons are pill capsules with a soft inner glow, never a hard drop shadow. Thin 1px cyan strokes at 20–40% opacity draw connections between nodes (router diagram, agent graph). No blobs, no clip art, no photographic texture.

Layout

Full-bleed dark stage. The Landing hero is a full-viewport radial composition: the voice orb dead-centre, the headline arc-set above it, the four verbs pinned as a HUD row at the bottom edge. Inside the app: a persistent left rail (72px collapsed / 240px expanded) of thin luminous icons, a centre column for the conversation, and a right HUD panel that slides in for citations, memory hits, file chunks, and permissions. AI Router is a radial node map with the active model at the centre. Everything sits on a 4px grid; 24px gutters mobile, 40px desktop; content max-width 1200px, but the hero and the router deliberately bleed to the viewport edge.

Imagery

No stock photography. The imagery is the interface itself: a WebGL voice orb (icosahedron with a shader-driven noise displacement, cyan-to-magenta rim light), a particle field that reacts to voice amplitude, radial model-routing diagrams, thin-line HUD glyphs for tools and permissions, and a topographic-style waveform for the research/citation timeline. Files and media appear as glass thumbnails with monospace metadata overlays.

Readability guarantee

Headlines, wordmarks, labels, numbers, cards' text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration, and motion may be cropped, bled off an edge, rotated, overlapped, or cut as the direction asks, as long as they cover no readable text or control. Moving and scrollable content (the verb ticker, the citation rail) may cross the viewport edge by design; every item becomes fully readable as it passes. Under prefers-reduced-motion it stops and shows whole items, wrapping into rows or sitting in a horizontally scrollable row (overflow-x: auto).

7. Signature Design Concept

The orb is the product. The public entry is a full-viewport #05070E void. Dead centre sits a 280px WebGL orb of cyan light with a magenta rim — a noise-displaced icosahedron whose outer ring orbits slowly. It breathes when idle. The moment the mic opens, it expands into three hairline listening rings. Above it, the wordmark JARVES in Space Grotesk 500 at clamp(40px, 8vw, 88px), with AI in outlined cyan stroke. Beneath it, one line in 16px muted: "बोलो — Jarves सुन रहा है।" There is no sub-headline paragraph and no blue CTA button. A single pill capsule labelled Speak, with a live waveform inside it, sits directly under the orb. The four verbs SPEAK · ASK · RESEARCH · BUILD run as a monospace HUD ticker pinned flush to the bottom viewport edge, each lighting cyan as the orb enters that state — a status bar that doubles as navigation.

The type arcs around the orb; nothing is centred-and-stacked like a SaaS template. The orb is the hero, and the composition is radial rather than vertical. This concept recomposes only accepted content, states, and controls: the wordmark, the muted line, the Speak entry, the four verbs, and the orb's own idle/listening/thinking/answering states.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: webgl

Landing Hero Motion Brief

• Focal subject: the WebGL voice orb — a noise-displaced icosahedron with cyan-to-magenta rim light, dead-centre in a full-viewport #05070E void, its outer ring in a continuous slow 24s orbit.
• Input → transformation → outcome thesis: the mic opening is the input; the orb transforms from a single slow breathing pulse into three expanding hairline listening rings; the outcome is that the user's spoken query is captured as a live transcript and Jarves answers, with the waveform rippling in sync with TTS. The orb's state is the product's state — idle, listening, thinking, answering.
• Motion vocabulary: continuous slow orbit of the outer ring (24s); a light sweep across glass panels on entry; waveform bars that react to mic amplitude; scroll-scrubbed camera push into the router node map; a thin cyan arc that sweeps the orb while thinking; waveform ripples in sync with TTS while answering.
• Composed first frame: the void, the orb breathing at centre with its ring mid-orbit, the wordmark arc-set above, the muted line beneath, the Speak capsule with a live waveform directly under the orb, and the monospace verb ticker flush to the bottom edge — all readable and whole at 375px, 768px, and 1280px.
• Reduced-motion state: everything collapses to a static frame. The orb holds a single still pulse, the ring stops orbiting, the light sweep and scroll-scrubbed camera push are removed, and the verb ticker stops and shows whole items — wrapping into rows or sitting in a horizontally scrollable row whose further items are reached by scrolling.

Landing Hero 3D Scene Brief — DIRECTION-DERIVED

One crafted real-time object: a WebGL icosahedron with shader-driven noise displacement, lit with a cyan-to-magenta rim, surrounded by a particle field that reacts to voice amplitude. The scene shows the product's defining state — the orb breathing when idle, expanding into three hairline listening rings when the mic opens, swept by a thin cyan arc while thinking, and rippling in sync with TTS while answering. It sits on the deep #05070E ground with no other 3D content, and it degrades to the static composed frame under prefers-reduced-motion or when WebGL is unavailable.

9. Non-Functional Requirements

NFR-1 — Voice-first latency (explicit, from the voice-first vision) The voice loop must feel like an instrument: the transition from listening to thinking to answering must be perceptible as a continuous state change rather than a stall. Rationale: the product's core promise is that the user speaks and Jarves answers.

NFR-2 — Verified results (explicit) Actions must be executed with tools, permissions, and verified results. Any result that cannot be verified is presented as unverified rather than as verified. Rationale: explicit hard constraint in the source.

NFR-3 — Permission gating before execution (explicit) Permission checks and security validation run before actions are executed; an action with no recorded grant does not execute. Rationale: explicit hard constraint in the source.

NFR-4 — Multilingual interaction (explicit) The product supports multilingual interaction, with Hindi/English first. Voice input and answers must work in the user's selected interaction language. Rationale: explicit source requirement.

NFR-5 — Mobile-heavy use (explicit, from the stated audience) The interface must remain fully usable on mobile viewports, with the left rail collapsing to 72px and 24px gutters. Rationale: the stated audience is mobile-heavy.

NFR-6 — Readable text and controls at every viewport (explicit design constraint) Headlines, wordmarks, labels, numbers, cards' text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit, and no other element covers any part of them. Rationale: explicit design constraint.

NFR-7 — Reduced-motion support (explicit design constraint) All motion collapses to a static frame under prefers-reduced-motion; moving and scrollable content stops and shows whole items. Rationale: explicit design constraint.

NFR-8 — Contrast (explicit design constraint) Body text #EAF2FF on the dark ground holds contrast greater than 14:1. Secondary text and metadata use #7C8BA6 only at 14px+ or as uppercase micro-labels. Cyan and magenta text are never placed directly on each other. Rationale: explicit design constraint.

NFR-9 — Backend API boundary (explicit) Client surfaces and the execution layer communicate through backend APIs, with requests carrying the identity context of the authenticated user. Rationale: explicit source requirement.

NFR-10 — Identity-bound durable state (required_inference) Conversations, memory, uploaded files, permission grants, language preference, and theme preference are bound to the individual user identity and remain theirs across sessions. Rationale: required to make the accepted history, memory, file, and preference journeys executable.

NFR-11 — Phased delivery integrity (explicit) A later-phase capability that is not yet delivered is not presented as working. Rationale: explicit phasing constraint.

10. Tech Stack

• Frontend: React, with a WebGL/R3F hero subject for the voice orb as called for by the creative direction.
• Backend: Python / FastAPI, exposing the backend APIs that connect client surfaces to the execution layer.
• Storage: Appropriate persistent storage for user identity, conversations, memory items, uploaded files and their indexed chunks, permission grants, and preferences.
• Containerization: Docker and docker-compose for local and service composition.
• Orchestration: Kubernetes only when deployment requires it.

11. Assumptions and Constraints

Constraints (explicit, binding).

• Development must proceed in phases: a small working version first (login, chat, voice in/out, speaker button, basic web research, citations, best answer, basic history, basic memory, file upload), then progressively add multi-AI, coding, agents, media editing, phone control, gallery search, and supported app integrations.
• Actions must be executed with tools, permissions, and verified results.
• The roadmap must be written as a proposal.

Assumptions (narrow, labeled).

• [Assumption] The user's identity is established by self-service enrollment on Sign Up or returning verification on Login, because no invitation, provisioning, provider, or pre-existing-account boundary is established for the Jarves User.
• [Assumption] Every destination other than Landing, Login, and Sign Up requires an established identity, because conversation, memory, file, permission, language, and theme state are bound to the individual user.
• [Assumption] External web sources, third-party AI models, connected applications, and the device's phone and gallery subsystems are provider- or device-owned; Jarves owns the request, the permission gate, and the verified result it presents.
• [Assumption] The Jarves Builder/Developer does not gain differentiated control or visibility over any individual user's conversation, memory, files, or permission grants; no role-based permission model is established by the source.
• [Default — not specified by user] React and Python/FastAPI are used for the client and backend, with Docker/docker-compose for composition and Kubernetes only if deployment requires it.
• [Default — not specified by user] Persistent storage is used for identity, conversations, memory, files and indexed chunks, permission grants, and preferences.

Exclusions.

• No account-management, billing, social, or administrative capabilities beyond the enrollment and verification needed to reach protected state.
• No stock photography, illustrated characters, or emoji-as-icons.
• No blue-indigo (#2563EB, #4F46E5, #6366F1 family) anywhere, and no blue-on-white SaaS template look.
• No Inter, Roboto, Arial, Helvetica, Poppins, or system-ui for headings or body.
• No dense spreadsheet-style tables for citations, memory, or file chunks — the HUD rail is used instead.
• No bouncy spring easing, confetti, or playful micro-animations on permission and verification surfaces.

12. Glossary

• Jarves — the voice-first AI OS described in this document.
• Jarves User — the end user who speaks or types to Jarves and expects it to understand and answer.
• Jarves Builder/Developer — the person building Jarves through the phased roadmap.
• Voice orb — the central WebGL hero object and the visual representation of Jarves' voice state (idle, listening, thinking, answering).
• HUD panel — the right-hand panel that slides in for citations, memory hits, file chunks, and permissions.
• HUD rail — the vertical hairline rail on which citations render as numbered cyan nodes.
• Best answer — the single answer presented ahead of supporting citations for a research query.
• Citation — a source reference rendered as a HUD node expanding into a glass card with domain, timestamp, and verified badge.
• Verified result — a result presented with its verification status, including the magenta verified badge on citations and a stated outcome for executed actions.
• Permission scope — a named capability (for example camera · gallery · contacts) that must be granted before an action executes.
• Consent sheet — the glass sheet that slides up from the bottom presenting permission scopes with the Allow once / Always / Deny capsule row.
• Multi-AI router — the radial node map that routes a query across candidate models and names the chosen model with its latency.
• Agent — an AI worker invoked on Agents whose live pulse is shown while it runs and whose output is presented as a verified result.
• Tool / plugin — an executable capability invoked on Agents beyond plain conversation.
• RAG — retrieval-augmented generation; the mechanism by which uploaded file chunks inform an answer.
• Phase 1 working version — the small first release: login, chat, voice in/out, speaker button, basic web research, citations, best answer, basic history, basic memory, file upload.
• HUD ticker — the monospace strip of the four verbs SPEAK · ASK · RESEARCH · BUILD pinned to the bottom edge of the hero, doubling as status and navigation.