magma

# GEMINI.md

This file provides instructional context for Gemini CLI when working in the Magma repository.

## Project Overview

Magma is an IDE for developing prompts for coding agents (like Claude Code, Codex, Gemini CLI, OpenCode, etc.). It uses an Obsidian-compatible markdown "vault" system to manage project knowledge, assemble complex prompts via transclusions, and execute them through LLM integrations (primarily OpenAI).

The core workflow centers around **Sessions**—interactive markdown documents supporting multi-turn conversations—and **Prompts**—standalone prompt documents.

### Key Technologies
- **Elixir**: The core language and runtime.
- **Burrito**: Used to package the Elixir application into a standalone cross-platform CLI binary.
- **Panpipe**: Integration with Pandoc for markdown processing.
- **Obsidian**: The markdown vault is designed to be compatible with the Obsidian note-taking app.

## Building and Running

### Essential Commands
```bash
# Install dependencies
mix deps.get

# Run tests
mix test                             # Run all tests
mix test test/specific_test.exs      # Run specific test file

# Build production release (binary)
make release                         # Executes MIX_ENV=prod mix release

# Install binary to /usr/local/bin
make install

# Format and quality checks
mix format                           # Format code
mix format --check-formatted         # Check formatting (CI)
```

### Magma-Specific Mix Tasks
- `mix magma.vault.init <name>`: Initialize a new Magma vault.
- `mix magma.prompt.gen "Prompt Name"`: Generate a custom prompt document.
- `mix magma.prompt.exec "Prompt Name"`: Execute a prompt via LLM.
- `mix magma.session.import_response "Session Name"`: Import an external response into a session.

## Architecture and Structure

### Core Concepts
1. **Vault System**: Typically located in `docs.magma/`. It contains `sessions/`, `prompts/`, `templates/`, and `magma.config/`.
2. **Document Types**: 
   - `Magma.Prompt`: Standalone prompts.
   - `Magma.Session`: Multi-turn interactive sessions.
   - `Magma.PromptResult`: Results of LLM executions.
   - `Magma.Config.System`: System-wide settings.
3. **Transclusion System**: Uses `[[Document#Section|alias]]` syntax to resolve and include content from other documents recursively. Core logic resides in `Magma.DocumentStruct.TransclusionResolver`.

### Directory Structure
- `lib/magma/`: Core logic (Vault, Document, Prompt, Session, etc.).
- `lib/magma/document_struct/`: Markdown AST and transclusion resolution.
- `lib/mix/tasks/magma/`: CLI command implementations.
- `priv/base_vault/`: Default templates and structure for new vaults.
- `test/`: ExUnit tests and data.

## Development Conventions

### Coding Style
- Follow the [Elixir Style Guide](https://github.com/christopheradams/elixir_style_guide).
- **Error Handling**: Consistently use `{:ok, result} | {:error, reason}` tuples.
- **Path Resolution**: Always use `Magma.Config.vault_path()` for vault-relative paths.

### Testing Practices
- **Test-Driven Development (TDD)**: Write minimal code required to pass tests.
- **Struct Comparison**: Prefer `==` comparisons of complete structs over individual field assertions.
- **Mocks**: Use `Magma.Generation.Mock` for LLM testing and `ExVCR` for HTTP request mocking.

### Documentation
- Use `ExDoc` for module documentation.
- Maintain the User Guide in `docs/user_guide/`.
- Update `CHANGELOG.md` for significant changes.

## Usage
When working with Magma, Gemini should prioritize maintaining the integrity of the transclusion system and the document-based workflow. Ensure that any changes to the vault structure or document handling are reflected in the corresponding `Magma.Document` implementations and Mix tasks.