feat(nix): add native flake support with automated lock updates

.github/workflows/update-flake-lock.yml

@@ -0,0 +1,57 @@
+name: Update Flake Lock
+
+on:
+  schedule:
+    - cron: '0 3 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: update-flake-lock
+  cancel-in-progress: false
+
+jobs:
+  update-flake-lock:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@main
+
+      - name: Update flake.lock
+        run: nix flake update
+
+      - name: Validate flake
+        run: nix flake check
+
+      - name: Test build
+        run: nix build .#default
+
+      - name: Commit flake.lock changes
+        run: |
+          if git diff --quiet -- flake.lock; then
+            echo "No flake.lock changes detected"
+            exit 0
+          fi
+
+          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add flake.lock
+          git commit -m "chore(nix): update flake.lock [skip ci]"
+          git push
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "## Flake Lock Update" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ flake update attempted" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ flake check executed" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ build executed" >> $GITHUB_STEP_SUMMARY

README.md

@@ -205,6 +205,25 @@ Add a login endpoint
 
 ---
 
+## For Nix Users
+
+If you use Nix, OAC includes a Home Manager flake module:
+
+```nix
+{
+  programs.opencode.oac = {
+    enable = true;
+    profile = "developer";
+  };
+}
+```
+
+Import `oac.homeManagerModules.default`, then apply with `home-manager switch --flake .#my-user`.
+
+For the full setup, available `programs.opencode.oac.*` options, context reference behavior, bootstrap files, and built-in permission settings, see [docs/getting-started/nix-home-manager.md](docs/getting-started/nix-home-manager.md).
+
+---
+
 ## 💡 The Context System: Your Secret Weapon
 
 **The problem with AI code:** It doesn't match your patterns. You spend hours refactoring.

docs/README.md

@@ -8,6 +8,7 @@ Welcome to the OpenAgents Control documentation! This directory contains all doc
 
 - **[Installation Guide](getting-started/installation.md)** - Complete installation guide with collision handling
 - **[Collision Handling](getting-started/collision-handling.md)** - Quick reference for install script collision strategies
+- **[Nix Home Manager Guide](getting-started/nix-home-manager.md)** - Install OAC with the flake module and configure `programs.opencode.oac`
 
 ### Features
 
@@ -50,7 +51,8 @@ docs/
 ├── README.md                           # This file
 ├── getting-started/
 │   ├── installation.md                 # Installation guide
-│   └── collision-handling.md           # Collision handling reference
+│   ├── collision-handling.md           # Collision handling reference
+│   └── nix-home-manager.md             # Nix/Home Manager flake module guide
 ├── features/
 │   ├── system-builder/
 │   │   ├── README.md                   # System builder quick start
@@ -70,6 +72,9 @@ docs/
 **...install OpenAgents Control**
 → [Installation Guide](getting-started/installation.md)
 
+**...install OpenAgents Control with Nix/Home Manager**
+→ [Nix Home Manager Guide](getting-started/nix-home-manager.md)
+
 **...understand collision handling**
 → [Collision Handling](getting-started/collision-handling.md)
 

docs/getting-started/installation.md

@@ -2,6 +2,8 @@
 
 Complete guide to installing OpenAgents Control components using the automated installer script.
 
+> Use Nix/Home Manager instead? See the [Nix Home Manager Guide](./nix-home-manager.md).
+
 ---
 
 ## Quick Start