From 3c8f961cdcd20070cafe836b7a76eabc8d7ed6cc Mon Sep 17 00:00:00 2001 From: Dan Date: Thu, 22 Jan 2026 17:12:04 -0800 Subject: [PATCH] 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 | 10 +++++ docs/user-AGENTS.md | 7 ++++ docs/user-README.md | 62 ++++++++++++++++++++++++++++++ docs/user-readme.txt | 1 + scripts/dev-add.sh | 90 +++++++++++--------------------------------- 5 files changed, 102 insertions(+), 68 deletions(-) create mode 100644 docs/user-AGENTS.md create mode 100644 docs/user-README.md create mode 100644 docs/user-readme.txt diff --git a/configuration.nix b/configuration.nix index 2e82f69..2773b16 100644 --- a/configuration.nix +++ b/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"; } diff --git a/docs/user-AGENTS.md b/docs/user-AGENTS.md new file mode 100644 index 0000000..785e7b3 --- /dev/null +++ b/docs/user-AGENTS.md @@ -0,0 +1,7 @@ +# AGENTS.md + +**Read [./SERVER.md](./SERVER.md) first** - system capabilities, limits, and available tools. + +## User Notes + + diff --git a/docs/user-README.md b/docs/user-README.md new file mode 100644 index 0000000..7a7f8f2 --- /dev/null +++ b/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 # JS/TS packages (fast) +nix profile install nixpkgs# # System packages +uv pip install # 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 ` to find packages diff --git a/docs/user-readme.txt b/docs/user-readme.txt new file mode 100644 index 0000000..95e9799 --- /dev/null +++ b/docs/user-readme.txt @@ -0,0 +1 @@ +whaddup cuz diff --git a/scripts/dev-add.sh b/scripts/dev-add.sh index b5f7240..cfc463e 100755 --- a/scripts/dev-add.sh +++ b/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 # 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#` | -| 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"