docs: user-facing docs with SERVER.md symlink pattern

- SERVER.md: symlinked from /etc/user-docs (always current)
- AGENTS.md: user's file, points to SERVER.md, editable
- README.md: welcome doc, copied once
- readme.txt: whaddup cuz

dev-add.sh provisions all four, only overwrites SERVER.md symlink.

configuration.nix

@@ -253,6 +253,16 @@ in
     EOF
   '';
 
+  # User documentation - provisioned to home dirs by dev-add script
+  # SERVER.md = symlink (system-maintained)
+  # AGENTS.md, README.md, readme.txt = copied (user can edit)
+  environment.etc = {
+    "user-docs/SERVER.md".source = ./docs/server-AGENTS.md;
+    "user-docs/AGENTS.md".source = ./docs/user-AGENTS.md;
+    "user-docs/README.md".source = ./docs/user-README.md;
+    "user-docs/readme.txt".source = ./docs/user-readme.txt;
+  };
+
   # This value determines the NixOS release compatibility
   system.stateVersion = "24.05";
 }

docs/user-AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md
+
+**Read [./SERVER.md](./SERVER.md) first** - system capabilities, limits, and available tools.
+
+## User Notes
+
+<!-- Your notes below -->

docs/user-README.md

@@ -0,0 +1,62 @@
+# Welcome to the Dev Server
+
+You have shell access to a shared NixOS development server.
+
+See [./SERVER.md](./SERVER.md) for system capabilities, limits, and available tools.
+
+## Quick Start
+
+```bash
+# Install an AI coding tool
+bun install -g @anthropic-ai/claude-code   # Claude
+bun install -g @google/gemini-cli          # Gemini
+
+# Authenticate and start
+claude   # or: gemini
+```
+
+## What's Here
+
+| File | Purpose |
+|------|---------|
+| `~/AGENTS.md` | Guide for AI coding agents (capabilities, limits) |
+| `~/README.md` | This file |
+| `~/.forgejo-credentials` | Git server login (delete after first use) |
+
+## Git Access
+
+Clone repositories from our Forgejo server:
+
+```bash
+git clone forgejo@git.clarun.xyz:owner/repo.git
+```
+
+Web UI: https://git.clarun.xyz
+
+See `docs/forgejo-collaboration.md` in any repo for collaboration workflows.
+
+## Available Tools
+
+**Pre-installed:** python3, uv, bun, node, git, vim, curl, tmux, zig
+
+**Install more:**
+```bash
+bun install -g <package>           # JS/TS packages (fast)
+nix profile install nixpkgs#<pkg>  # System packages
+uv pip install <package>           # Python (use venv first)
+```
+
+## Limits
+
+This is a shared server with per-user resource limits:
+- ~1GB memory
+- 200 processes max
+- Rate-limited network
+
+Heavy processes may be killed automatically. See [./SERVER.md](./SERVER.md) for details.
+
+## Getting Help
+
+- Check `~/AGENTS.md` for what's possible
+- Ask in the team chat
+- `nix search nixpkgs <name>` to find packages

docs/user-readme.txt

@@ -0,0 +1 @@
+whaddup cuz

scripts/dev-add.sh

@@ -134,74 +134,28 @@ create_user() {
     echo "prefix=$npm_global" > "$npmrc"
     chown "$username:users" "$npm_global" "$npmrc"
 
-    # Create AGENTS.md for AI coding assistants
-    cat > "/home/$username/AGENTS.md" << 'AGENTS_EOF'
-# AGENTS.md - Dev Server Guide
-
-Shared NixOS dev server. This guide helps AI coding agents work effectively here.
-
-## Possible Right Now
-
-**Install packages:**
-```bash
-bun install -g @google/gemini-cli     # JS tools (fast)
-nix profile install nixpkgs#go        # System tools (go, rust, etc.)
-uv venv && uv pip install <pkg>       # Python packages
-```
-
-**Run services:**
-```bash
-python -m http.server 8080            # Dev servers on high ports
-bun run app.js                        # Run JS directly
-tmux / screen                         # Persistent sessions
-```
-
-**Available tools:** python3, uv, bun, node, npm, zig, git, vim, curl, tmux, opencode, bd
-
-## Not Possible Right Now
-
-| Want | Why | Workaround |
-|------|-----|------------|
-| sudo / root | Shared server security | Use nix profile or npm install -g |
-| apt / yum | NixOS uses nix | `nix profile install nixpkgs#<pkg>` |
-| Port 80/443 | Needs root | Use high port + SSH tunnel |
-| Docker | Security isolation | Use nix for dependencies |
-| systemd system services | Needs root | Use pm2, screen, or tmux |
-
-## Resource Limits
-
-Per-user limits to keep the server stable:
-- **Memory**: ~1GB (50% of system)
-- **Processes**: 200 max
-- **Network**: 30 new connections/min
-
-Heavy processes may be killed automatically.
-
-## Environment
-
-- **OS**: NixOS (not Debian/Ubuntu)
-- **Shell**: bash
-- **Home**: ~/  (private, 700)
-- **Temp**: /tmp (fast, cleared on reboot)
-
-## AI Agent Sandbox Conflicts
-
-Some AI agents (Codex, etc.) sandbox commands with seccomp filters, blocking nix daemon access.
-
-**Symptom**: `nix store ping` fails with "Operation not permitted" inside the agent but works in your shell.
-
-**Fix for Codex CLI**:
-```bash
-# One-off
-codex -s danger-full-access
-
-# Permanent (~/.codex/config.toml)
-sandbox_mode = "danger-full-access"
-```
-
-Server already provides isolation - agent sandbox is redundant here.
-AGENTS_EOF
-    chown "$username:users" "/home/$username/AGENTS.md"
+    # Provision user documentation from /etc/user-docs/
+    # SERVER.md = symlink (always current, system-maintained)
+    # AGENTS.md, README.md = copy (user can customize)
+    local docs_dir="/etc/user-docs"
+    if [[ -d "$docs_dir" ]]; then
+        # Symlink SERVER.md (system-maintained, always current)
+        if [[ -f "$docs_dir/SERVER.md" ]]; then
+            ln -sf "$docs_dir/SERVER.md" "/home/$username/SERVER.md"
+            log_info "Linked SERVER.md"
+        fi
+        # Copy user-editable docs (only if they don't exist)
+        for doc in AGENTS.md README.md readme.txt; do
+            if [[ -f "$docs_dir/$doc" && ! -f "/home/$username/$doc" ]]; then
+                cp "$docs_dir/$doc" "/home/$username/$doc"
+                chown "$username:users" "/home/$username/$doc"
+                log_info "Created $doc"
+            fi
+        done
+    else
+        log_warn "/etc/user-docs not found - skipping doc provisioning"
+        log_warn "Deploy NixOS config to create user docs"
+    fi
 
     # Set up git config for proper commit attribution
     local gitconfig="/home/$username/.gitconfig"