updated docs

pkgs/homelab-docs/readme.nix

@@ -0,0 +1,124 @@
+# homelab-docs-readme.nix - README generator CLI
+{
+  writeShellScriptBin,
+  jq,
+}:
+writeShellScriptBin "homelab-docs-readme" ''
+  #!/usr/bin/env bash
+  set -euo pipefail
+
+  cat << 'EOF'
+  # Homelab Documentation
+
+  > Auto-generated documentation for the homelab deployment
+  >
+  > Generated on: $(date)
+  > Source: $(pwd)
+
+  ## 📚 Documentation Files
+
+  This documentation is automatically generated from your colmena flake configuration.
+
+  ### 📊 Overview Documents
+  - **[Fleet Overview](fleet-overview.md)** - High-level fleet statistics and service distribution
+  - **[Current Deployment](current-deployment.md)** - Current deployment state and node status
+
+  ### 📖 Detailed Configuration
+  - **[Node Configurations](nodes.md)** - Per-node detailed configuration and services
+  - **[Service Configurations](services.md)** - Service configurations across the fleet
+
+  ## 🚀 Quick Actions
+
+  ### View Current Status
+  \`\`\`bash
+  # Service status across fleet (if homelab CLI is available)
+  homelab services --global
+
+  # Backup status
+  homelab backups --global
+
+  # Overall status
+  homelab status
+  \`\`\`
+
+  ### Update Documentation
+  \`\`\`bash
+  # Regenerate all documentation
+  homelab-generate-docs ./docs
+
+  # Generate in different directory
+  homelab-generate-docs /path/to/output
+  \`\`\`
+
+  ## 📋 Quick Stats
+
+  EOF
+
+  # Add live stats
+  quick_stats=$(colmena eval -E '{ nodes, pkgs, lib, ... }:
+    let
+      homelabNodes = lib.filterAttrs (name: node: node.config.homelab.enable or false) nodes;
+    in {
+      totalNodes = lib.length (lib.attrNames nodes);
+      homelabNodes = lib.length (lib.attrNames homelabNodes);
+    }')
+
+  total_nodes=$(echo "$quick_stats" | ${jq}/bin/jq -r '.totalNodes')
+  homelab_nodes=$(echo "$quick_stats" | ${jq}/bin/jq -r '.homelabNodes')
+
+  echo "- **Total Nodes**: $total_nodes"
+  echo "- **Homelab-Enabled Nodes**: $homelab_nodes"
+  echo "- **Generated**: $(date)"
+  echo
+  echo "## 🛠️ Management Tools"
+  echo
+  echo "### Documentation Commands"
+  echo "- \`homelab-generate-docs\` - Regenerate this documentation"
+  echo "- \`homelab-docs-fleet\` - Generate fleet overview only"
+  echo "- \`homelab-docs-nodes\` - Generate node configurations only"
+  echo "- \`homelab-docs-services\` - Generate service configurations only"
+  echo "- \`homelab-docs-deployment\` - Generate deployment state only"
+  echo
+  echo "### Colmena Commands"
+  echo "- \`colmena eval\` - Evaluate flake expressions"
+  echo "- \`colmena apply\` - Deploy configuration changes"
+  echo "- \`colmena build\` - Build configurations without deploying"
+  echo
+  echo "## 🎯 Integration with CI/CD"
+  echo
+  echo "### GitHub Actions Example"
+  echo
+  echo "\`\`\`yaml"
+  echo "name: Generate Documentation"
+  echo "on:"
+  echo "  push:"
+  echo "    branches: [ main ]"
+  echo ""
+  echo "jobs:"
+  echo "  docs:"
+  echo "    runs-on: ubuntu-latest"
+  echo "    steps:"
+  echo "    - uses: actions/checkout@v4"
+  echo "    - uses: cachix/install-nix-action@v24"
+  echo "    - name: Generate docs"
+  echo "      run: nix develop --command homelab-generate-docs ./docs"
+  echo "    - name: Commit docs"
+  echo "      run: |"
+  echo "        git add docs/"
+  echo "        git commit -m \"docs: update homelab documentation\" || exit 0"
+  echo "        git push"
+  echo "\`\`\`"
+  echo
+  echo "### Manual Generation"
+  echo
+  echo "\`\`\`bash"
+  echo "# From your homelab directory"
+  echo "nix develop"
+  echo "homelab-generate-docs ./docs"
+  echo "git add docs/ && git commit -m \"Update docs\""
+  echo "\`\`\`"
+  echo
+  echo "---"
+  echo
+  echo "*This documentation reflects the live state of your homelab deployment as evaluated by colmena.*"
+''