157 lines
4.5 KiB
Markdown
157 lines
4.5 KiB
Markdown
# Cloonar Assistant LLM Rules
|
|
|
|
This document defines the rules and guidelines for an LLM working with the Cloonar Assistant NixOS module project.
|
|
|
|
## 1. Project Understanding
|
|
|
|
### 1.1 Core Components
|
|
- Network Infrastructure (VLANs, DHCP, DNS, Firewall)
|
|
- Security Services (WireGuard VPN, SSL/ACME)
|
|
- Home Automation (Home Assistant)
|
|
- System Services (Dynamic DNS, Container Management)
|
|
- Development Tools (ISO Builder, VM Testing)
|
|
|
|
### 1.2 Module Architecture
|
|
```mermaid
|
|
graph TD
|
|
A[Cloonar Assistant] --> B[Network Management]
|
|
A --> C[Security]
|
|
A --> D[Services]
|
|
A --> E[Development Tools]
|
|
|
|
B --> B1[VLANs]
|
|
B --> B2[DHCP/Kea]
|
|
B --> B3[DNS/Unbound]
|
|
B --> B4[Firewall/nftables]
|
|
|
|
C --> C1[WireGuard VPN]
|
|
C --> C2[SSL/ACME]
|
|
C --> C3[SOPS Integration]
|
|
|
|
D --> D1[Home Assistant]
|
|
D --> D2[Dynamic DNS]
|
|
D --> D3[Container Services]
|
|
|
|
E --> E1[ISO Builder]
|
|
E --> E2[VM Testing]
|
|
```
|
|
|
|
## 2. NixOS Integration (REQUIRED)
|
|
|
|
### 2.1 Package and Option Verification
|
|
- ALWAYS use the NixOS MCP server to verify packages and options before suggesting them
|
|
- Query format: `use_mcp_tool` with server "nixos" for all NixOS-related lookups
|
|
- Verify package availability in the project's current NixOS version
|
|
- Validate option compatibility and deprecation status
|
|
|
|
### 2.2 Configuration Guidelines
|
|
- All NixOS configurations must be validated through MCP before suggestion
|
|
- Use proper module imports and option declarations
|
|
- Follow NixOS naming conventions and type declarations
|
|
- Consider module dependencies and conflicts
|
|
|
|
## 3. Development Guidelines
|
|
|
|
### 3.1 Code Structure
|
|
- Maintain modular organization in `modules/cloonar-assistant/`
|
|
- Follow existing patterns for option declarations
|
|
- Use descriptive names for options and properties
|
|
- Keep related functionality grouped in appropriate submodules
|
|
|
|
### 3.2 Testing Protocol
|
|
- Utilize the VM testing scripts in `scripts/`
|
|
- Test configuration changes with `test-configuration`
|
|
- Verify VLAN and network functionality in VM environment
|
|
- Ensure proper service container operation
|
|
|
|
## 4. Configuration Support
|
|
|
|
### 4.1 Network Configuration
|
|
- Define appropriate VLANs based on network requirements
|
|
- Configure firewall rules using nftables syntax
|
|
- Set up proper DHCP and DNS services
|
|
- Implement correct routing between VLANs
|
|
|
|
### 4.2 Service Configuration
|
|
- Configure Home Assistant container with proper isolation
|
|
- Set up SSL certificates via ACME
|
|
- Manage WireGuard VPN peers and configurations
|
|
- Configure dynamic DNS updates
|
|
|
|
## 5. Security Best Practices
|
|
|
|
### 5.1 General Security
|
|
- Never expose sensitive information in configurations
|
|
- Use SOPS for secrets management
|
|
- Implement proper network segmentation
|
|
- Follow principle of least privilege
|
|
|
|
### 5.2 Network Security
|
|
- Verify firewall rule correctness
|
|
- Implement proper VLAN isolation
|
|
- Secure VPN configurations
|
|
- Validate SSL certificate management
|
|
|
|
## 6. Troubleshooting Framework
|
|
|
|
### 6.1 Diagnostic Approach
|
|
```mermaid
|
|
flowchart LR
|
|
A[Issue Reported] --> B{Category?}
|
|
B --> C[Network]
|
|
B --> D[Service]
|
|
B --> E[Build]
|
|
|
|
C --> C1[Check VLANs]
|
|
C --> C2[Verify Firewall]
|
|
C --> C3[Test DNS]
|
|
|
|
D --> D1[Container Status]
|
|
D --> D2[Service Logs]
|
|
D --> D3[Dependencies]
|
|
|
|
E --> E1[Nix Errors]
|
|
E --> E2[Option Issues]
|
|
E --> E3[Build Logs]
|
|
```
|
|
|
|
### 6.2 Common Issues
|
|
- VLAN connectivity problems
|
|
- Container networking issues
|
|
- SSL certificate renewal failures
|
|
- Build and configuration errors
|
|
|
|
## 7. Self-Maintenance Rules
|
|
|
|
### 7.1 Rule Update Triggers
|
|
Monitor and update rules.md when:
|
|
- Major NixOS version changes affect module functionality
|
|
- New security considerations emerge
|
|
- Core module features are added/modified
|
|
- Breaking changes in dependencies occur
|
|
|
|
### 7.2 Update Protocol
|
|
1. Identify breaking changes or important updates
|
|
2. Document impact on existing configurations
|
|
3. Update relevant rule sections
|
|
4. Add new guidelines if needed
|
|
5. Update version compatibility information
|
|
|
|
### 7.3 Documentation Sync
|
|
- Keep rules aligned with current codebase
|
|
- Update mermaid diagrams for architectural changes
|
|
- Maintain accurate NixOS version compatibility info
|
|
- Document new features and deprecations
|
|
|
|
### 7.4 Change Validation
|
|
Before updating rules:
|
|
- Verify changes against current codebase
|
|
- Test impact on existing configurations
|
|
- Check NixOS MCP for option/package changes
|
|
- Validate security implications
|
|
|
|
## 8. Version Information
|
|
|
|
- Last Updated: 2025-06-06
|
|
- Compatible NixOS Versions: 23.05, 23.11, 24.05
|
|
- Project Version: Current Master |