nixos/context

Context Directory

This directory contains concise documentation for discrete units of work performed in this repository.

Purpose

Document specific configurations, changes, and procedures in a concise format. Prefer clarity over verbosity - use inline comments in code when the config is self-documenting.

Organization

File Naming

• Use lowercase, hyphenated names
• Include dates for time-sensitive updates: feature-update-YYYY-MM-DD.md
• Use descriptive names for ongoing configs: service-name.md

File Content

Each file should document:

• What changes were made
• Where the config lives (file paths)
• How to build/test/deploy
• Why the change was made (brief context)

Examples

Service Configuration

# Service Name

**Config:** `servers/service-name.nix`

## Purpose
Brief description of what this service does.

## Build & Deploy
```bash
nixos-rebuild build --flake .#system

Notes

Key points to remember.

### Event/Update Documentation
```markdown
# Feature Update - YYYY-MM-DD

## Changes
- Removed: old-feature
- Added: new-feature

## Resolution
How the issue was solved.

## Build
Build commands if relevant.

When to Create Files

• Major feature additions to services/desktop configs
• Significant refactoring or restructuring
• Security updates requiring special handling
• Cross-service dependencies
• Troubleshooting guides for complex issues

When NOT to Create Files

• Routine package updates
• Self-documenting NixOS configurations
• Trivial changes covered by code comments
• Temporary debugging (use git commits instead)

Related Documentation

• agents.md - Agent instructions and procedures
• README.md - Project overview
• Test scripts in tests/