# Iris User Guide

Iris is an intelligent assistant workspace for conversations, specialized
agents, memory, and private knowledge. Use this guide to get started, choose the
right feature for each task, manage what Iris remembers, and troubleshoot common
issues.

---

## Table of Contents

1. [Getting Started](#getting-started)
2. [Feature Overview](#feature-overview)
3. [Having Conversations](#having-conversations)
4. [Working with AI Agents](#working-with-ai-agents)
5. [Memory and Context](#memory-and-context)
6. [Knowledge Base](#knowledge-base)
7. [Tips and Tricks](#tips-and-tricks)
8. [Frequently Asked Questions](#frequently-asked-questions)
9. [Troubleshooting](#troubleshooting)
10. [Quick Reference Card](#quick-reference-card)
11. [Related Documentation](#related-documentation)

---

## Getting Started

### Access Iris

Your organization decides which Iris apps are enabled. The web app is the
primary user workspace; desktop, mobile, wearable, XR, dashboard, marketplace,
developer portal, and API access may also be available.

| Access path          | Use it for                                                                    |
| -------------------- | ----------------------------------------------------------------------------- |
| **Web app**          | Full conversation, agent, memory, and knowledge workflows in a browser.       |
| **Desktop app**      | Native workstation use, local tools, and deeper device integration.           |
| **Mobile app**       | On-the-go conversations, voice input, camera uploads, and quick review.       |
| **Dashboard**        | Team administration, analytics, policies, and workspace settings.             |
| **Marketplace**      | Browsing approved agents, plugins, and integrations.                          |
| **Developer portal** | API keys, SDK examples, API documentation, and integration tools.             |
| **API service**      | Programmatic access to conversations, agents, memory, knowledge, and streams. |

To sign in:

1. Open the Iris URL or app provided by your administrator.
2. Sign in with SSO, email/password, or the identity method your organization
   configured.
3. Confirm that the active workspace is the one you intend to use.
4. Review your initial privacy, memory, and model settings before sharing
   sensitive information.

### Start Your First Conversation

1. Select **New Conversation**.
2. Choose an agent or keep the default general assistant.
3. Type a message in the input field.
4. Attach files if the question depends on a document, image, code sample, or
   dataset.
5. Send the message and watch the response stream in real time.

Example first message:

```text
I am new to Iris. Give me a short tour of what I can do in this workspace,
and ask one question that would help you tailor future answers to my role.
```

### Interface Overview

| Area                  | What it does                                                                    |
| --------------------- | ------------------------------------------------------------------------------- |
| **Conversation list** | Shows recent conversations, search results, titles, folders, and saved history. |
| **Agent selector**    | Chooses the assistant or specialist agent for the current task.                 |
| **Message timeline**  | Displays user messages, streamed responses, citations, tool output, and files.  |
| **Composer**          | Sends text, files, images, voice input, and structured follow-up requests.      |
| **Knowledge panel**   | Manages knowledge bases, uploaded documents, collections, tags, and search.     |
| **Memory settings**   | Shows what Iris may remember and lets you edit, disable, or delete memory.      |
| **Model controls**    | Lets permitted users choose model routing, local mode, cost, or latency goals.  |
| **Settings**          | Account, privacy, notification, accessibility, integration, and export options. |

### Keyboard Shortcuts

| Shortcut        | Action                                      |
| --------------- | ------------------------------------------- |
| `Enter`         | Send the current message.                   |
| `Shift + Enter` | Add a new line in the composer.             |
| `Ctrl/Cmd + N`  | Start a new conversation.                   |
| `Ctrl/Cmd + K`  | Search conversations and knowledge.         |
| `Ctrl/Cmd + Up` | Edit the most recent message when allowed.  |
| `Escape`        | Stop an in-progress response or close menu. |
| `Ctrl/Cmd + /`  | Show available shortcuts.                   |

---

## Feature Overview

### Conversations

Conversations are threaded workspaces that keep the relevant context for a
topic. Iris supports multi-turn discussion, streaming responses, message
editing, regeneration, branching, search, deletion, and export.

Use conversations for:

- Asking questions and refining answers over multiple turns.
- Analyzing documents, images, code, and structured data.
- Drafting, reviewing, and improving written work.
- Planning projects and tracking decisions.
- Preserving a cited record of research or analysis.

### Agents

Agents are specialized assistants with instructions, capabilities, tools, model
preferences, and sometimes access to selected memory or knowledge. Your
workspace may include general, coding, research, writing, analysis, support,
creative, operations, supervisor, or custom team agents.

Use agents when the task benefits from a defined role, approved tools,
repeatable workflow, or domain-specific knowledge.

### Memory

Memory lets Iris personalize help across turns and, when you allow it, across
conversations. Iris separates short-term conversation context from longer-lived
preferences, task context, episodic history, and semantic relationships.

Use memory for durable preferences such as:

- Preferred programming language, stack, or style.
- Communication preferences and output formats.
- Project facts that should carry across sessions.
- Repeated goals, constraints, or team conventions.

### Knowledge Base

Knowledge bases contain documents and text that Iris can search and cite. They
are useful for policies, specifications, manuals, runbooks, research, datasets,
source documentation, and team knowledge.

Knowledge answers should include citations or references when the response is
grounded in uploaded material.

---

## Having Conversations

### Write Effective Prompts

Strong prompts usually include a goal, context, constraints, and desired output.

```text
Goal: Review this deployment plan for release risk.
Context: We deploy the API and worker together, but search indexing is async.
Constraints: Focus on operational risk, rollback, and customer impact.
Output: Give me a prioritized checklist with owners and verification steps.
```

When Iris needs more information, it may ask a clarifying question. Answering
that question usually gives better results than forcing a broad answer.

### Use Multi-Turn Context

You can build on previous messages naturally:

```text
You: Summarize this support ticket thread.
Iris: [summary]
You: Turn the summary into a customer-facing reply.
Iris: [draft]
You: Make it shorter and include the outage window from the first message.
Iris: [revised draft]
```

For long conversations, restate the current goal when the topic changes. This
keeps the response focused and helps Iris choose the right context.

### Attach Files

Use attachments when the answer depends on exact source material.

| File category | Examples                       | Typical use                                    |
| ------------- | ------------------------------ | ---------------------------------------------- |
| Documents     | PDF, DOCX, TXT, Markdown       | Summaries, policy questions, contract review.  |
| Code          | Python, JavaScript, TypeScript | Debugging, explanation, review, test planning. |
| Data          | CSV, JSON, XLSX                | Analysis, transformation, trends, reporting.   |
| Images        | PNG, JPG, GIF, WebP            | Screenshots, diagrams, visual inspection, OCR. |
| Slides        | PPTX                           | Presentation review, extraction, rewriting.    |

After attaching a file, say what you want done with it:

```text
Attached is the draft incident report. Find missing timeline details,
unclear customer impact statements, and any claims that need evidence.
```

### Edit, Regenerate, Branch, and Stop

| Action         | When to use it                                                                     |
| -------------- | ---------------------------------------------------------------------------------- |
| **Edit**       | Correct your prompt or add missing context. Later responses may be regenerated.    |
| **Regenerate** | Ask for a different answer without changing your prompt.                           |
| **Branch**     | Explore an alternate direction while preserving the original conversation history. |
| **Stop**       | Cancel a response that is going in the wrong direction or taking too long.         |

### Export and Share

Use conversation export when you need a durable record. Available formats depend
on workspace policy and may include Markdown, JSON, and PDF.

Before sharing an export:

1. Review it for secrets, personal data, customer information, and confidential
   source material.
2. Confirm citations and generated claims.
3. Remove draft content that should not leave the workspace.
4. Follow your organization's sharing and retention policies.

---

## Working with AI Agents

### Choose the Right Agent

| Agent type        | Best for                                                             |
| ----------------- | -------------------------------------------------------------------- |
| **General**       | Everyday questions, explanation, brainstorming, drafting, planning.  |
| **Code**          | Debugging, code review, refactoring, tests, architecture, examples.  |
| **Research**      | Source synthesis, fact checking, literature review, cited summaries. |
| **Writer**        | Editing, tone changes, style adaptation, outlines, final copy.       |
| **Analyst**       | Data interpretation, reports, spreadsheet analysis, trends.          |
| **Support**       | Knowledge-grounded answers, FAQs, ticket triage, customer replies.   |
| **Operations**    | Runbooks, deployment analysis, incident response, automation.        |
| **Supervisor**    | Coordinating multiple agents or reviewing delegated work.            |
| **Custom agents** | Team-specific workflows, tools, constraints, and knowledge sources.  |

If you are unsure, start with the general assistant and ask which agent should
handle the task.

### Understand Capabilities

Agents may be able to:

- Plan a multi-step task before acting.
- Use approved tools such as file search, web search, API calls, databases, or
  code execution.
- Search memory and knowledge bases that you have permission to use.
- Delegate subtasks to other agents when multi-agent workflows are enabled.
- Return artifacts such as summaries, JSON, tables, code, runbooks, or tickets.

Tool access is permissioned. If an agent cannot access a file, system, or
knowledge base, it should say what is missing.

### Switch Agents

You can switch agents at the start of a new conversation or, when enabled, from
the current conversation header. When switching mid-conversation:

1. Confirm the new agent can see the relevant history.
2. Summarize the handoff goal in one sentence.
3. Mention any tool, model, or privacy constraints that changed.

Example:

```text
Switching to the operations agent: use the incident timeline above and produce
a rollback checklist. Do not call external systems; this is planning only.
```

---

## Memory and Context

### Memory Types

| Memory type    | Scope                    | Examples                                                            |
| -------------- | ------------------------ | ------------------------------------------------------------------- |
| **Short-term** | Current conversation     | Recent messages, current file references, active question.          |
| **Working**    | Current task or session  | Temporary task state, selected constraints, in-progress decisions.  |
| **Long-term**  | Cross-conversation       | Stable preferences, profile facts, repeated project context.        |
| **Episodic**   | Time-bound interactions  | Conversation summaries, milestones, notable events.                 |
| **Semantic**   | Concepts and relations   | Relationships among people, projects, systems, and domain concepts. |
| **Core**       | Durable profile/context  | Persona, goals, role, persistent instructions, team conventions.    |
| **Archival**   | Long-lived stored record | Verified facts, historical notes, durable references.               |

Available tiers depend on workspace configuration and consent settings.

### Teach Iris Explicitly

Use direct language when you want Iris to remember something:

```text
Remember that I prefer TypeScript examples, use UTC timestamps, and want
security notes called out separately in release plans.
```

For sensitive facts, decide first whether they should be stored. You can also
say:

```text
Use this only for the current conversation. Do not save it to memory.
```

### Manage Memory

In **Settings > Memory**, you can typically:

- View stored memories and their source context.
- Edit incorrect or outdated memory.
- Delete specific memories.
- Clear a memory tier.
- Disable long-term, semantic, or episodic memory.
- Export memory data when allowed by policy.
- Review whether agents can use memory by default.

### Privacy Basics

Memory should not be treated as a place for secrets. Avoid storing passwords,
tokens, private keys, regulated data, or information you are not authorized to
retain. Use the privacy guide for detailed controls, deletion, local-only mode,
and compliance rights.

---

## Knowledge Base

### Upload Documents

1. Open the **Knowledge** panel.
2. Create or select a knowledge base.
3. Upload documents, paste text, or add structured content.
4. Add useful metadata such as title, owner, version, tags, and source.
5. Wait for indexing to complete before relying on the document in answers.

If a document is sensitive, confirm that the destination knowledge base has the
right access controls before upload.

### Organize Knowledge

Use clear organization so retrieval works well:

- Create separate knowledge bases for different teams, projects, or sensitivity
  levels.
- Use collections for related documents such as release notes, policies, or API
  references.
- Add tags for product, version, status, owner, and date.
- Remove duplicates and obsolete documents.
- Upload new versions instead of relying on stale files.

### Use Knowledge in Conversations

You can ask Iris to search knowledge automatically or explicitly:

```text
Search the Platform Runbooks knowledge base for database failover steps.
Summarize the procedure and cite the relevant sections.
```

Good knowledge-grounded requests name the expected source, version, and output:

```text
Using the 2026 onboarding policy documents only, list the equipment steps for
new hires in the US. Include citations and flag anything the policy does not
answer.
```

### Check Answers

When a response depends on knowledge:

1. Review citations or source references.
2. Check whether the cited document is current.
3. Ask Iris to quote or summarize the specific supporting passage when needed.
4. Treat uncited claims as model-generated unless the workspace guarantees
   strict grounding.

---

## Tips and Tricks

### Get Better Responses

- State the outcome you want before the background context.
- Tell Iris who the answer is for: beginner, executive, engineer, customer, or
  reviewer.
- Specify the format: checklist, table, JSON, email, runbook, diff summary, or
  short answer.
- Give constraints: length, tone, deadline, tools allowed, sources allowed,
  privacy limits, and assumptions.
- Ask for uncertainty: "List what you know, what you infer, and what needs
  verification."
- Use follow-up turns to refine rather than starting over.

### Productivity Patterns

| Pattern       | Example prompt                                                                |
| ------------- | ----------------------------------------------------------------------------- |
| **Review**    | `Review this plan for risks, missing owners, and unclear verification steps.` |
| **Transform** | `Turn these notes into a customer update with a calm, factual tone.`          |
| **Compare**   | `Compare these two options by cost, risk, time, and reversibility.`           |
| **Extract**   | `Extract action items, owners, dates, blockers, and open questions.`          |
| **Constrain** | `Use only the attached document. If it does not say, write "not specified".`  |
| **Iterate**   | `Keep the meaning, reduce length by half, and preserve all commitments.`      |
| **Validate**  | `Find assumptions, weak evidence, and claims that need confirmation.`         |
| **Plan**      | `Create a step-by-step plan with dependencies and a verification checklist.`  |

### Advanced Features

- Use model controls when you need lower latency, lower cost, longer context, or
  local-only processing.
- Use branches for alternate drafts or strategies.
- Use memory intentionally for stable preferences and project context.
- Use knowledge bases for source-backed answers instead of pasting the same
  reference repeatedly.
- Use specialized agents when tool access or workflow discipline matters.
- Use exports for meeting notes, audit records, research summaries, and handoff
  material.

---

## Frequently Asked Questions

### General

**Q: What is Iris best at?**

A: Iris is best for conversational work that benefits from context, source
material, specialist agents, memory, or repeatable workflows: research, coding,
writing, analysis, support, planning, and knowledge-grounded Q&A.

**Q: Is Iris always connected to the internet?**

A: Not necessarily. Cloud models require network access. Local-only mode and
offline behavior depend on the app, local model availability, and workspace
policy.

**Q: Which app should I use?**

A: Use the web app for the fullest general experience. Use desktop or mobile
when you need local device features, voice, camera, or work away from your main
browser.

### Conversations

**Q: Why did Iris answer differently after I regenerated?**

A: Generation can vary by model settings, context, temperature, tool results,
and retrieved knowledge. For repeatable output, give tighter instructions and
cite the exact sources or format.

**Q: Can I delete a conversation?**

A: Yes, when your workspace policy allows it. Deletion removes the conversation
from your visible history and follows the retention behavior configured by your
organization.

**Q: Can I use generated code or text?**

A: You may use generated content subject to your organization's policies, but
you remain responsible for reviewing correctness, security, licensing, privacy,
and fitness for production use.

### Technical

**Q: Why is a file not accepted?**

A: The file may exceed the configured size limit, use an unsupported format, be
encrypted, be corrupted, or be blocked by workspace policy.

**Q: Why are citations missing?**

A: The answer may not have used a knowledge source, the source may not be
indexed, or the agent may not have permission to access it. Ask Iris to answer
only from a named knowledge base and include citations.

**Q: What should I do with sensitive data?**

A: Avoid pasting secrets. Use approved knowledge bases, local-only mode, privacy
settings, and organization policy. Delete accidental sensitive content and
notify the appropriate internal team if required.

### Account

**Q: How do I change account settings?**

A: Open **Settings** from your profile menu. Password changes may be handled by
your identity provider if SSO is enabled.

**Q: How do I export my data?**

A: Use the export controls available in conversations, knowledge, memory, or
privacy settings. Some exports may require administrator approval.

**Q: How do I request account deletion?**

A: Use the self-service deletion workflow if available, or contact your
administrator. Deletion timing and retention follow workspace policy and legal
requirements.

---

## Troubleshooting

### Response Takes Too Long

Try these steps:

1. Stop generation and retry.
2. Ask a narrower question.
3. Remove unnecessary attachments.
4. Choose a faster model or simpler agent if permitted.
5. Check whether the workspace status page or administrator reports a service
   issue.

### Response Seems Wrong

1. Ask Iris to show assumptions and cite sources.
2. Provide the missing context or correct fact.
3. Regenerate only after tightening the prompt.
4. Use a knowledge base or attachment for source-grounded questions.
5. Escalate high-impact decisions to a human reviewer.

### Iris Does Not Remember Something

Check whether:

- Memory is enabled.
- You asked Iris to remember the fact explicitly.
- The memory was deleted, expired, or stored in a different workspace.
- The active agent has permission to use memory.
- You are in an incognito or privacy-preserving mode.

### File Upload Fails

Check:

- File size and format.
- Whether the file is password-protected or corrupted.
- Your network connection.
- Workspace policy for that file type or sensitivity level.
- Whether the knowledge base or conversation still has storage quota.

### Knowledge Search Misses Relevant Material

Try:

- Confirm the document finished indexing.
- Search by exact title, keyword, and concept.
- Expand the search to more collections or knowledge bases.
- Check document permissions.
- Re-upload a cleaner or newer version of the source.

### Agent Cannot Use a Tool

The agent may be missing permission, the tool may be disabled, required
credentials may be absent, or policy may block the action. Ask Iris to describe
which permission or tool is missing, then contact an administrator if needed.

### Getting Help

When reporting a problem, include:

- Workspace name and app used.
- Conversation or task ID if available.
- Approximate time and timezone.
- Agent and model if visible.
- Error message.
- Steps to reproduce.
- Whether files, memory, tools, or knowledge were involved.

Do not include passwords, API keys, tokens, private keys, or customer secrets in
support requests.

---

## Quick Reference Card

### Common Actions

| Goal                  | Fast path                                                              |
| --------------------- | ---------------------------------------------------------------------- |
| Start fresh           | `Ctrl/Cmd + N` or **New Conversation**.                                |
| Search previous work  | `Ctrl/Cmd + K`.                                                        |
| Add context           | Attach a file or paste a concise summary.                              |
| Stop a response       | Press `Escape` or select **Stop**.                                     |
| Improve an answer     | Ask for a revision with format, audience, and constraints.             |
| Ground in sources     | Name the knowledge base and request citations.                         |
| Teach a preference    | Say `Remember that...` only for facts you want stored.                 |
| Avoid saving context  | Say `Use this only for this conversation; do not save it to memory.`   |
| Export a conversation | Open the conversation menu and choose an available export format.      |
| Check privacy         | Open **Settings > Privacy & Security** and review memory/data options. |

### Prompt Formula

```text
Task:
Context:
Sources or files:
Constraints:
Output format:
What to verify or flag:
```

### Privacy Reminders

- Do not paste secrets or credentials.
- Use local-only mode when cloud processing is not acceptable.
- Use incognito/private conversations for work that should not update memory.
- Delete mistaken uploads or memories promptly.
- Follow your organization's policy for regulated or customer data.

---

## Related Documentation

- [Product Features](./features.md) - Complete feature inventory.
- [Privacy Guide](./privacy-guide.md) - Data controls, deletion, encryption, and
  local-only mode.
- [API Documentation](./api/README.md) - REST, GraphQL, SSE, WebSocket, and gRPC
  contracts.
- [SDK Documentation](./sdk/README.md) - TypeScript SDK and language-specific
  client patterns.
- [Integration Guide](./integration-guide.md) - Application integration, agents,
  tools, memory, and knowledge.
- [Developer Guide](./developer-guide.md) - Local development and contribution
  workflows.
