first

ai-agent/AGENTS.md

@@ -0,0 +1,38 @@
+# Workspace Agent Instructions
+
+## Folder Structure & Purpose
+
+- `ai-agent`: Agent workspace for internal notes, chat logs, and todo lists.
+- `code`: Ground truth for all program code. Only source files belong here.
+- `documentation`: User-facing documentation in Markdown format.
+- `tests`: Unit tests only.
+
+**Strict separation:**
+- Agent materials → `ai-agent`
+- Source code → `code`
+- Documentation → `documentation`
+- Tests → `tests`
+
+## Agent Workflow Principles
+
+- Always respect folder boundaries and intended purposes.
+- Never mix code, docs, tests, or agent materials across folders.
+- When generating new files, place them in the correct folder by type.
+- When updating instructions, preserve valuable content and remove outdated or duplicate sections.
+
+## Anti-Patterns
+
+- Do not store code, documentation, or tests in `ai-agent`.
+- Do not place agent notes, logs, or todos in `code`, `documentation`, or `tests`.
+- Do not duplicate content across folders.
+
+## Example Prompts
+
+- "Create a new script in `code` for data processing."
+- "Add a Markdown guide to `documentation` explaining the backup process."
+- "Write unit tests for the backup logic in `tests`."
+- "Store my agent notes in `ai-agent`."
+
+---
+
+For advanced customization, use applyTo-based instructions for specific areas (e.g., frontend, backend, tests) as the project grows.

ai-agent/INSTRUCTIONS-FOLDERS.md

@@ -0,0 +1,41 @@
+# Project folder rules for the AI agent
+
+This file defines what the subfolders are for and how I should use them.
+
+## 1) `ai-agent`
+Purpose: Working directory of the AI agent.
+
+How I use it:
+- I store all the files I need for my work here.
+- I save internal information and notes here.
+- I store previous chat histories here.
+- I create and maintain my to-do lists here.
+
+## 2) `code`
+Purpose: Ground truth of the programme code.
+
+My use:
+- This directory contains only programme code.
+- All source code files are stored here.
+- I treat the content as the authoritative code base.
+
+## 3) `documentation` (technical term: ‘documentation’)
+Purpose: User documentation.
+
+How I use it:
+- I create Markdown documents here to explain the programme functions.
+- I keep the documentation understandable and user-oriented.
+
+## 4) `tests`
+Purpose: Test directory.
+
+How I use it:
+- This is where the unit tests are stored.
+- I create new unit tests in this directory.
+
+## General rule
+I strictly separate content according to purpose:
+- Agent work material only in `ai-agent`
+- Source code only in `code`
+- User documentation only in `documentation`
+- Unit tests only in `tests`

ai-agent/INSTRUCTIONS.md

@@ -0,0 +1,28 @@
+A script is to be created that runs on a TrueNAS server.
+The server contains several datasets and storage hard drives.
+The script is to back up an entire directory from another external server.
+To do this:
+1) The entire directory is to be copied locally (to the storage hard drives) using rsync.
+2) Then, all changes should be versioned with a git commit (local git command).
+
+This workflow is given and will not be changed. 
+No backup tool or Git server will be used. Simply rsync to the disk + git commit. It's that simple.
+
+# Configuration
+No configuration must be in the script. 
+A env file must be used for config.
+
+# Git commit
+
+Only create a new git commit, if something has changed.
+
+# Rsync
+
+No visual feedback or verbos mode needed.
+
+recommended options:
+
+-a  archive mode
+-v  verbose
+-z  compression
+--delete remove deleted files

code/backup_rsync_git.env

@@ -0,0 +1,14 @@
+# Remote rsync source. Example: backup@example.com:/srv/data/project/
+RSYNC_SOURCE="boogie:/home/boogie/nextcloud_data/root/files/Obsidian"
+
+# Local sync destination (must be a directory inside GIT_REPO_DIR)
+RSYNC_TARGET_DIR="/mnt/bfds-nix/rob/backup/Obsidian-daily-git"
+
+# Local monorepo path
+GIT_REPO_DIR="/mnt/bfds-nix/rob/backup/Obsidian-daily-git"
+
+# Prefix for commit message (timestamp is appended automatically)
+COMMIT_MESSAGE_PREFIX="backup: rsync sync"
+
+# Optional: custom SSH command for rsync (leave empty if not needed)
+# RSYNC_RSH="ssh -i /path/to/key -o StrictHostKeyChecking=yes"

code/backup_rsync_git.env.example

@@ -0,0 +1,14 @@
+# Remote rsync source. Example: backup@example.com:/srv/data/project/
+RSYNC_SOURCE="user@example.com:/path/to/source/"
+
+# Local sync destination (must be a directory inside GIT_REPO_DIR)
+RSYNC_TARGET_DIR="/path/to/monorepo/backups/source"
+
+# Local monorepo path
+GIT_REPO_DIR="/path/to/monorepo"
+
+# Prefix for commit message (timestamp is appended automatically)
+COMMIT_MESSAGE_PREFIX="backup: rsync sync"
+
+# Optional: custom SSH command for rsync (leave empty if not needed)
+# RSYNC_RSH="ssh -i /path/to/key -o StrictHostKeyChecking=yes"

code/backup_rsync_git.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -gt 1 ]]; then
+  echo "Usage: $0 [path/to/.env]" >&2
+  exit 2
+fi
+
+ENV_FILE="${1:-$(dirname "$0")/.env}"
+if [[ ! -f "$ENV_FILE" ]]; then
+  echo "Env file not found: $ENV_FILE" >&2
+  exit 1
+fi
+
+# shellcheck disable=SC1090
+source "$ENV_FILE"
+
+required_vars=(
+  RSYNC_SOURCE
+  RSYNC_TARGET_DIR
+  GIT_REPO_DIR
+  COMMIT_MESSAGE_PREFIX
+)
+
+for var in "${required_vars[@]}"; do
+  if [[ -z "${!var:-}" ]]; then
+    echo "Missing required env var: $var" >&2
+    exit 1
+  fi
+done
+
+mkdir -p "$RSYNC_TARGET_DIR"
+
+repo_abs="$(cd "$GIT_REPO_DIR" && pwd)"
+target_abs="$(cd "$RSYNC_TARGET_DIR" && pwd)"
+
+case "$target_abs" in
+  "$repo_abs"/*) ;;
+  *)
+    echo "RSYNC_TARGET_DIR must be inside GIT_REPO_DIR" >&2
+    exit 1
+    ;;
+esac
+
+rel_target="${target_abs#"$repo_abs"/}"
+
+if [[ -n "${RSYNC_RSH:-}" ]]; then
+  rsync -az --delete -e "$RSYNC_RSH" "$RSYNC_SOURCE" "$RSYNC_TARGET_DIR/"
+else
+  rsync -az --delete "$RSYNC_SOURCE" "$RSYNC_TARGET_DIR/"
+fi
+
+git -C "$GIT_REPO_DIR" add -A -- "$rel_target"
+
+if git -C "$GIT_REPO_DIR" diff --cached --quiet -- "$rel_target"; then
+  exit 0
+fi
+
+timestamp="$(date '+%Y-%m-%d %H:%M:%S')"
+git -C "$GIT_REPO_DIR" commit -m "$COMMIT_MESSAGE_PREFIX $timestamp" -- "$rel_target"