nixai - AI-Powered NixOS Help System

You are an AI assistant for the nixai project, a modular console-based Linux application that provides AI-powered help for NixOS configuration and troubleshooting.

Project Overview

nixai is a Go-based CLI tool that:

Architecture Guidelines

Code Organization

1. **Entry Point**: `cmd/nixai/main.go` - main application entry

2. **CLI Logic**: `internal/cli` - all command implementations and submodules

3. **AI Integration**: `internal/ai` - LLM provider implementations

4. **MCP Server**: `internal/mcp` - documentation query system

5. **NixOS Tools**: `internal/nixos` - log parsing, diagnostics, command execution

6. **Configuration**: `internal/config` - YAML config management (`configs/default.yaml`)

7. **Logging**: `pkg/logger` - structured logging with configurable levels

8. **Utilities**: `pkg/utils` - file checks, string helpers, formatting

Core Principles

1. **Idiomatic Go**: Write clean, idiomatic Go code with proper error handling

2. **Modularity**: Each feature should be a separate, testable module

3. **Privacy First**: Default to local Ollama inference; use cloud LLMs only when specified

4. **Configuration-Driven**: All settings loaded from YAML via `internal/config`

5. **Testability**: All new features must include tests

6. **Documentation**: Update README.md and docs/MANUAL.md for all changes

AI Provider Implementation

Required Interface

All AI providers in `internal/ai` must implement:

```go

type Provider interface {

Query(ctx context.Context, question string) (string, error)

GenerateResponse(ctx context.Context, prompt string) (string, error)

}

```

Provider Guidelines

1. **Default Provider**: Ollama with `llama3` model (privacy-focused, local)

2. **User Selection**: Allow runtime provider selection via config or flags

3. **Fallback Logic**: Gracefully handle provider unavailability

4. **API Keys**: Store in environment variables, never in config files

5. **Prompt Formatting**: Maintain consistent prompt structure across providers

6. **Direct Questions**: Use `Query` method for `nixai "question"` interface

Feature Implementation

Direct Question Assistant

Support both formats:

Always use the provider's `Query` method for direct questions.

Documentation Query System

Query NixOS documentation from these sources via MCP server (`internal/mcp`):

Handle MCP server unavailability gracefully with clear error messages.

Log & Configuration Diagnostics

1. Accept input via:

- File path argument

- Piped input (stdin)

- Direct command execution

2. Parse using `internal/nixos` package

3. Analyze with LLM provider

4. Return actionable diagnostics

Modular Subcommands

Each submodule should have:

**Supported Submodules**:

Terminal UI Standards

Output Formatting

Use utilities from `pkg/utils`:

```go

utils.FormatHeader("Section Title")

utils.FormatKeyValue("Key", "Value")

utils.FormatDivider()

```

Markdown Rendering

Use `glamour` for Markdown output with syntax highlighting.

Progress Indicators

Show progress for:

Help Menus

All commands must provide:

Development Workflow

Build & Test

Use the `justfile` for common tasks:

Nix Integration

Use `flake.nix` for:

Testing Requirements

1. Add tests for all new features

2. Update existing tests when modifying functionality

3. Ensure test coverage for error cases

4. Test with multiple AI providers

Input Validation & Security

1. **Sanitize User Input**: Validate and sanitize all user-provided data

2. **Log Parsing**: Handle malformed logs gracefully

3. **Command Execution**: Validate NixOS commands before execution

4. **API Keys**: Never log or expose API keys

5. **Error Handling**: Use idiomatic Go error handling with context

Documentation Standards

Code Documentation

User Documentation

Update for all changes:

Examples

Include examples for:

Context7 Integration

When answering questions about frameworks, libraries, or APIs, use Context7 to retrieve current documentation rather than relying on training data. This ensures responses use the latest information.

Error Handling Patterns

1. **Context Propagation**: Pass context through all async operations

2. **Graceful Degradation**: Provide fallbacks when services unavailable

3. **User-Friendly Messages**: Translate technical errors into actionable guidance

4. **Logging**: Log errors at appropriate levels using `pkg/logger`

Best Practices Summary

1. Keep code modular, well-documented, and testable

2. Prefer local Ollama for privacy; support cloud LLMs as option

3. Validate and sanitize all inputs

4. Format terminal output consistently with utilities

5. Provide clear help menus with practical examples

6. Handle piped input and file arguments seamlessly

7. Show progress for long-running operations

8. Update tests and documentation with all changes

9. Use Nix for reproducible builds and development

10. Keep all `.instructions.md` files up to date

Contributing Guidelines

When implementing new features or fixing bugs:

1. Follow the architecture guidelines above

2. Add or update tests for all code changes

3. Update relevant documentation

4. Ensure help menus reflect new functionality

5. Test with multiple AI providers

6. Validate input handling and error cases

7. Run `just lint` and `just test` before committing

8. Update submodule `.instructions.md` if applicable