AI-Studio/AGENTS.md

# AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

MindWork AI Studio is a cross-platform desktop application for interacting with Large Language Models (LLMs). The app uses a hybrid architecture combining a Rust Tauri runtime (for the native desktop shell) with a .NET Blazor Server web application (for the UI and business logic).

**Key Architecture Points:**
- **Runtime:** Rust-based Tauri v1.8 application providing the native window, system integration, and IPC layer
- **App:** .NET 9 Blazor Server application providing the UI and core functionality
- **Communication:** The Rust runtime and .NET app communicate via HTTPS with TLS certificates generated at startup
- **Providers:** Multi-provider architecture supporting OpenAI, Anthropic, Google, Mistral, Perplexity, self-hosted models, and others
- **Plugin System:** Lua-based plugin system for language packs, configuration, and future assistant plugins

## Building

### Prerequisites
- .NET 9 SDK
- Rust toolchain (stable)
- Tauri v1.6.2 CLI: `cargo install --version 1.6.2 tauri-cli`
- Tauri prerequisites (platform-specific dependencies)
- **Note:** Development on Linux is discouraged due to complex Tauri dependencies that vary by distribution

### Build
```bash
cd app/Build
dotnet run build
```
This builds the .NET app as a Tauri "sidecar" binary, which is required even for development.

### Running .NET builds from an agent
- Do not run `.NET` builds such as `dotnet run build`, `dotnet build`, or similar build commands from an agent. Codex agents can hit a known sandbox issue during `.NET` builds, typically surfacing as `CSSM_ModuleLoad()` or other sandbox-related failures.
- Instead, ask the user to run the `.NET` build locally in their IDE and report the result back.
- Recommend the canonical repo build flow for the user: open an IDE terminal in the repository and run `cd app/Build && dotnet run build`.
- If the context fits better, it is also acceptable to ask the user to start the build using their IDE's built-in build action, as long as it is clear the build must be run locally by the user.
- After asking for the build, wait for the user's feedback before diagnosing issues, making follow-up changes, or suggesting the next step.
- Treat the user's build output, error messages, or success confirmation as the source of truth for further troubleshooting.
- For reference: https://github.com/openai/codex/issues/4915

### Running Tests
Currently, no automated test suite exists in the repository.

## Architecture Details

### Rust Runtime (`runtime/`)
**Entry point:** `runtime/src/main.rs`

Key modules:
- `app_window.rs` - Tauri window management, updater integration
- `dotnet.rs` - Launches and manages the .NET sidecar process
- `runtime_api.rs` - Axum-based HTTPS API for .NET ↔ Rust communication
- `certificate.rs` - Generates self-signed TLS certificates for secure IPC
- `secret.rs` - Secure secret storage using OS keyring (Keychain/Credential Manager)
- `clipboard.rs` - Cross-platform clipboard operations
- `file_data.rs` - File processing for RAG (extracts text from PDF, DOCX, XLSX, PPTX, etc.)
- `encryption.rs` - AES-256-CBC encryption for sensitive data
- `pandoc.rs` - Integration with Pandoc for document conversion
- `log.rs` - Logging infrastructure using `flexi_logger`

### .NET App (`app/MindWork AI Studio/`)
**Entry point:** `app/MindWork AI Studio/Program.cs`

Key structure:
- **Program.cs** - Bootstraps Blazor Server, configures Kestrel, initializes encryption and Rust service
- **Provider/** - LLM provider implementations (OpenAI, Anthropic, Google, Mistral, etc.)
  - `BaseProvider.cs` - Abstract base for all providers with streaming support
  - `IProvider.cs` - Provider interface defining capabilities and streaming methods
- **Chat/** - Chat functionality and message handling
- **Assistants/** - Pre-configured assistants (translation, summarization, coding, etc.)
  - `AssistantBase.razor` - Base component for all assistants
- **Agents/** - contains all agents, e.g., for data source selection, context validation, etc.
  - `AgentDataSourceSelection.cs` - Selects appropriate data sources for queries
  - `AgentRetrievalContextValidation.cs` - Validates retrieved context relevance
- **Tools/PluginSystem/** - Lua-based plugin system
- **Tools/Services/** - Core background services (settings, message bus, data sources, updates)
- **Tools/Rust/** - .NET wrapper for Rust API calls
- **Settings/** - Application settings and data models
- **Components/** - Reusable Blazor components
- **Pages/** - Top-level page components

### IPC Communication Flow
1. Rust runtime starts and generates TLS certificate
2. Rust starts internal HTTPS API on random port
3. Rust launches .NET sidecar, passing: API port, certificate fingerprint, API token, secret key
4. .NET reads environment variables and establishes secure HTTPS connection to Rust
5. .NET requests an app port from Rust, starts Blazor Server on that port
6. Rust opens Tauri webview pointing to localhost:app_port
7. Bi-directional communication: .NET ↔ Rust via HTTPS API

### Configuration and Metadata
- `metadata.txt` - Build metadata (version, build time, component versions) read by both Rust and .NET
- `startup.env` - Development environment variables (generated by build script)
- `.NET project` reads metadata.txt at build time and injects as assembly attributes

## Plugin System

**Location:** `app/MindWork AI Studio/Plugins/`

Plugins are written in Lua and provide:
- **Language plugins** - I18N translations (e.g., German language pack)
- **Configuration plugins** - Enterprise IT configurations for centrally managed providers, settings
- **Future:** Assistant plugins for custom assistants

**Example configuration plugin:** `app/MindWork AI Studio/Plugins/configuration/plugin.lua`

Plugins can configure:
- Self-hosted LLM providers
- Update behavior
- Preview features visibility
- Preselected profiles
- Chat templates
- etc.

When adding configuration options, update:
- `app/MindWork AI Studio/Tools/PluginSystem/PluginConfiguration.cs`: In method `TryProcessConfiguration` register new options.
- `app/MindWork AI Studio/Tools/PluginSystem/PluginFactory.Loading.cs`: In method `LoadAll` check for leftover configuration.
- The corresponding data class in `app/MindWork AI Studio/Settings/DataModel/` to call `ManagedConfiguration.Register(...)`, when adding config options (in contrast to complex config. objects)
- `app/MindWork AI Studio/Tools/PluginSystem/PluginConfigurationObject.cs` for parsing logic of complex configuration objects.
- `app/MindWork AI Studio/Plugins/configuration/plugin.lua` to document the new configuration option.

## Tool Calling System

**Documentation:** `documentation/Tools.md`

When adding, changing, or removing model-driven tools, keep these parts in sync:
- `app/MindWork AI Studio/wwwroot/tool_definitions/` for the tool JSON definition.
- `app/MindWork AI Studio/Tools/ToolCallingSystem/ToolCallingImplementations/` for the `IToolImplementation` class.
- `app/MindWork AI Studio/Program.cs` for DI registration of the implementation.
- `app/MindWork AI Studio/Tools/ToolCallingSystem/ToolSelectionRules.cs` when default tool dependencies or minimum provider confidence rules change.
- `app/MindWork AI Studio/Plugins/configuration/plugin.lua` when administrators can configure or manage the tool or its settings.

Tool implementations must treat model-provided arguments as untrusted input. Validate settings and arguments, protect secrets with `SensitiveTraceArgumentNames`, use `ToolExecutionBlockedException` for intentional policy blocks, and check provider confidence before returning sensitive data to the model.

## RAG (Retrieval-Augmented Generation)

RAG integration is currently in development (preview feature). Architecture:
- **External Retrieval Interface (ERI)** - Contract for integrating external data sources
- **Data Sources** - Local files and external data via ERI servers
- **Agents** - AI agents select data sources and validate retrieval quality
- **Embedding providers** - Support for various embedding models
- **Vector database** - Planned integration with Qdrant for vector storage
- **File processing** - Extracts text from PDF, DOCX, XLSX via Rust runtime

## Enterprise IT Support

AI Studio supports centralized configuration for enterprise environments:
- **Registry (Windows)** or **environment variables** (all platforms) specify configuration server URL and ID
- Configuration downloaded as ZIP containing Lua plugin
- Checks for updates every ~16 minutes via ETag
- Allows IT departments to pre-configure providers, settings, and chat templates

**Documentation:** `documentation/Enterprise IT.md`

## Provider Confidence System

Multi-level confidence scheme allows users to control which providers see which data:
- Confidence levels: e.g. `NONE`, `LOW`, `MEDIUM`, `HIGH`, and some more granular levels
- Each assistant/feature can require a minimum confidence level
- Users assign confidence levels to providers based on trust

**Implementation:** `app/MindWork AI Studio/Provider/Confidence.cs`

## Dependencies and Frameworks

**Rust:**
- Tauri 1.8 - Desktop application framework
- Axum - HTTPS API server
- tokio - Async runtime
- keyring - OS keyring integration
- pdfium-render - PDF text extraction
- calamine - Excel file parsing

**.NET:**
- Blazor Server - UI framework
- MudBlazor - Component library
- LuaCSharp - Lua scripting engine
- HtmlAgilityPack - HTML parsing
- ReverseMarkdown - HTML to Markdown conversion

## Security

- **Encryption:** AES-256-CBC with PBKDF2 key derivation for sensitive data
- **IPC:** TLS-secured communication with random ports and API tokens
- **Secrets:** OS keyring for persistent secret storage (API keys, etc.)
- **Sandboxing:** Tauri provides OS-level sandboxing

## Release Process

1. Create changelog file: `app/MindWork AI Studio/wwwroot/changelog/vX.Y.Z.md`
2. Commit changelog
3. Run from `app/Build`: `dotnet run release --action <build|month|year>`
4. Create PR with version bump and changes
5. After PR merge, maintainer creates git tag: `vX.Y.Z`
6. GitHub Actions builds release binaries for all platforms
7. Binaries uploaded to GitHub Releases

## Important Development Notes

- **File changes require Write/Edit tools** - Never use bash commands like `cat <<EOF` or `echo >`
- **End of file formatting** - Do not append an extra empty line at the end of files.
- **No automated formatting for Rust or .NET files** - Never run automated formatters on Rust files (`.rs`) or .NET files (`.cs`, `.razor`, `.csproj`, etc.). Only make the minimal manual formatting changes required for the specific edit.
- **I18N resources are generated** - Do not manually edit `app/MindWork AI Studio/Assistants/I18N/allTexts.lua`, `app/MindWork AI Studio/Plugins/languages/en-us-97dfb1ba-50c4-4440-8dfa-6575daf543c8/plugin.lua`, or `app/MindWork AI Studio/Plugins/languages/de-de-43065dbc-78d0-45b7-92be-f14c2926e2dc/plugin.lua`. These files are updated automatically by the I18N process.
- **Spaces in paths** - Always quote paths with spaces in bash commands
- **Agent-run .NET builds** - Do not run `.NET` builds from an agent. Ask the user to run the build locally in their IDE, preferably via `cd app/Build && dotnet run build` in an IDE terminal, then wait for their feedback before continuing.
- **Debug environment** - Reads `startup.env` file with IPC credentials
- **Production environment** - Runtime launches .NET sidecar with environment variables
- **MudBlazor** - Component library requires DI setup in Program.cs
- **Encryption** - Initialized before Rust service is marked ready
- **Message Bus** - Singleton event bus for cross-component communication inside the .NET app
- **Naming conventions** - Constants, enum members, and `static readonly` fields use `UPPER_SNAKE_CASE` such as `MY_CONSTANT`.
- **Empty lines** - Avoid adding extra empty lines at the end of files.

## Changelogs
Changelogs are located in `app/MindWork AI Studio/wwwroot/changelog/` with filenames `vX.Y.Z.md`. These changelogs are meant to be for normal end-users
and should be written in a non-technical way, focusing on user-facing changes and improvements. Additionally, changes made regarding the plugin system
should be included in the changelog, especially if they affect how users can configure the app or if they introduce new capabilities for plugins. Plugin
developers should also be informed about these changes, as they might need to update their plugins accordingly. When adding entries to the changelog,
please ensure they are clear and concise, avoiding technical jargon where possible. Each entry starts with a dash and a space (`- `) and one of the
following words:

- Added
- Released
- Improved
- Changed
- Fixed
- Updated
- Removed
- Downgraded
- Upgraded

The entire changelog is sorted by these categories in the order shown above. The language used for the changelog is US English.