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.

.beads/.local_version

@@ -1 +1 @@
-0.47.1
+0.49.0

.beads/last-touched

@@ -1 +1 @@
-ops-jrz1-6hu4
+ops-jrz1-mh2

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/forgejo-collaboration.md

@@ -0,0 +1,178 @@
+# Forgejo Collaboration Guide
+
+How dev users collaborate on shared projects via git.clarun.xyz.
+
+## Overview
+
+Forgejo is our self-hosted git server at https://git.clarun.xyz. Dev users get automatic accounts when provisioned via `dev-add.sh`.
+
+## Getting Started
+
+### Your Account
+
+When your account is created, you automatically get:
+- **Forgejo username** matching your Unix username
+- **SSH access** from both your laptop and the dev server
+- **Initial password** in `~/.forgejo-credentials` (change on first login)
+
+### Clone a Repository
+
+```bash
+# From the dev server (or laptop with SSH key registered)
+git clone forgejo@git.clarun.xyz:owner/repo.git
+```
+
+> **Note:** The SSH user is `forgejo`, not `git`.
+
+### Web Interface
+
+Browse repos, manage settings, view history: https://git.clarun.xyz
+
+## Collaboration Models
+
+### Shared Repository (Small Teams)
+
+All collaborators have write access to the same repo.
+
+**Setup:**
+1. Repo owner adds collaborators via web UI (Settings → Collaborators)
+2. Everyone clones the same repo
+3. Use branches for features, merge to main
+
+**Best for:** Trusted teams, internal projects, rapid iteration
+
+### Fork + Pull Request (Open Contribution)
+
+Contributors work on personal forks and submit PRs.
+
+**Setup:**
+1. Fork the repo via web UI
+2. Clone your fork
+3. Push changes to your fork
+4. Create Pull Request to upstream
+
+**Best for:** External contributors, code review gates, open source style
+
+## Recommended Workflow
+
+We use **trunk-based development**:
+
+```
+main (always deployable)
+  │
+  ├── feature-branch (short-lived)
+  │     └── merge back quickly
+  │
+  └── another-feature
+```
+
+### Daily Workflow
+
+```bash
+# Start fresh
+git checkout main
+git pull
+
+# Create feature branch
+git checkout -b add-new-feature
+
+# Make changes, commit often
+git add .
+git commit -m "Add new feature"
+
+# Push and create PR (or merge directly for small teams)
+git push -u origin add-new-feature
+```
+
+### Commit Messages
+
+Keep them clear and concise:
+- ~70 characters for the summary line
+- Reference issue IDs if applicable
+- No emojis or marketing language
+
+## Repository Settings
+
+### Creating a New Repo
+
+**Via Web UI:**
+1. Click "+" → "New Repository"
+2. Choose owner (you or an organization)
+3. Set visibility (public/private)
+
+**Via API (admins):**
+```bash
+TOKEN=$(cat /run/secrets/forgejo-api-token)
+curl -X POST "http://localhost:3000/api/v1/user/repos" \
+  -H "Authorization: token $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-project", "private": false}'
+```
+
+### Adding Collaborators
+
+1. Go to repo → Settings → Collaborators
+2. Search by username
+3. Choose permission level (Read, Write, Admin)
+
+## SSH Configuration
+
+### From Your Laptop
+
+Add to `~/.ssh/config`:
+```
+Host git.clarun.xyz
+    HostName git.clarun.xyz
+    User forgejo
+    IdentityFile ~/.ssh/id_ed25519
+```
+
+Then clone with:
+```bash
+git clone git.clarun.xyz:owner/repo.git
+```
+
+### From the Dev Server
+
+SSH keys are pre-configured. Just clone:
+```bash
+git clone forgejo@git.clarun.xyz:owner/repo.git
+```
+
+## Troubleshooting
+
+### "Permission denied (publickey)"
+
+Your SSH key isn't registered in Forgejo.
+
+**Fix:** 
+1. Go to https://git.clarun.xyz/user/settings/keys
+2. Add your public key (`cat ~/.ssh/id_ed25519.pub`)
+
+### "Repository not found"
+
+Either the repo doesn't exist or you don't have access.
+
+**Fix:**
+- Check the URL spelling
+- Ask the repo owner to add you as a collaborator
+- For private repos, ensure you're authenticated
+
+### Clone works but push fails
+
+You have read access but not write access.
+
+**Fix:** Ask repo owner to grant Write permission in Collaborators settings.
+
+## Best Practices
+
+1. **Pull before starting work** - Avoid merge conflicts
+2. **Small, focused commits** - Easier to review and revert
+3. **Use branches** - Keep main deployable
+4. **Write good commit messages** - Future you will thank you
+5. **Don't commit secrets** - Use environment variables or secret management
+
+## Related Docs
+
+- [Dev Onboarding](dev-onboarding.md) - Full setup guide
+- [Forgejo Admin](forgejo-admin.md) - API tokens and admin operations

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
+    # Provision user documentation from /etc/user-docs/
-    cat > "/home/$username/AGENTS.md" << 'AGENTS_EOF'
+    # SERVER.md = symlink (always current, system-maintained)
-# AGENTS.md - Dev Server Guide
+    # AGENTS.md, README.md = copy (user can customize)
-
+    local docs_dir="/etc/user-docs"
-Shared NixOS dev server. This guide helps AI coding agents work effectively here.
+    if [[ -d "$docs_dir" ]]; then
-
+        # Symlink SERVER.md (system-maintained, always current)
-## Possible Right Now
+        if [[ -f "$docs_dir/SERVER.md" ]]; then
-
+            ln -sf "$docs_dir/SERVER.md" "/home/$username/SERVER.md"
-**Install packages:**
+            log_info "Linked SERVER.md"
-```bash
+        fi
-bun install -g @google/gemini-cli     # JS tools (fast)
+        # Copy user-editable docs (only if they don't exist)
-nix profile install nixpkgs#go        # System tools (go, rust, etc.)
+        for doc in AGENTS.md README.md readme.txt; do
-uv venv && uv pip install <pkg>       # Python packages
+            if [[ -f "$docs_dir/$doc" && ! -f "/home/$username/$doc" ]]; then
-```
+                cp "$docs_dir/$doc" "/home/$username/$doc"
-
+                chown "$username:users" "/home/$username/$doc"
-**Run services:**
+                log_info "Created $doc"
-```bash
+            fi
-python -m http.server 8080            # Dev servers on high ports
+        done
-bun run app.js                        # Run JS directly
+    else
-tmux / screen                         # Persistent sessions
+        log_warn "/etc/user-docs not found - skipping doc provisioning"
-```
+        log_warn "Deploy NixOS config to create user docs"
-
+    fi
-**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"
 
     # Set up git config for proper commit attribution
     local gitconfig="/home/$username/.gitconfig"