From 2d7a67bac966559a3870692025e25c9f8a287e17 Mon Sep 17 00:00:00 2001
From: ashisgreat22 <dev@ashisgreat.xyz>
Date: Wed, 18 Mar 2026 02:42:21 +0100
Subject: [PATCH] Add CLAUDE.md for future Claude Code instances

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..7206846
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a NixOS VPS configuration using flakes. It deploys a private server with:
+- **SearXNG**: Private meta-search engine with Anubis AI firewall protection
+- **OpenClaw**: AI agent with Discord integration (uses ZAI/GLM models)
+- **Nginx**: Reverse proxy with automatic Let's Encrypt certificates
+
+## Commands
+
+### Deploy Configuration
+```bash
+# Apply configuration changes to the system
+sudo nixos-rebuild switch --flake .#nixos
+
+# Dry-run to check configuration without applying
+nixos-rebuild build --flake .#nixos
+
+# Update system with latest nixpkgs
+sudo nixos-rebuild switch --upgrade
+```
+
+### Secrets Management
+```bash
+# Generate a new age key for SOPS
+nix-shell -p age --run "age-keygen -o key.txt"
+
+# Edit encrypted secrets
+nix-shell -p sops --run "sops secrets/secrets.yaml"
+```
+
+### Container Management
+```bash
+# View running containers
+sudo podman ps
+
+# View container logs
+sudo podman logs <container-name>
+
+# Restart a container service
+sudo systemctl restart podman-<container-name>.service
+```
+
+## Architecture
+
+### Module System
+All services are defined as custom modules under `myModules.` namespace in `modules/`:
+
+```
+modules/
+├── default.nix        # Imports all modules
+├── system.nix         # Base system config, packages
+├── podman.nix         # Container runtime setup
+├── nginx.nix          # Reverse proxy + ACME
+├── searxng.nix        # Search engine stack (SearXNG + Valkey + Anubis)
+└── openclaw-podman.nix # AI agent container
+```
+
+### Module Pattern
+Each module follows this structure:
+```nix
+{
+  config, lib, pkgs, ...
+}:
+let
+  cfg = config.myModules.<module-name>;
+in
+{
+  options.myModules.<module-name> = { ... };
+  config = lib.mkIf cfg.enable { ... };
+}
+```
+
+Modules are enabled/configured in `configuration.nix`:
+```nix
+myModules.searxng = {
+  enable = true;
+  port = 8888;
+  domain = "search.example.com";
+};
+```
+
+### Secrets (SOPS)
+- Secrets defined in `secrets/secrets.yaml` (encrypted)
+- SOPS configuration in `.sops.yaml`
+- Secrets are injected into containers via environment files:
+  - `sops.templates."service.env"` creates env file with interpolated secrets
+  - Container references: `environmentFiles = [ config.sops.templates."service.env".path ]`
+
+### Container Networking
+- SearXNG uses a dedicated podman network (`searxng-net`)
+- Services bind to `127.0.0.1` only; Nginx handles external traffic
+- OpenClaw uses `--network=host` for Discord gateway access
+
+### Service Dependencies
+Modules declare dependencies explicitly:
+```nix
+config = lib.mkIf cfg.enable {
+  myModules.podman.enable = true;  # Ensures podman is enabled
+  ...
+};
+```