# Iris Domain — Feature Reference

Iris is the Universal Intelligent Assistant Platform of the Oshun ecosystem. It
delivers AI conversation powered by multiple language models, deep
personalization through a four-tier hierarchical memory architecture (core,
working, archival, episodic), autonomous agents capable of using tools and
delegating to each other, knowledge base integration with cited retrieval, and
full multimodal interaction across text, voice, vision, and spatial computing.
Iris is purpose-built for both individual productivity and enterprise
deployment: it works equally well as a personal AI companion on a smartwatch, a
corporate knowledge assistant in Microsoft Teams, or a code intelligence engine
embedded in a developer's editor. Critically, Iris runs models on any hardware —
from local Ollama instances for air-gapped deployments to frontier models like
Claude and GPT-4 for maximum capability — with intelligent routing that selects
the right model for every task automatically.

**Library prefix:** `@iris/*` | **258 library packages** under `libs/iris/**`
(45 cluster directories) and **11 application packages** under `apps/iris/**`.
Iris is partially implemented: the fully built-out, verifiable pieces are
`@iris/types`, the `@iris/api` Hono service, `@iris/conversation-core`,
`@iris/conversation-orchestration`, the `@iris/agents` catalog, and
`@iris/core`/`@iris/config`. Many leaf packages exist as Nx scaffolds. Features
below describe the product surface; consult `DOMAINS/iris/specifications.md` for
what is verified in code today.

---

## 1. Platform Access

Iris is available on every major platform, surface, and device form factor so
users encounter a consistent AI experience regardless of where they work.

### 1.1 Applications

| Application          | Platform                      | Description                                                     |
| -------------------- | ----------------------------- | --------------------------------------------------------------- |
| **Web App**          | Browser (React)               | Full-featured interface with conversation management and search |
| **Desktop App**      | Windows / Mac / Linux (Tauri) | Native desktop assistant with system-level integration          |
| **Mobile App**       | iOS / Android (React Native)  | On-the-go AI assistance with voice and camera integration       |
| **Wearable App**     | Smartwatches                  | Quick AI interactions from the wrist with glanceable responses  |
| **XR App**           | VR/AR headsets (WebXR)        | Spatial AI assistant in extended reality environments           |
| **Dashboard**        | Browser                       | Administration, analytics, and team management                  |
| **Developer Portal** | Browser                       | API documentation, key management, and interactive playground   |
| **Marketplace**      | Browser                       | Browse, install, and rate AI agents, plugins, and integrations  |
| **API Service**      | Server                        | REST, WebSocket, and gRPC APIs for programmatic access          |

### 1.2 Interface Elements

| Element               | Description                                                             |
| --------------------- | ----------------------------------------------------------------------- |
| **Conversation List** | Sidebar listing all past conversations with inline search               |
| **Agent Selector**    | Dropdown to choose which AI agent configuration to use for a session    |
| **Message Input**     | Text entry field with file attachment button and voice input toggle     |
| **Streaming Display** | AI responses render token by token as they are generated                |
| **Knowledge Panel**   | Side panel for browsing, uploading, and managing knowledge collections  |
| **Settings**          | Memory management, privacy controls, and model preference configuration |

### 1.3 Keyboard Shortcuts

| Shortcut        | Action                                     |
| --------------- | ------------------------------------------ |
| `Enter`         | Send message                               |
| `Shift + Enter` | New line within message                    |
| `Ctrl/Cmd + N`  | Start a new conversation                   |
| `Ctrl/Cmd + K`  | Open quick search across all conversations |
| `Escape`        | Stop the current generation                |
| `Ctrl/Cmd + Up` | Edit the last sent message                 |
| `Ctrl/Cmd + /`  | Show keyboard shortcut reference           |

---

## 2. AI Conversations

The core of Iris is natural, context-aware, multi-turn AI conversation with rich
formatting, file understanding, and deep conversational intelligence.

### 2.1 Conversation Management

- **Create conversations**: Start new conversations on any topic with a single
  click or keyboard shortcut. Each conversation maintains independent context so
  multiple simultaneous threads do not bleed into each other.
- **Conversation history**: Permanent, searchable record of all past
  conversations. Past conversations load instantly for reference or continuation
  months later.
- **Auto-generated titles**: The system infers a descriptive title from the
  first message exchange, eliminating manual naming while keeping the list
  navigable.
- **Custom titles**: Override auto-generated titles with any custom name for
  long-lived conversations.
- **Full-text search**: Search across conversation titles and full message text
  simultaneously, returning results from any point in history.
- **Conversation export**: Export individual conversations as Markdown (for
  documentation), JSON (for programmatic use), or PDF (for sharing with people
  outside the platform).
- **Conversation branching**: Fork a conversation at any message to explore an
  alternative direction without losing the original thread — useful when a
  conversation reaches a decision point with multiple viable paths.
- **Conversation deletion**: Delete individual conversations or bulk-delete
  history with confirmation.

### 2.2 Message Features

- **Real-time streaming**: AI responses appear token by token as they are
  generated — no waiting for the full response before reading begins.
- **Message editing**: Edit any sent message and regenerate the AI's response
  from that point, effectively revising the conversation history in place.
- **Response regeneration**: Request a different response to the same message
  without editing the input — useful for exploring alternative phrasings or
  approaches.
- **One-click copy**: Copy any complete message or individual code block with a
  single click.
- **File attachments**: Attach documents, images, code files, and data files for
  the AI to analyze and reference in its response.
- **Syntax-highlighted code blocks**: Code responses are automatically formatted
  with language-specific syntax highlighting and a copy button.
- **Markdown rendering**: Full rich-text rendering of headings, lists, nested
  lists, tables, bold, italic, links, and blockquotes.
- **LaTeX support**: Mathematical equations written in LaTeX notation are
  rendered as formatted formulas inline.
- **Citation links**: When the AI draws on knowledge base documents, it includes
  inline citations that link directly to the source document, page, and section.
- **Stop generation**: Halt the AI's response at any point mid-generation.

### 2.3 Supported File Attachments

| Category      | Formats                            | Max Size |
| ------------- | ---------------------------------- | -------- |
| **Documents** | PDF, DOCX, TXT, Markdown           | 25 MB    |
| **Code**      | Python, JS, TS, Go, Rust, and more | 10 MB    |
| **Data**      | CSV, JSON, XLSX                    | 50 MB    |
| **Images**    | PNG, JPG, GIF, WebP                | 20 MB    |
| **Slides**    | PPTX                               | 25 MB    |

### 2.4 Conversation Intelligence

- **Context coreference resolution**: The system tracks pronouns and references
  across turns ("it", "that approach", "the earlier example") so the AI always
  knows what the user is referring to, even several messages later.
- **Intent classification**: Each user message is classified into a semantic
  intent category (question, task request, clarification, follow-up) to route to
  the most appropriate response strategy.
- **Slot filling**: When a request requires multiple pieces of information, the
  system identifies what is already provided and asks targeted clarifying
  questions for the missing values rather than making assumptions.
- **State machine dialogue management**: Conversations follow configurable state
  machines with guard conditions, ensuring coherent multi-step interactions such
  as onboarding flows or structured workflows.

---

## 3. AI Model Selection and Routing

Iris provides intelligent access to multiple AI models and automatically selects
the best one for each task, balancing quality, cost, and speed — without
requiring users to understand or choose models manually.

### 3.1 Available Models

| Provider      | Models                                 | Strengths                        |
| ------------- | -------------------------------------- | -------------------------------- |
| **Anthropic** | Claude (Opus, Sonnet, Haiku)           | Deep analysis, reasoning, safety |
| **OpenAI**    | GPT-4, GPT-4 Turbo, GPT-4o             | Versatility, creative writing    |
| **Google**    | Gemini (Pro, Ultra, Flash)             | Very long context, multimodal    |
| **Cohere**    | Command R+                             | Embeddings, search, reranking    |
| **Mistral**   | Mistral Large, Mistral Medium, Mixtral | Fast inference, multilingual     |
| **Local**     | Ollama (Llama 3, Mistral, Phi, Gemma)  | Privacy, offline use, zero cost  |

### 3.2 Intelligent Model Routing — `@iris/model-routing`

Model routing automatically selects the appropriate model for each request based
on declared task requirements, without requiring the user to choose:

- **Task-based routing**: Different task types (code generation, creative
  writing, factual Q&A, analysis, long-document reasoning) are routed to the
  model with the strongest track record for that category.
- **Cost optimization**: Routes to the most cost-effective model that satisfies
  the quality threshold for the task — uses a smaller, cheaper model when a
  frontier model is unnecessary.
- **Latency optimization**: In interactive sessions, routing can prioritize
  faster models when response speed matters more than maximum quality.
- **Fallback chains**: If the primary model is unavailable (API error, rate
  limit, outage), the system automatically retries with the next model in the
  fallback chain, transparent to the user.
- **Circuit breaking**: When a provider experiences sustained high error rates,
  the circuit breaker temporarily stops routing to that provider to prevent
  cascading failures.
- **Provider health monitoring**: Continuous health checks track each model
  provider's availability, latency, and error rate to inform routing decisions
  in real time.
- **Manual override**: Users can explicitly select a specific model for any
  conversation, bypassing automatic routing.

### 3.3 Multi-Model Ensemble — `@iris/ensemble`

The ensemble system queries multiple models and combines their outputs for
higher-confidence responses, particularly valuable for factual questions where
accuracy is paramount:

- **Ensemble voting**: Send the same request to multiple models and use a voting
  mechanism to determine the consensus answer.
- **Response aggregation**: Combine distinct insights from multiple model
  responses into a single synthesized answer, drawing on the strengths of each
  model.
- **Confidence scoring**: Each model response includes a confidence estimate
  that influences how heavily it is weighted in the final aggregated output.
- **Self-consistency checks**: For complex reasoning tasks, generate multiple
  independent reasoning chains and select the answer that appears most
  consistently across them.

### 3.4 Model Failover — `@iris/failover`

- **Automatic failover**: When any model provider fails, the failover system
  switches to the next available provider in the configured chain without any
  user-facing interruption.
- **Failover history**: Records of every provider failure and failover event for
  reliability analysis and SLA reporting.

---

## 4. Memory System

Iris remembers users across conversations through a **four-tier, MemGPT-inspired
memory architecture** — `core`, `working`, `archival`, and `episodic` (the
`MemoryTier` enum in `@iris/types`). Each tier operates at a different timescale
and scope, together providing continuity from the current turn to the user's
entire relationship with Iris.

The tiers form a pyramid from fastest to slowest access: core memory is always
in context, working memory covers the active session, archival memory is a
searchable long-term store of durable facts, and episodic memory is a
time-ordered event log of what happened across conversations. When Iris
assembles a response, the context assembler allocates a token budget across all
four tiers (default: core 15%, working 40%, archival 30%, episodic 15%) and
truncates the lowest-priority chunks when the budget is exceeded.

### 4.1 Core Memory — `@iris/memory-core`

Core memory holds essential identity and persona information that is always kept
in the model's context window:

- **Persona, user, system, goals blocks**: Core memory is divided into
  `CoreMemorySection` blocks (`persona`, `user`, `system`, `goals`), each with a
  token budget that is enforced against a total budget.
- **Always in context**: Unlike searchable tiers, core memory blocks are
  injected into every turn so the assistant never loses its persona or the key
  facts it has been told.
- **Block update operations**: Blocks support `replace`, `append`, `prepend`,
  and `insert` edits.

### 4.2 Working Memory

Working memory covers the current session's active context and recent
interactions:

- **Active task context**: The AI maintains an understanding of what task is
  currently being worked on across multiple conversational exchanges — for
  example, "we are refactoring this function" persists across back-and-forth
  questions.
- **Relevance and recency scoring**: Each working-memory entry carries
  `relevance`, `recency`, and `accessCount` scores; a configurable decay rate
  and relevance threshold prune low-value entries.
- **Bounded and TTL'd**: Working memory is capped by entry count and token
  budget, with an optional TTL (the default working-memory config expires
  entries after one hour).
- **Temporary state storage**: Session-scoped state that persists until the
  session ends, protecting ephemeral information from permanent storage.

### 4.3 Archival Memory — `@iris/memory-core` / `@iris/memory-persistence`

Archival memory is the long-term, searchable store of durable facts and
preferences about the user:

- **User preferences**: Communication style, preferred response format (bullet
  points vs. prose), programming language preferences, and domain-specific
  preferences learned over time.
- **Explicit teaching**: Users can directly instruct Iris to remember specific
  information ("Remember that I prefer TypeScript over JavaScript"); the system
  acknowledges and confirms storage.
- **Confidence scoring**: Each memory carries a confidence score that increases
  when the same information is observed multiple times across conversations.
- **Source attribution**: Every long-term memory record links back to the
  specific conversation that created it, enabling traceability and manual
  verification.
- **Manual memory management**: Users can view all stored memories, edit
  incorrect ones, and delete memories they no longer want retained.

- **Vector-backed semantic retrieval**: Archival entries carry an optional
  embedding (default model `text-embedding-3-small`, 1536 dimensions) so they
  are found by conceptual similarity rather than keyword match. Search results
  are tagged `semantic`, `keyword`, or `hybrid`.
- **Entity extraction**: Archival entries can carry extracted `EntityReference`
  links, building an incremental graph of the user's projects, colleagues, and
  domain knowledge.
- **Importance scoring**: Each entry carries an importance level (`critical`,
  `high`, `medium`, `low`, `trivial`); search and context assembly weight
  entries by importance.

### 4.4 Episodic Memory — `@iris/memory-episodic`

Episodic memory stores time-ordered events and significant past interactions,
functioning as Iris's record of the user's history:

- **Time-ordered event log**: Episodic entries record typed events
  (`conversation_start`, `conversation_end`, `milestone`, `decision`,
  `learning`, `preference_change`, `goal_update`, `context_switch`, and more)
  with timestamps.
- **Conversation summaries**: Important conversations are summarized and stored
  as episodic memories, capturing key decisions, discoveries, and outcomes.
- **Emotional context**: Episodic entries can carry an `EmotionState`
  (valence/arousal/dominance) so the assistant can recall how an interaction
  felt, not just what happened.
- **Milestone tracking**: Significant accomplishments are flagged so Iris can
  acknowledge progress over time.

### 4.5 Context Assembly

The four tiers are assembled into a single LLM context window under a token
budget. The default memory-context configuration allocates the budget across
tiers (core 15%, working 40%, archival 30%, episodic 15%) and truncates the
lowest-priority chunks when the budget is exceeded.

### 4.6 Memory Operations

The `libs/iris/memory/` cluster (22 packages) provides the supporting
operations:

- **Memory consolidation** (`@iris/memory-consolidation`): Working-tier memories
  are processed and promoted into longer-lived storage — analogous to how sleep
  consolidates human memories.
- **Tier transitions** (`@iris/memory-transitions`): Manages promotion and
  demotion of memories between tiers.
- **Memory persistence** (`@iris/memory-persistence`): Cross-session persistence
  of memory records.
- **Memory retrieval** (`@iris/memory-retrieval`): Retrieval that injects
  contextually relevant memories into the prompt for each conversation turn.
- **Memory visualization** (`@iris/memory-visualization`): An interface showing
  the user's memory graph — what Iris knows and where it came from.
- **Memory debugging** (`@iris/memory-debugging`): Developer tools for
  inspecting which memories were retrieved for a given turn.
- **Memory sharing** (`@iris/memory-sharing`): Selective sharing of memory
  contexts — e.g. sharing a project knowledge base across a team while keeping
  personal preferences private.
- **Memory migration** (`@iris/memory-migration`): Import and export of memory
  packages for account transfers, backups, or moving between Iris instances.
- **Memory analytics** (`@iris/memory-analytics`): Aggregate statistics over the
  memory tiers.

---

## 5. Knowledge Base

Upload documents and let Iris search them to provide informed, cited answers
grounded in your specific content rather than general training knowledge.

### 5.1 Document Management — `@iris/knowledge`

- **Document upload**: Upload PDFs, Word documents (DOCX), Markdown files, plain
  text, code files, CSV, JSON, and HTML pages.
- **Bulk upload**: Upload entire folders of documents simultaneously with a
  progress indicator.
- **Collection organization**: Group related documents into named collections
  (e.g., "Company Policies", "API Documentation", "Research Papers") for
  organized retrieval.
- **Tagging**: Apply custom tags to documents for cross-collection filtering and
  organization.
- **Version control**: Upload updated versions of existing documents. The system
  detects content changes and re-indexes modified sections, preserving the full
  version history.

### 5.2 Knowledge Retrieval

- **Semantic search**: Meaning-based search that finds relevant passages by
  conceptual similarity rather than exact keyword matches — searching "how do
  users log in" will find passages about "authentication flow" even without
  those exact words.
- **Hybrid retrieval**: Combines vector-based semantic search with traditional
  BM25 keyword matching (a probabilistic relevance ranking algorithm), then
  merges and reranks results for the best of both approaches.
- **Automatic chunking**: Documents are intelligently split into overlapping
  chunks at natural boundaries (paragraph, section, sentence) sized to fit
  within the LLM's context window.
- **Citation engine**: Every AI response that draws on a knowledge base document
  includes inline citations identifying the document, section, and page number.
  Citations are clickable, jumping to the source passage.
- **Knowledge graph**: Entities and relationships extracted from documents are
  linked into a graph — a question about "how Product X relates to Service Y"
  can traverse these links even if no single document mentions both.
- **Real-time knowledge**: Access to current information through web search
  integration for questions that require data beyond the knowledge base.
- **Knowledge freshness detection**: The system flags documents that appear
  outdated based on date references and conflicting information, prompting the
  user to upload updated versions.

### 5.3 Knowledge Sources

| Source Type   | Description                                                          |
| ------------- | -------------------------------------------------------------------- |
| Manual upload | One-time document uploads via drag-and-drop or file browser          |
| Sync source   | Scheduled synchronization from external systems (Confluence, Notion) |
| API source    | Programmatic content updates via the Iris REST API                   |
| Real-time web | Live web search for current information beyond uploaded content      |

### 5.4 Enterprise Knowledge Features

- **Team knowledge bases**: Shared knowledge bases accessible to all members of
  an organization or team.
- **Access control**: Fine-grained permissions determining which users or roles
  can view, edit, and delete knowledge documents.
- **Knowledge analytics**: Track which documents are most frequently retrieved,
  identifying the highest-value knowledge assets.
- **Grounding**: Configure the AI to answer only from the knowledge base and
  refuse to speculate beyond it — critical for regulated industries or customer
  support accuracy requirements.
- **Personal knowledge base**: Private knowledge bases visible only to the
  individual user, separate from team-shared content.

---

## 6. AI Agents and Tool Use

Specialized AI agents designed for particular task domains, capable of using
tools, browsing the web, executing code, and coordinating with other agents.
Agents extend conversational AI into autonomous task execution.

### 6.1 Built-In Agents — `@iris/agents`

| Agent          | Specialty                                                                  |
| -------------- | -------------------------------------------------------------------------- |
| **General**    | Everyday questions, writing assistance, brainstorming, and learning        |
| **CodeAssist** | Programming, debugging, code review, and architecture recommendations      |
| **Researcher** | Deep research synthesis, source evaluation, and fact verification          |
| **Writer**     | Long-form content creation, editing, copywriting, and style adaptation     |
| **Analyst**    | Data analysis, report generation, trend identification, insight extraction |
| **Support**    | Customer support responses, FAQ drafting, and ticket triage                |
| **Creative**   | Creative writing, ideation, and artistic concept generation                |
| **Operations** | DevOps automation, infrastructure review, monitoring, runbook execution    |
| **Supervisor** | Coordinates multi-agent workflows and reviews outputs for quality          |

### 6.2 Agent Capabilities

- **Task decomposition**: When given a complex goal, agents automatically break
  it into a sequence of manageable sub-tasks and create an execution plan before
  starting.
- **Plan generation**: Agents generate an explicit step-by-step plan with a
  confidence estimate before beginning multi-step tasks, allowing the user to
  review and modify the plan.
- **Tool use**: Agents can invoke registered tools — file operations, web
  search, code execution, API calls — to gather information and take actions
  during task execution.
- **Multi-agent collaboration**: Multiple specialized agents can collaborate on
  tasks too complex for any single agent. The Supervisor agent coordinates
  handoffs and merges outputs.
- **Proactive suggestions**: Based on context and usage patterns, agents
  proactively suggest relevant next steps, related queries, or potentially
  useful resources.
- **Workflow automation**: Define reusable workflows (sequences of agent steps
  with conditional branches) that execute automatically when triggered.

### 6.3 Agent Tools

| Tool Category    | Available Tools                                                   |
| ---------------- | ----------------------------------------------------------------- |
| **File ops**     | Read, write, search, rename, and organize files on disk           |
| **Web ops**      | Browse URLs, perform web searches, extract structured data        |
| **Code exec**    | Execute code in sandboxed environments, capture output, run tests |
| **API ops**      | Make REST, GraphQL, and gRPC API calls with authentication        |
| **Database ops** | Query databases, inspect schemas, run read-only analysis          |
| **GUI ops**      | Click UI elements, fill forms, take screenshots (computer use)    |

### 6.4 Agent-to-Agent Protocol (A2A) — `@iris/a2a`

`@iris/a2a` is a private, unmounted compatibility prototype. It does not expose
the current A2A wire protocol and is not evidence of external interoperability;
ADR-0091 defers adoption until a named independent agent boundary exists. Its
local experiments model concepts used by internal multi-agent workflows:

- **Agent registry**: A central registry where agents advertise their
  capabilities so the Supervisor knows which agents can handle which tasks.
- **Agent communication**: Agents send structured messages to each other,
  sharing partial results and requesting assistance without human involvement.
- **Task delegation**: A generalist agent can delegate a specialized sub-task to
  the best-equipped specialist agent and collect the result asynchronously.
- **Result aggregation**: The Supervisor agent collects partial outputs from
  multiple agents and synthesizes a unified, coherent final response.

### 6.5 Model Context Protocol (MCP) — `@iris/mcp`

MCP (Model Context Protocol) is an industry standard for connecting AI systems
to external tools and data sources. Iris has both server and client MCP
capabilities:

- **MCP server**: Iris exposes its own capabilities (memory, knowledge base,
  conversation history) as an MCP server so external AI clients like Claude Code
  can access them.
- **MCP client**: Iris connects to external MCP servers to acquire additional
  tools — for example, connecting to a company's internal MCP server that
  exposes CRM data.
- **Standard protocol compatibility**: Compatible with the broader MCP
  ecosystem, allowing third-party MCP tools to be used in Iris conversations
  with no custom integration code.

### 6.6 Computer Use — `@iris/sandbox`

The computer use system enables agents to operate a sandboxed web browser during
conversations:

- **Sandboxed Chromium**: A fully isolated headless Chromium browser that the
  agent controls during a session. The sandbox prevents the agent from accessing
  anything outside the designated browser session.
- **Observe-Reason-Act loop**: The agent takes a screenshot, asks the LLM what
  to do based on the screen content, executes the decided action, verifies the
  result, and repeats until the task is complete.
- **Action types**: Click, type text, navigate to URLs, scroll pages, select
  from dropdowns, upload files, download files.
- **Action safety validation**: Every action is checked against safety rules
  before execution. High-risk actions (form submissions, purchases, deletions)
  require explicit human confirmation.
- **Maximum iteration limit**: Configurable maximum of 50 actions per task to
  prevent runaway automation loops.

---

## 7. Code Intelligence

Specialized capabilities for developers and engineering teams, providing an
AI-powered development environment that understands code at both the line and
architectural levels.

### 7.1 Code Features — `libs/iris/code/*`

The code-intelligence capability is a cluster of packages under
`libs/iris/code/` (`@iris/code-generation`, `@iris/code-review`,
`@iris/code-explanation`, `@iris/code-understanding`, `@iris/code-architecture`,
and others) — there is no single `@iris/code` package.

- **Code generation**: Generate complete functions, classes, modules, or entire
  files from natural language descriptions. Generates idiomatic code in the
  target language and follows project conventions when given context.
- **Code explanation**: Explain what existing code does in plain language — from
  individual lines to entire modules — with varying levels of technical depth.
- **Code review**: Automated code review identifying bugs, security
  vulnerabilities, performance issues, and deviations from best practices, with
  specific line-level feedback.
- **Code debugging**: Identify the root cause of bugs from error messages, stack
  traces, or unexpected output, with suggested corrections and explanations.
- **Code refactoring**: Suggest and apply refactoring improvements — extract
  functions, simplify conditionals, remove duplication — with before/after
  comparison.
- **Test generation**: Generate unit tests with appropriate edge cases and
  assertions for existing functions, targeting the testing framework used in the
  project.
- **Documentation generation**: Create JSDoc comments, docstrings, README
  sections, and inline comments from code.
- **Architecture advice**: Guidance on system design patterns, module
  organization, API design, and architectural tradeoffs.

### 7.2 Codebase Understanding

- **Repository analysis**: Analyze an entire code repository to understand its
  structure, key modules, entry points, and overall architecture.
- **Dependency mapping**: Map out package dependencies, internal module
  dependencies, and their relationships to understand coupling and the impact of
  changes.
- **Semantic code search**: Search a codebase by meaning — "find where user
  authentication happens" — rather than just text matching.
- **Static analysis**: Identify potential issues in code without running it —
  dead code, unreachable branches, type inconsistencies, and common error
  patterns.

---

## 8. Voice Interaction

Speak to Iris naturally for hands-free AI assistance across all supported
platforms, with support for continuous conversation, wake words, and
multi-language recognition.

### 8.1 Voice Features — `@iris/voice`

- **Voice input**: Speak messages instead of typing. Real-time transcription
  appears as speech is recognized, with the final message sent on a detected
  pause.
- **Voice response synthesis**: AI responses are read aloud using high-quality
  neural text-to-speech with natural prosody and emotional expressiveness.
  Multiple voice profiles are available.
- **Continuous voice conversation**: Hold a natural back-and-forth voice
  conversation with turn detection — the system knows when the user has finished
  speaking and responds promptly without requiring a button press.
- **Wake word detection**: On desktop and mobile, activate Iris by saying a
  configurable wake word without pressing any button.
- **Multi-language voice**: Voice input recognition and output synthesis
  available in dozens of languages, with automatic language detection.
- **Voice commands**: Perform navigation actions ("New conversation", "Stop",
  "Copy that") with voice commands while keeping hands free.
- **Voice shortcuts**: Define custom voice trigger phrases for frequently used
  actions or common queries.

### 8.2 Voice Customization

- **Voice profile selection**: Choose from multiple synthesized voice profiles
  varying in gender presentation, accent, warmth, and age.
- **Speaking rate control**: Adjust the playback speed of AI voice responses
  from 0.5x to 2.0x to match comprehension preference.
- **Tone adaptation**: The AI adjusts spoken delivery (formal, casual,
  empathetic, energetic) based on the conversation context and user preference
  settings.

### 8.3 Accessibility Voice Features

The voice interface serves as a complete primary interaction mode for users with
motor disabilities or visual impairments. It supports full application
navigation by voice — including searching conversations, starting new
conversations, and accessing settings — not just message input.

---

## 9. Vision and Multimodal

Iris can understand images, analyze documents visually, and interact with
extended reality environments, making it useful for any task where visual
context matters.

### 9.1 Vision Features — `libs/iris/multimodal/vision/*`

Vision is a cluster under `libs/iris/multimodal/vision/`
(`@iris/multimodal/vision` plus `@iris/vision-understanding`,
`@iris/vision-documents`, `@iris/vision-diagrams`, `@iris/vision-screenshare`,
and others) — there is no single `@iris/multimodal` package.

- **Image analysis**: Upload any image for AI analysis — the AI describes it,
  answers questions about its content, extracts information, or compares it to
  other images.
- **Screenshot analysis**: Take a screenshot of any screen for the AI to
  analyze, enabling natural-language Q&A about visible software, errors, or
  interfaces.
- **Document scanning**: Capture paper documents with a camera for extraction
  and analysis — forms, receipts, notes, whiteboards.
- **Diagram understanding**: The AI understands charts (bar, line, pie,
  scatter), diagrams (flowcharts, UML, network diagrams), and visual data
  without requiring manual data extraction first.
- **OCR (Optical Character Recognition)**: Extract text from images of
  documents, street signs, handwritten notes, and screenshots.

### 9.2 Spatial Interaction (XR)

- **Spatial AI assistant**: In XR environments (Meta Quest, Vision Pro, WebXR
  browsers), Iris appears as a spatial entity the user can interact with through
  gaze, voice, and gesture.
- **Gesture control**: Navigate the Iris interface and trigger actions with hand
  gestures in XR environments.
- **Spatial pinning**: Pin AI responses to specific locations in augmented
  reality — for example, pinning assembly instructions next to the physical
  component they describe.
- **3D object recognition**: In AR, the AI can identify and discuss real-world
  objects visible through the headset's cameras.

### 9.3 Brain-Computer Interface (BCI) — `@iris/bci`

- **BCI input support**: Experimental support for commercially available
  consumer BCI (Brain-Computer Interface) devices (Emotiv, OpenBCI, Muse) as an
  input modality for hands-free interaction.
- **Neural signal processing**: Processing pipeline for raw neural signals
  including noise filtering, feature extraction, and intent classification from
  EEG (electroencephalography) or EMG (electromyography) signals.
- **Adaptive responses**: The AI adapts response complexity and pacing based on
  cognitive state indicators detected via BCI data, reducing information
  overload for fatigued users.

### 9.4 IoT Integration

- **Smart device control**: Issue natural language commands to connected IoT
  devices and smart home systems through Iris.
- **Sensor data analysis**: AI analysis of time-series data streams from
  connected sensors — temperature trends, energy usage patterns, anomaly
  detection.
- **Ambient intelligence**: Iris can respond to environmental context changes
  from connected sensors (e.g., adjusting communication style based on detected
  meeting room occupancy).

---

## 10. Emotional Intelligence

Iris understands emotional context and responds with appropriate empathy and
sensitivity, making it more effective in situations involving stress,
frustration, or personal topics.

### 10.1 Emotion Recognition — `libs/iris/emotional/*`

Emotional intelligence is a cluster under `libs/iris/emotional/`
(`@iris/emotional-recognition`, `@iris/emotional-response`,
`@iris/emotional-rapport`, `@iris/emotional-social`, `@iris/emotional-ethics`,
`@iris/emotional-wellbeing`, `@iris/emotional-voice-analysis`, and others) —
there is no single `@iris/emotional` package.

- **Text sentiment analysis**: Detects emotional tone in written messages —
  frustration, excitement, confusion, sadness — from linguistic patterns and
  phrasing.
- **Voice emotion detection**: Analyzes voice tone, pacing, and prosody to
  identify emotional state from speech characteristics beyond word choice.
- **Contextual emotion inference**: Understands emotional subtext in context —
  someone asking "is this normal?" after describing a difficult situation is
  seeking reassurance, not merely information.

### 10.2 Empathetic Responses

- **Empathetic response generation**: When emotional distress or difficulty is
  detected, the AI responds first with acknowledgment and empathy before
  providing information or solutions.
- **Rapport building**: Iris builds conversational rapport over time through
  consistent personality, remembered preferences, and appropriate reference to
  shared conversation history.
- **Social context awareness**: Understands social dynamics — the difference
  between venting, seeking advice, and requesting concrete help — and responds
  accordingly.
- **Wellbeing monitoring**: Gently monitors for patterns suggesting user stress
  or difficulty and offers supportive responses without being intrusive.
- **Ethical guardrails**: The AI applies ethical reasoning in sensitive
  conversations, identifying when a topic requires professional help and
  communicating that boundary respectfully.

### 10.3 Communication Style Adaptation

- **Tone control**: Switch between formal, casual, professional, and friendly
  registers based on conversation context or explicit preference.
- **Verbosity control**: The user can request concise bullet-point summaries or
  detailed long-form explanations based on the current need.
- **Audience awareness**: Adjust technical complexity from beginner-friendly
  analogies to expert-level technical detail based on demonstrated expertise.
- **Cultural sensitivity**: Adapt communication style for different cultural
  contexts, avoiding culturally specific idioms that may not translate well.

---

## 11. Advanced Reasoning

Advanced reasoning capabilities for complex, multi-step problems that require
careful, transparent thought before reaching conclusions. These features are
grouped under the `libs/iris/reasoning-thinking/` cluster
(`@iris/reasoning-thinking`) and apply on top of any supported AI model — they
control _how_ the model approaches a problem, not which model answers it.

- **Chain-of-thought reasoning**: The AI walks through its reasoning step by
  step before reaching a conclusion, making the reasoning process transparent
  and auditable.
- **Extended thinking mode** (`@iris/reasoning-thinking`): For particularly
  complex problems, the AI enters an extended deliberation mode where it spends
  additional compute time on planning and verification before responding.
- **Self-consistency checking**: For important conclusions, the AI generates
  multiple independent reasoning chains and cross-checks them — if all chains
  reach the same conclusion, confidence is high.
- **Metacognitive monitoring**: The AI actively monitors its own reasoning for
  logical leaps, unsupported assumptions, or areas where its knowledge is
  limited.
- **Uncertainty disclosure**: The AI explicitly communicates when it is
  uncertain about an answer, distinguishing between confident knowledge and
  educated estimation.
- **Confidence scoring**: Responses include confidence indicators that reflect
  the AI's assessed reliability of the information provided.

---

## 12. Agent Marketplace

A curated directory for discovering, installing, and publishing AI agents and
plugins that extend Iris's capabilities beyond the built-in set.

- **Agent directory**: Browse a curated catalog of specialized AI agents created
  by Anthropic, verified third-party publishers, and the Iris developer
  community.
- **Plugin library**: Install plugins that add new tool categories, data
  sources, or workflow integrations to Iris.
- **One-click install**: Install agents and plugins directly from the
  Marketplace with a single confirmation — no configuration required for
  standard setups.
- **Reviews and ratings**: Community ratings and written reviews help users
  identify the highest-quality agents for their use cases.
- **Developer publishing**: Any developer with an Iris developer account can
  publish agents and plugins to the Marketplace, subject to a review process.
- **Version management**: Installed agents and plugins receive automatic updates
  with version notes. Users can pin to a specific version or roll back if
  needed.
- **Agent archetypes**: Pre-defined templates for common agent use cases
  (customer support bot, coding assistant, research agent) that developers can
  customize and publish.
- **Custom personalities**: Customize any agent's name, personality description,
  visual avatar, and tone without modifying its underlying capabilities.

---

## 13. Privacy and Security

Iris is built with privacy as a core design principle, with controls that range
from full local-only operation to enterprise compliance certification.

### 13.1 Privacy Controls — `@iris/privacy`

- **End-to-end encryption**: All conversation content is encrypted in transit
  (TLS 1.3) and at rest (AES-256). Only the authenticated user can decrypt their
  conversation history.
- **Local-only mode**: Iris can be configured to run AI models entirely
  on-device with zero data leaving the device — no cloud API calls, no
  telemetry.
- **Data minimization**: The system collects only the data necessary to provide
  the requested service. No behavioral tracking beyond what is needed for
  personalization.
- **Differential privacy**: Analytics processing uses differential privacy
  techniques (mathematical methods that add calibrated noise to statistics) that
  prevent individual user data from being reconstructable from aggregate
  analytics.
- **Consent management**: Users configure granular consent for each category of
  data processing: conversation storage, personalization learning, analytics,
  and third-party integrations.
- **Data residency**: Enterprise users choose which geographic region (US, EU,
  Asia-Pacific) stores their data, supporting data sovereignty requirements.
- **Data portability**: Export all personal data, conversations, and memories at
  any time in standard formats (JSON, Markdown).
- **Data deletion**: Request deletion of all personal data, triggering
  verifiable deletion across all storage systems within 30 days.
- **Audit logging**: Complete, tamper-evident logs of all data access and
  processing operations for compliance reporting.

### 13.2 Security Features

- **API key management**: Generate, scope, and revoke API keys from the
  developer dashboard with configurable per-key permission sets.
- **Rate limiting**: Per-user and per-IP rate limiting to prevent abuse and
  enforce fair usage quotas.
- **Secret detection**: Automatic scanning of user inputs for accidental
  inclusion of credentials, API keys, and other sensitive data, with warning and
  optional redaction.
- **Sandboxed execution**: All agent tool invocations and code execution run in
  isolated sandboxes with no access to host system resources outside the
  permitted scope.
- **Role-based access control (RBAC)**: Enterprise deployments define roles with
  specific permission sets — a "viewer" role can read conversations but cannot
  create API keys or modify settings.

### 13.3 Compliance

| Standard      | Coverage                                                           |
| ------------- | ------------------------------------------------------------------ |
| **GDPR**      | Data access, portability, deletion, and processing records         |
| **CCPA**      | California consumer privacy rights                                 |
| **SOC 2**     | Security, availability, and confidentiality trust service criteria |
| **ISO 27001** | International information security management standard             |

### 13.4 Rate Limits and Quotas

Default per-user limits by plan tier. Enterprise limits are configurable per
contract. Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
`X-RateLimit-Reset`, and `X-Token-Budget-Remaining` headers.

| Limit             | Free  | Pro       | Enterprise   |
| ----------------- | ----- | --------- | ------------ |
| Requests/minute   | 10    | 60        | Configurable |
| Messages/day      | 100   | 1,000     | Unlimited    |
| Tokens/month      | 100K  | 2M        | Configurable |
| Knowledge docs    | 10    | 500       | Unlimited    |
| Knowledge storage | 50 MB | 10 GB     | Unlimited    |
| Memory entries    | 1,000 | Unlimited | Unlimited    |
| Agent tasks/day   | 20    | 500       | Unlimited    |
| API keys          | 2     | 10        | Unlimited    |

---

## 14. Accessibility

Iris is designed to be usable by everyone, with comprehensive support across all
disability categories built into the core design rather than added as an
afterthought.

### 14.1 Visual Accessibility — `@iris/accessibility`

- **Screen reader support**: Full compatibility with VoiceOver (macOS/iOS), NVDA
  and JAWS (Windows), and TalkBack (Android). All interactive elements have
  correct ARIA labels and roles.
- **High contrast mode**: Enhanced contrast themes for low-vision users,
  including both high-contrast dark and high-contrast light themes.
- **Scalable text**: Text size scales throughout the entire interface in
  response to system font size settings or in-app size controls.
- **Color blind modes**: Alternative color themes for protanopia (red-green),
  deuteranopia (green-red), and tritanopia (blue-yellow) color vision
  deficiencies.
- **Braille display support**: Compatible with refreshable Braille displays
  through standard screen reader interfaces.

### 14.2 Motor Accessibility

- **Complete keyboard navigation**: Every feature and action in Iris is
  accessible via keyboard alone — no mouse required. Tab order is logical and
  follows visual layout.
- **Switch access**: Support for single-switch and multi-switch scanning input
  methods used by users with limited motor control.
- **Dwell control**: Activate interface elements by hovering for a configurable
  dwell duration, supporting users who cannot physically click.
- **Customizable shortcuts**: Define custom keyboard shortcuts for any
  frequently used action.

### 14.3 Hearing Accessibility

- **Closed captions**: Real-time synchronized captions displayed during AI voice
  response playback.
- **Visual notifications**: All audio notifications have visual counterparts
  (flashes, animated indicators) ensuring deaf users do not miss alerts.
- **Conversation transcripts**: Full text transcripts of voice conversations,
  downloadable as plain text or Markdown.

### 14.4 Cognitive Accessibility

- **Simplified interface mode**: An optional simplified layout that reduces
  visual complexity, removes decorative elements, and presents only core
  features.
- **Reading level adjustment**: Request AI responses at a specific reading level
  — from simple (Grade 3) to technical (Graduate level).
- **Step-by-step mode**: Break complex instructions into individually confirmed
  steps, presenting one step at a time.
- **Summary mode**: Get a concise summary of any long response with a single
  click.
- **Reduced motion mode**: Disable all non-essential animations and transitions
  for users sensitive to motion.

### 14.5 Language Accessibility

- **100+ languages**: AI conversation and understanding in over 100 languages
  with high-quality comprehension.
- **RTL layout support**: Full right-to-left text direction support for Arabic,
  Hebrew, Persian, and other RTL languages, including mirrored UI layouts.
- **Automatic language detection**: Iris detects the language of each message
  and responds in the same language without requiring manual selection.

---

## 15. Personalization

Iris adapts to each user over time, becoming progressively more useful as it
learns individual preferences and working patterns through the memory and
conversation systems.

- **Communication style learning** (`@iris/personalization`): Iris learns
  whether a user prefers formal or casual language, concise or detailed
  responses, technical or accessible explanations — and applies these
  preferences automatically in future sessions.
- **Domain expertise modeling**: As users demonstrate knowledge in specific
  areas, Iris adjusts the complexity and depth of explanations in those domains
  without being asked.
- **Tool preference memory**: Iris remembers which tools, workflows, and
  approaches each user gravitates toward and suggests or defaults to those in
  relevant contexts.
- **Schedule awareness**: Iris considers the time of day, day of week, and
  typical usage patterns to calibrate response urgency and style.
- **Automatic context carry-over**: Important context from past conversations
  (ongoing projects, recurring challenges, established preferences) is
  automatically carried into new conversations without the user needing to
  re-explain.
- **Proactive suggestions**: Based on observed patterns, Iris proactively
  surfaces relevant information or suggests next actions before being asked —
  analogous to a well-attuned human assistant anticipating needs.

---

## 16. Analytics and Insights

Understand how AI assistance is being used and track the value it delivers to
individuals and organizations.

### 16.1 Usage Analytics — `@iris/analytics`

- **Conversation metrics**: Total conversations started, average length,
  messages exchanged, and time spent per session over configurable date ranges.
- **Model usage breakdown**: Which AI models are being used most frequently,
  enabling cost allocation and optimization decisions.
- **Token consumption**: Track token usage per model, per conversation type, and
  per user for budget management and billing reconciliation.
- **Response quality tracking**: User ratings on individual responses are
  aggregated into quality trend reports.
- **Usage patterns**: Heatmaps and trend charts showing when Iris is used most
  heavily, which features are most popular, and how usage evolves over time.

### 16.2 Productivity Insights

- **Time saved estimates**: Statistical models estimate how much time Iris
  assistance saves compared to completing tasks without AI help.
- **Task completion rates**: Track the percentage of AI-assisted tasks that are
  marked as successfully completed by users.
- **Knowledge base utilization**: Which documents are most frequently retrieved
  and cited, identifying the highest-ROI knowledge assets.
- **Agent performance comparison**: Compare different agent configurations on
  key performance metrics — satisfaction score, task completion rate, average
  session length.

### 16.3 Advanced Analytics

- **A/B testing framework**: Compare different model configurations, prompt
  variants, or agent behaviors on controlled user cohorts with statistical
  significance testing.
- **Cohort analysis**: Segment users by onboarding date, use case, or
  organization and compare behavior and outcome metrics across cohorts.
- **Funnel analytics**: Define user journey funnels and measure completion rates
  at each step.
- **Real-time dashboards**: Live monitoring dashboards for active session
  counts, message rates, error rates, and latency percentiles.

---

## 17. Cross-Platform Presence

### 17.1 Notifications and Presence — `@iris/presence-sync`, `@iris/presence-integration`

- **Task completion alerts**: Push notifications when background agent tasks
  (long research sessions, code generation jobs, batch processing) finish
  running.
- **Multi-device sync**: Conversation state, preferences, and ongoing tasks
  synchronize instantly across all the user's signed-in devices.
- **Online/offline status**: Iris adapts its behavior to network availability —
  queuing requests when offline and flushing when connectivity returns.
- **Cross-platform notifications**: Native notification integration on all
  platforms (iOS, Android, macOS, Windows, browser) ensures alerts reach the
  user wherever they are.

---

## 18. Integrations

Iris integrates primarily with the **other Oshun domains** through dedicated
bridge libraries, and exposes a webhook surface (`@iris/platform-webhooks`) for
external systems.

The domain boundary is deliberate: each Oshun domain (Psyche, Sophia, Maya,
etc.) has its own specialized product logic, but none of them should own a
separate AI conversation stack. Instead, they depend on Iris for everything
related to model access, memory, and agent execution, and connect via typed
bridge packages that encapsulate the Iris API contract. This keeps AI
infrastructure centralized and consistently versioned, while allowing each
domain to build its own UX on top of shared capabilities. Third-party SaaS
connectors (Slack, Teams, Jira, GitHub, etc.) are planned but not yet
implemented in `libs/iris`.

### 18.1 Cross-Domain Bridges — `@iris/integrations-*`

`libs/iris/integrations/` contains one bridge package per sister Oshun domain —
these are **cross-Oshun-domain bridges, not third-party SaaS connectors**. Each
package owns the typed contract that lets the corresponding domain use Iris
capabilities without depending directly on `@iris/api` internals:

| Bridge                      | Sister domain | Purpose                                                             |
| --------------------------- | ------------- | ------------------------------------------------------------------- |
| `@iris/integrations-psyche` | Psyche        | AI avatar representation, emotion expression, conferencing presence |
| `@iris/integrations-sophia` | Sophia        | Research & knowledge integration                                    |
| `@iris/integrations-maya`   | Maya          | AI assistance for the Maya metaverse engine                         |
| `@iris/integrations-yemaya` | Yemaya        | Creative Studio integration                                         |
| `@iris/integrations-hathor` | Hathor        | Worldbuilding / lore integration                                    |
| `@iris/integrations-nyx`    | Nyx           | Astronomy integration                                               |

There is no top-level `@iris/integrations` package, and no Slack / Microsoft
Teams / Notion / Jira / GitHub / Confluence connector exists in `libs/iris`.
Third-party SaaS connectors of that kind are **planned**, not implemented.

### 18.2 Webhooks and API Access

- **Webhook support** (`@iris/platform-webhooks`): Outbound webhooks that notify
  external systems of Iris events for integration with custom workflows.
- **API-first design**: Iris capabilities are exposed through the `@iris/api`
  REST + GraphQL service so teams can embed Iris functionality in their own
  products and internal tools.

### 18.3 Domain Event Vocabulary

`@iris/types` (`events.ts`) defines the domain-event type system using a
CloudEvents-style `DomainEvent<T>` model. This gives every Iris event a
consistent envelope (`id`, `type`, `category`, `aggregateId`, `payload`,
`metadata`) that any consumer can parse without knowing the specific event
schema upfront. The interfaces `IEventBus` and `IEventStore` define the
publish/subscribe and append/replay contracts, while per-category event-type
literals such as `conversation.created`, `message.created`, `memory.summarized`,
`task.completed`, and `tool.completed` form the typed vocabulary.

The shared cross-domain transport is the **Redis-backed** `@oshun/event-bus`
(`libs/shared/event-bus`). No `libs/iris` package publishes onto that bus today,
and there are no Kafka topics — event publication from iris services is
**planned**.

---

## 19. Developer Platform

Full developer access for building custom integrations, agents, and applications
on top of Iris.

### 19.1 SDK and API

- **Typed REST API**: Complete REST API with OpenAPI specification for all Iris
  capabilities — conversations, memory, knowledge, agents, analytics.
- **SDK** (`@iris/sdk`): TypeScript SDK providing typed methods for every API
  endpoint with built-in authentication, retry logic, and pagination handling.
- **WebSocket API**: Real-time streaming API for conversation responses, agent
  progress updates, and event notifications.
- **gRPC API**: High-performance gRPC interface for server-to-server
  integrations requiring low latency.

### 19.2 Testing and Configuration

- **Testing library** (`@iris/testing`): Utilities for writing unit and
  integration tests for agent workflows and knowledge retrieval pipelines —
  including mock providers and conversation simulators.
- **Configuration library** (`@iris/config`): Typed configuration management for
  all Iris service settings with environment variable support and validation.
- **Developer portal**: Interactive API playground, SDK documentation, usage
  dashboards, and API key management in a self-service web interface.

### 19.3 Platform Providers

- **Conversation providers** (`@iris/conversation-providers-anthropic`,
  `@iris/conversation-providers-openai`, `@iris/conversation-providers-google`,
  `@iris/conversation-providers-local`): Individual provider adapters exposing a
  uniform interface regardless of which model is in use.

---

## 20. Wearable and XR

Dedicated experiences for extended reality headsets and wearable devices.

### 20.1 Wearable Features

- **Wrist-based interaction**: Compressed AI responses optimized for small
  screen formats and glanceable consumption.
- **Haptic feedback**: Use device haptics to signal AI response completion, task
  updates, and notification delivery on wearable devices.
- **Voice-first on wearable**: On smartwatches where typing is impractical,
  voice input is the primary interaction mode with one-word command recognition.

### 20.2 XR Features

- **Spatial conversations**: In XR environments, Iris renders as a spatial
  entity with positional audio that sounds like it comes from a specific
  direction in the user's space.
- **Environment awareness**: The AI receives context about the XR environment —
  what the user is looking at, spatial objects nearby — and incorporates this
  into responses.
- **Collaborative XR**: Multiple users in the same XR space can interact with a
  shared Iris instance, enabling collaborative AI-assisted workflows in virtual
  environments.

---

## Library Summary

`libs/iris/**` holds 258 packages organized into roughly 20 functional clusters.
The table below lists the representative packages by cluster, with their
filesystem path and primary capability. Package names are taken from the
`package.json` `name` field — several do not match their directory path (for
example, `@iris/knowledge` lives at `knowledge/core`, and `@iris/voice` lives at
`multimodal/voice/recognition`), and a few clusters have no single umbrella
package. The full inventory and counts are in `DOMAINS/iris/specifications.md`
§14.

| Cluster / Package                   | Path / count                       | Primary Capability                                                                                              |
| ----------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `@iris/core`                        | `core`                             | Foundation: errors, context, logging, tracing, config                                                           |
| `@iris/types`                       | `types`                            | Shared domain types for all Iris entities                                                                       |
| `@iris/config`                      | `config`                           | Typed service configuration                                                                                     |
| Conversation cluster                | 31 `@iris/conversation*` packages  | Core dialogue engine, context, intent, RAG, orchestration, providers, reasoning                                 |
| `@iris/conversation-core`           | `conversation-core`                | Dialogue engine: managers, turns, context window, state machine                                                 |
| `@iris/conversation-orchestration`  | `conversation-orchestration`       | Multi-model orchestration; V2 match-commentary contract                                                         |
| `@iris/conversation-providers-*`    | 4 packages                         | Anthropic / Google / OpenAI / local provider adapters                                                           |
| `@iris/model-routing`               | `model-routing`                    | Provider routing and circuit breaking                                                                           |
| `@iris/ensemble` / `@iris/failover` | `ensemble`, `failover`             | Multi-model voting; provider failover chains                                                                    |
| Memory cluster                      | 22 packages under `memory/`        | Four-tier memory: core, transitions, consolidation, retrieval, persistence, sharing, debugging, visualization   |
| `@iris/memory-core`                 | `memory/core`                      | Core memory tier manager                                                                                        |
| Knowledge cluster                   | ~23 packages under `knowledge/`    | `@iris/knowledge` (core), chunking, embeddings, retrieval, RAG, graph, factcheck, grounding                     |
| Agents cluster                      | `agents/` tree                     | `@iris/agents` catalog, `agents-core`, `archetypes`, `multi-agent`, `workflows`, tools, computer-use, proactive |
| `@iris/mcp` / `@iris/a2a`           | `mcp`, `a2a`                       | Model Context Protocol; agent-to-agent protocol                                                                 |
| `@iris/reasoning-thinking`          | `reasoning-thinking`               | Extended thinking, chain-of-thought, metacognition                                                              |
| Code cluster                        | `code/` tree (~21 packages)        | `code-generation`, `code-review`, `code-understanding`, IDE packages, etc.                                      |
| Multimodal cluster                  | `multimodal/` tree                 | `@iris/voice` (recognition) + voice family, vision family, `@iris/iot`, `@iris/spatial`, `@iris/bci`            |
| Emotional cluster                   | `emotional/` tree (9 packages)     | `emotional-recognition`, `-response`, `-rapport`, `-social`, `-ethics`, `-wellbeing`, etc.                      |
| Privacy cluster                     | `privacy/` tree + `memory/privacy` | `@iris/privacy`, encryption, anonymization, audit, safety/security sub-trees                                    |
| Platform cluster                    | `platform/` tree                   | `platform-admin`, `platform-gateway`, `platform-webhooks`, `@iris/streaming`, `@iris/plugins`, SDK packages     |
| Accessibility cluster               | `accessibility/` tree              | `@iris/accessibility`, visual / motor / hearing / cognitive / braille / i18n                                    |
| Analytics cluster                   | `analytics/` tree (5 packages)     | `@iris/analytics`, realtime, cohort, funnel, A/B                                                                |
| `@iris/concordia-assistant`         | `concordia-assistant`              | Appellant / arbiter dialogue scaffolding for dispute flows                                                      |
| `@iris/sdk`                         | `sdk/typescript`                   | TypeScript client SDK                                                                                           |
| `@iris/testing`                     | `testing/` tree                    | Test utilities; chaos, load, synthetic, visual                                                                  |
| `libs/iris/database`                | `database/prisma`                  | Prisma schema (3 models: consent, continuity, memory-scope)                                                     |
| `@iris/integrations-*`              | `integrations/` (6 packages)       | Cross-Oshun-domain bridges (Psyche, Sophia, Maya, Yemaya, Hathor, Nyx)                                          |

## Planned Concordia Mediation Assistant

The Concordia domain handles cross-domain dispute resolution — contract
disagreements, community moderation appeals, structured negotiations — but it
needs conversational scaffolding to guide the parties through intake, agreement
drafting, and consent. That conversational layer lives in Iris rather than
Concordia because Iris already owns model routing, memory, multilingual support,
and consent management; Concordia only needs the orchestration and agreement
search logic.

Phase 179 adds planned Iris Concordia capabilities under
`libs/iris/concordia-assistant/`. Iris owns the conversational surfaces for
party-isolated private intake, low-stakes conflict brainstorming, two-device or
multi-device participant flows, "turn this conversation into a structured
agreement" commands, meeting co-mediator mode, consent disclosures, and
inappropriate-case routing to human or professional support. The Concordia
domain owns the orchestration and agreement search; Iris owns assistant UX,
conversation state, model routing, multilingual interaction, and participant
controls.

V2 now consumes `@iris/concordia-assistant` through `@v2/concordia-substrate`
for anti-cheat appeals, tournament-result disputes, and crew conflicts. The V2
integration uses Iris consent-gated intake flows, canonical prompt scripts, and
party-isolated prompt contexts to scaffold appellant / arbiter dialogue while
exposing only sealed private-context refs to the dispute surface.

## V2 Real-Time Translation Bridge

The V2 fighting-game platform serves a global audience across dozens of
languages. Rather than each broadcast surface owning its own translation
pipeline, V2 routes all real-time language work through Iris's voice and
translation stack, keeping the translation logic in one place and benefiting
from Iris's provider failover and latency budgeting.

`@v2/iris-realtime-translation` composes `@iris/voice` for V2 spectator chat
translation and commentary localization. It routes per-recipient target
languages for chat, commentary subtitles, broadcast overlays, and companion
second-screen feeds, preserves failed-delivery metadata during provider outage,
and remains presentation-only and off rollback.

## Domain Boundary Summary

Iris owns the assistant interfaces, conversation engine, memory system, agent
orchestration, model routing, and all related UX. Neighbouring domains own
adjacent concerns: **Nous** owns model serving, training, and on-device
inference; **Sophia** owns research knowledge and academic knowledge bases;
**Concordia** owns cross-domain bargaining orchestration and agreement search;
**Psyche** owns embodied virtual-assistant behavior and avatar rendering. Iris
integrates with each of these through typed bridge packages rather than owning
their domains.

## Neural World Model Look-Ahead (Phase 176)

Iris is a co-owner of the neural world models track (Phase 176, centered in
Nous). Iris's side is the look-ahead planner: the assistant uses Nous
world-model `imagine()` rollouts to plan multi-step tool actions before
executing them, distinguishing confident predictions from uncertain
extrapolation via the model's uncertainty signal. Nous owns the world model;
Iris owns the planning-and-execution loop.