init: ai-prompts repo with project briefings and onboarding prompts

2026-02-22 15:48:49 +00:00
commit 22c28a27c2
9 changed files with 703 additions and 0 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,133 @@
+# How to Add or Update Prompt Files
+
+This document is for AIs and scripts that need to upload new prompt/rule files
+to this repository programmatically via the Gitea API.
+
+---
+
+## Authentication
+
+All write operations require the API token. The token should be provided
+to you by the server owner (Richard Brandon) at session start.
+
+```
+Gitea URL:  https://g.pozi.co.za
+LAN URL:    http://192.168.0.126:3000
+API token:  (provided by owner — do not hardcode here)
+Repo:       gadmin/ai-prompts
+Branch:     main
+```
+
+---
+
+## Folder / Category Structure
+
+Files MUST be placed inside an appropriate project folder:
+
+| Folder | Use for |
+|--------|---------|
+| `gitea-server/` | Prompts about this git server setup and management |
+| `multiplan/` | Multiplan PHP ERP project prompts and context |
+| `dotfiles/` | Desktop/laptop dotfiles and config management |
+| `arduino/` | Arduino sketches and automation scripts |
+| `general/` | Generic AI rules not tied to a specific project |
+
+To add a new project category, simply use a new folder name — it will
+be created automatically when you upload the first file into it.
+
+---
+
+## File Naming Rules
+
+- Use lowercase, hyphen-separated names
+- Use `.md` for prompt/context/rule documents
+- Use descriptive prefixes:
+  - `context-` — background info to give AI at session start
+  - `setup-` — instructions for setting something up
+  - `rules-` — constraints or rules AI must follow
+  - `prompt-` — a ready-to-use prompt for a specific task
+  - `briefing-` — status briefing for handover between AI sessions
+
+---
+
+## Upload a New File via API
+
+### Check if file already exists (200 = exists, 404 = new)
+```bash
+curl -o /dev/null -w "%{http_code}" \
+  https://g.pozi.co.za/api/v1/repos/gadmin/ai-prompts/contents/FOLDER/FILENAME.md \
+  -H "Authorization: token YOUR_TOKEN"
+```
+
+### Create a new file
+```bash
+# Encode your content as base64 first:
+CONTENT=$(base64 -w 0 < your-file.md)
+
+curl -X POST https://g.pozi.co.za/api/v1/repos/gadmin/ai-prompts/contents/FOLDER/FILENAME.md \
+  -H "Authorization: token YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"message\": \"add: FILENAME — brief description\",
+    \"content\": \"${CONTENT}\",
+    \"branch\": \"main\"
+  }"
+```
+
+### Update an existing file (requires current file SHA)
+```bash
+# Step 1 — get the current file SHA:
+SHA=$(curl -s https://g.pozi.co.za/api/v1/repos/gadmin/ai-prompts/contents/FOLDER/FILENAME.md \
+  -H "Authorization: token YOUR_TOKEN" | python3 -c "import sys,json; print(json.load(sys.stdin)['sha'])")
+
+# Step 2 — encode new content:
+CONTENT=$(base64 -w 0 < your-updated-file.md)
+
+# Step 3 — push the update:
+curl -X PUT https://g.pozi.co.za/api/v1/repos/gadmin/ai-prompts/contents/FOLDER/FILENAME.md \
+  -H "Authorization: token YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"message\": \"update: FILENAME — what changed\",
+    \"content\": \"${CONTENT}\",
+    \"sha\": \"${SHA}\",
+    \"branch\": \"main\"
+  }"
+```
+
+### Delete a file (requires SHA)
+```bash
+SHA=$(curl -s https://g.pozi.co.za/api/v1/repos/gadmin/ai-prompts/contents/FOLDER/FILENAME.md \
+  -H "Authorization: token YOUR_TOKEN" | python3 -c "import sys,json; print(json.load(sys.stdin)['sha'])")
+
+curl -X DELETE https://g.pozi.co.za/api/v1/repos/gadmin/ai-prompts/contents/FOLDER/FILENAME.md \
+  -H "Authorization: token YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"message\": \"remove: FILENAME — reason\", \"sha\": \"${SHA}\", \"branch\": \"main\"}"
+```
+
+---
+
+## Commit Message Convention
+
+```
+add: filename — short description of what it is
+update: filename — what changed and why
+remove: filename — why it was removed
+fix: filename — correction made
+```
+
+---
+
+## Reading Files (no auth needed — repo is public)
+
+```bash
+# Raw file content:
+curl https://g.pozi.co.za/gadmin/ai-prompts/raw/branch/main/FOLDER/FILENAME.md
+
+# File metadata (size, sha, download url):
+curl https://g.pozi.co.za/api/v1/repos/gadmin/ai-prompts/contents/FOLDER/FILENAME.md
+
+# List all files in a folder:
+curl https://g.pozi.co.za/api/v1/repos/gadmin/ai-prompts/contents/FOLDER/
+```
--- a/README.md
+++ b/README.md
@@ -0,0 +1,79 @@
+# AI Prompts & Rules Repository
+
+Public repository of AI prompt rules, context files, and briefing documents
+organised by project. Any AI or server can read these files directly.
+
+**Hosted at:** https://g.pozi.co.za/gadmin/ai-prompts  
+**Owner:** Richard Brandon <richard@teacup.co.za>  
+**Access:** Public read-only. Authenticated write via API token.
+
+---
+
+## How to Use (for AIs and scripts)
+
+### Clone the whole repo
+```bash
+git clone https://g.pozi.co.za/gadmin/ai-prompts.git
+```
+
+### Fetch a single file without cloning
+```bash
+curl https://g.pozi.co.za/gadmin/ai-prompts/raw/branch/main/PROJECT/filename.md
+```
+
+### Pull latest updates into an existing clone
+```bash
+cd ai-prompts && git pull origin main
+```
+
+---
+
+## Folder Structure
+
+```
+ai-prompts/
+├── README.md               ← this file
+├── CONTRIBUTING.md         ← how to add new prompt files (read this)
+│
+├── gitea-server/           ← prompts about this Gitea server setup
+│   ├── server-briefing.md
+│   ├── client-ssh-setup.md
+│   └── new-server-onboarding.md
+│
+├── multiplan/              ← Multiplan PHP ERP project
+│   └── deployment-pipeline.md
+│
+├── dotfiles/               ← desktop/laptop dotfiles management
+│   └── dotfiles-setup.md
+│
+├── arduino/                ← Arduino projects and scripting
+│
+└── general/                ← general-purpose AI rules and prompts
+    └── git-conventions.md
+```
+
+---
+
+## File Naming Convention
+
+```
+PROJECT/
+  context-briefing.md     ← what this project IS (give to AI at session start)
+  setup-THING.md          ← how to set something up
+  rules-THING.md          ← rules/constraints AI must follow
+  prompt-TASK.md          ← prompt to give AI to perform a specific task
+```
+
+---
+
+## Raw File URLs
+
+All files are accessible as raw text at:
+```
+https://g.pozi.co.za/gadmin/ai-prompts/raw/branch/main/<folder>/<file>
+```
+
+Example:
+```bash
+curl https://g.pozi.co.za/gadmin/ai-prompts/raw/branch/main/gitea-server/server-briefing.md
+```
--- a/arduino/.gitkeep
+++ b/arduino/.gitkeep
--- a/dotfiles/dotfiles-setup.md
+++ b/dotfiles/dotfiles-setup.md
@@ -0,0 +1,65 @@
+# Dotfiles Setup — New Machine Onboarding
+
+Give this prompt to an AI on a fresh desktop or laptop install to get
+configs restored from Gitea quickly.
+
+---
+
+## Prompt
+
+```
+I manage my dotfiles and config scripts in a self-hosted Gitea instance.
+Help me restore my setup on this machine.
+
+GITEA SERVER
+------------
+URL:      https://g.pozi.co.za
+LAN URL:  http://192.168.0.126:3000
+User:     gadmin
+
+REPOS TO CLONE (all private — need SSH key set up first)
+---------------------------------------------------------
+  gadmin/dotfiles        → shell configs (.bashrc .zshrc .aliases .profile)
+  gadmin/ssh-config      → ~/.ssh/config and known_hosts
+  gadmin/scripts         → custom scripts for ~/bin or ~/.local/bin
+  gadmin/desktop-config  → DE config (i3/sway/GNOME/KDE, keybindings)
+  gadmin/vim-config      → .vimrc or init.lua
+  gadmin/automounts      → udev rules, systemd mount units, fstab snippets
+
+SETUP ORDER
+-----------
+1. Install git:
+      sudo apt-get install -y git
+
+2. Generate SSH key and add to Gitea (see client-ssh-setup.md):
+      ssh-keygen -t ed25519 -C "richard@teacup.co.za" -f ~/.ssh/id_gitea
+      cat ~/.ssh/id_gitea.pub
+      # Add to https://g.pozi.co.za/user/settings/keys
+
+3. Clone all repos:
+      mkdir -p ~/repos
+      git clone git@192.168.0.126:gadmin/dotfiles.git       ~/repos/dotfiles
+      git clone git@192.168.0.126:gadmin/ssh-config.git     ~/repos/ssh-config
+      git clone git@192.168.0.126:gadmin/scripts.git        ~/repos/scripts
+      git clone git@192.168.0.126:gadmin/desktop-config.git ~/repos/desktop-config
+      git clone git@192.168.0.126:gadmin/vim-config.git     ~/repos/vim-config
+      git clone git@192.168.0.126:gadmin/automounts.git     ~/repos/automounts
+
+4. Run each repo's install.sh to symlink configs into place:
+      cd ~/repos/dotfiles       && ./install.sh
+      cd ~/repos/ssh-config     && ./install.sh
+      cd ~/repos/scripts        && ./install.sh
+      cd ~/repos/desktop-config && ./install.sh
+      cd ~/repos/vim-config     && ./install.sh
+      cd ~/repos/automounts     && ./install.sh
+
+5. Reload shell:
+      source ~/.bashrc   # or ~/.zshrc
+
+NOTES
+-----
+- Each install.sh backs up existing files before symlinking
+- ssh-config repo: only ~/.ssh/config and known_hosts — NO private keys
+- After cloning ssh-config, chmod 600 ~/.ssh/config
+- Use LAN address while on the home network (faster, no port-forward needed)
+```
--- a/general/git-conventions.md
+++ b/general/git-conventions.md
@@ -0,0 +1,55 @@
+# Git Commit Conventions
+
+Standard commit message format used across all repos on this Gitea instance.
+
+## Format
+
+```
+type: short description (max 72 chars)
+
+Optional longer body explaining WHY, not what.
+```
+
+## Types
+
+| Type | Use for |
+|------|---------|
+| `init` | First commit in a repo |
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `update` | Enhancement to existing feature |
+| `chore` | Maintenance — deps, config, ignores |
+| `docs` | Documentation only |
+| `refactor` | Code restructure, no behaviour change |
+| `remove` | Deleting files or features |
+| `deploy` | Deployment-related changes |
+
+## Examples
+
+```
+init: initial dotfiles
+feat: add automount for NAS share
+fix: correct SSH config hostname typo
+update: extend deploy script to restart php-fpm
+chore: add .gitignore for node_modules
+docs: add README for arduino sketches
+remove: drop legacy rsync deploy script
+```
+
+## Branch Naming
+
+```
+main / master   — stable, production-ready
+dev             — active development
+feature/NAME    — specific feature work
+fix/NAME        — specific bug fix
+```
+
+## Tags (for deployments)
+
+```
+v1.0.0    — major release
+v1.2.0    — minor feature addition  
+v1.2.1    — patch / hotfix
+deploy-YYYYMMDD  — deployment snapshot
+```
--- a/gitea-server/client-ssh-setup.md
+++ b/gitea-server/client-ssh-setup.md
@@ -0,0 +1,57 @@
+# Client SSH Setup — Desktop / Laptop
+
+Give this prompt to an AI on a desktop or laptop that needs SSH git access
+to this Gitea server.
+
+---
+
+## Prompt
+
+```
+I need to set up SSH key authentication so I can push and pull git repos
+from a self-hosted Gitea server.
+
+SERVER DETAILS
+--------------
+Gitea URL:       https://g.pozi.co.za
+Admin user:      gadmin
+SSH (LAN):       git@192.168.0.126  port 22
+SSH (external):  git@g.pozi.co.za   port 2222
+
+STEPS
+-----
+1. Generate SSH key (skip if ~/.ssh/id_gitea already exists):
+      ssh-keygen -t ed25519 -C "richard@teacup.co.za" -f ~/.ssh/id_gitea
+
+2. Display the public key to add to Gitea:
+      cat ~/.ssh/id_gitea.pub
+   Add it at: https://g.pozi.co.za/user/settings/keys
+   Give it a descriptive name (e.g. "Desktop-hostname" or "Laptop-hostname")
+
+3. Add to ~/.ssh/config:
+
+   # Gitea — LAN access (same network)
+   Host gitea-lan
+       HostName 192.168.0.126
+       User git
+       Port 22
+       IdentityFile ~/.ssh/id_gitea
+
+   # Gitea — external access (via port-forward)
+   Host g.pozi.co.za
+       HostName g.pozi.co.za
+       User git
+       Port 2222
+       IdentityFile ~/.ssh/id_gitea
+
+4. Test connection:
+      ssh -T git@192.168.0.126        (LAN)
+      ssh -T git@g.pozi.co.za         (external)
+   Expected: "Hi gadmin! You've successfully authenticated..."
+
+5. Clone a repo:
+      git clone git@192.168.0.126:gadmin/REPONAME.git     (LAN)
+      git clone git@g.pozi.co.za:gadmin/REPONAME.git      (external)
+
+NOTE: The public key must be added to Gitea before the SSH test will work.
+```
--- a/gitea-server/new-server-onboarding.md
+++ b/gitea-server/new-server-onboarding.md
@@ -0,0 +1,84 @@
+# New Server Onboarding — Connect to Gitea
+
+Give this prompt to an AI on any new server that needs to connect to this
+Gitea instance and create/push a repository.
+
+---
+
+## Prompt
+
+```
+I need to initialise a git repository on this server and connect it to a
+self-hosted Gitea instance on my LAN. Please help me with the full setup.
+
+GITEA SERVER DETAILS
+--------------------
+Public URL:  https://g.pozi.co.za
+LAN URL:     http://192.168.0.126:3000
+Admin user:  gadmin
+API token:   (request from owner)
+
+SSH ACCESS (use LAN since we are on the same network)
+------------------------------------------------------
+Host:  192.168.0.126
+Port:  22
+User:  git
+Clone format: git@192.168.0.126:gadmin/REPONAME.git
+
+WHAT I NEED YOU TO DO
+----------------------
+1. Check if git is installed:
+      git --version
+   If not, install it (Debian/Ubuntu):
+      apt-get install -y git
+
+2. Identify this server:
+      hostname && cat /etc/os-release | head -5
+
+3. Generate an SSH key for this server:
+      ssh-keygen -t ed25519 -C "$(hostname)@gitea" -f ~/.ssh/id_gitea -N ""
+      cat ~/.ssh/id_gitea.pub
+
+4. Register this server's SSH key with Gitea:
+      curl -X POST http://192.168.0.126:3000/api/v1/user/keys \
+        -H "Authorization: token API_TOKEN_HERE" \
+        -H "Content-Type: application/json" \
+        -d "{\"key\":\"$(cat ~/.ssh/id_gitea.pub)\",\"read_only\":false,\"title\":\"$(hostname)-server\"}"
+
+5. Add ~/.ssh/config entry:
+      mkdir -p ~/.ssh && cat >> ~/.ssh/config << 'EOF'
+
+   Host gitea-lan
+       HostName 192.168.0.126
+       User git
+       Port 22
+       IdentityFile ~/.ssh/id_gitea
+   EOF
+      chmod 600 ~/.ssh/config
+
+6. Test the connection:
+      ssh -T git@192.168.0.126
+   Expected: "Hi gadmin! You've successfully authenticated..."
+
+7. Ask me what to name the repo, then create it and push:
+
+   Create on Gitea:
+      curl -X POST http://192.168.0.126:3000/api/v1/user/repos \
+        -H "Authorization: token API_TOKEN_HERE" \
+        -H "Content-Type: application/json" \
+        -d '{"name":"REPONAME","private":true,"auto_init":false,"default_branch":"main"}'
+
+   Init and push local code:
+      cd /path/to/code
+      git init
+      git remote add origin git@192.168.0.126:gadmin/REPONAME.git
+      git add .
+      git commit -m "init: initial commit from $(hostname)"
+      git push -u origin main
+
+NOTES
+-----
+- Use LAN address 192.168.0.126:22 (not external g.pozi.co.za:2222)
+- Never commit the API token to git
+- Repo visibility defaults to private — confirm with owner before making public
+```
--- a/gitea-server/server-briefing.md
+++ b/gitea-server/server-briefing.md
@@ -0,0 +1,160 @@
+# Gitea Server — Context Briefing
+
+Use this file at the start of any AI session that involves managing this
+Gitea server. Paste its contents to give the AI full context.
+
+---
+
+## Server Identity
+
+| Item | Value |
+|------|-------|
+| Hostname | GITREPO |
+| IP | 192.168.0.126 |
+| OS | Debian GNU/Linux 12 (bookworm) |
+| Role | Self-hosted Gitea git server |
+| Public domain | g.pozi.co.za |
+| Platform | Proxmox LXC container |
+| Disk | 500GB ZFS volume |
+
+---
+
+## Gitea Installation
+
+| Item | Value |
+|------|-------|
+| Version | 1.25.4 |
+| Binary | /usr/local/bin/gitea |
+| Config | /etc/gitea/app.ini |
+| Repo storage | /srv/git |
+| Data/logs | /var/lib/gitea |
+| Service | systemd — gitea.service |
+| Run as user | git (uid 999) |
+| Web port | localhost:3000 (internal only) |
+
+---
+
+## Network / TLS Architecture
+
+```
+Internet
+  └── OPNsense router (public IP)
+        ├── Port 80/443 → Nginx SNI proxy (another LAN server)
+        │     └── g.pozi.co.za (SNI) → 192.168.0.126:443
+        └── Port 2222 → 192.168.0.126:22  (SSH git access, external)
+
+192.168.0.126
+  ├── Nginx :80   — ACME challenge + redirect to HTTPS
+  ├── Nginx :443  — TLS termination (Let's Encrypt cert) + proxy → :3000
+  └── Gitea :3000 — internal only
+```
+
+- TLS cert: Let's Encrypt via Certbot, auto-renews
+- Cert path: /etc/letsencrypt/live/g.pozi.co.za/
+- Nginx config: /etc/nginx/sites-available/g.pozi.co.za
+
+---
+
+## Access Methods
+
+### Web UI
+```
+https://g.pozi.co.za
+```
+
+### API
+```
+Base URL:  https://g.pozi.co.za/api/v1
+LAN URL:   http://192.168.0.126:3000/api/v1
+Token:     (request from owner — stored securely, not in this file)
+Docs:      https://g.pozi.co.za/api/swagger
+```
+
+### SSH (git operations)
+```
+LAN:  git@192.168.0.126:gadmin/REPO.git          (port 22)
+WAN:  git@g.pozi.co.za:gadmin/REPO.git           (port 2222)
+
+~/.ssh/config entry for external access:
+  Host g.pozi.co.za
+      Port 2222
+      User git
+      IdentityFile ~/.ssh/id_gitea
+```
+
+---
+
+## Admin Account
+
+| Item | Value |
+|------|-------|
+| Username | gadmin |
+| Email | richard@teacup.co.za |
+| Name | Richard Brandon |
+| Role | Admin |
+
+---
+
+## Existing Repositories
+
+| Repo | Visibility | Purpose |
+|------|------------|---------|
+| gadmin/multiplan | Private | Multiplan PHP ERP deployment pipeline |
+| gadmin/ai-prompts | Public | AI prompt and rules files (this repo) |
+
+---
+
+## Key File Locations
+
+```
+/etc/gitea/app.ini                          Gitea config
+/etc/nginx/sites-available/g.pozi.co.za    Nginx vhost
+/etc/systemd/system/gitea.service          Systemd service
+/etc/letsencrypt/live/g.pozi.co.za/        TLS certificates
+/srv/git/                                   Bare git repositories
+/var/lib/gitea/                             Gitea data, logs, sessions
+/home/git/.ssh/authorized_keys             SSH keys (managed by Gitea)
+```
+
+---
+
+## Maintenance Commands
+
+```bash
+# Service control
+systemctl status gitea
+systemctl restart gitea
+systemctl status nginx
+
+# Check logs
+journalctl -u gitea -n 50
+tail -f /var/lib/gitea/log/gitea.log
+
+# Certbot renewal (auto via timer, manual test)
+certbot renew --dry-run
+
+# Disk space
+df -h
+
+# Gitea version
+gitea --version
+```
+
+---
+
+## Backup Checklist
+
+Items to back up periodically:
+- `/etc/gitea/app.ini` — config (contains secrets)
+- `/srv/git/` — all bare repo data
+- `/var/lib/gitea/data/gitea.db` — SQLite database (users, keys, settings)
+- `/etc/letsencrypt/` — TLS certs and account
+
+---
+
+## What This Server Does NOT Do
+
+- It does not run application code
+- It does not have a CI/CD runner
+- It does not send email (mailer disabled)
+- It is passive — receives pushes, serves pulls
--- a/multiplan/deployment-pipeline.md
+++ b/multiplan/deployment-pipeline.md
@@ -0,0 +1,70 @@
+# Multiplan — Git Deployment Pipeline Briefing
+
+## Project
+
+Multiplan is a PHP ERP system. Git replaced rsync for deployments.
+
+## Architecture
+
+```
+[Dev Server] --push--> [Gitea: g.pozi.co.za] <--pull-- [Live Server]
+```
+
+## Repo Details
+
+| Item | Value |
+|------|-------|
+| Repo | gadmin/multiplan |
+| Visibility | Private |
+| Branch | master |
+| SSH URL | git@g.pozi.co.za:gadmin/multiplan.git |
+| HTTPS URL | https://g.pozi.co.za/gadmin/multiplan.git |
+
+## SSH Keys Registered
+
+| Key Name | Server |
+|----------|--------|
+| MultiplanServerLive | Live server |
+| dev@multiplan | Dev server |
+
+## Deployment Flow
+
+**Dev → Gitea:**
+```bash
+cd /path/to/multiplan
+git add .
+git commit -m "feat: description of change"
+git push origin master
+```
+
+**Gitea → Live:**
+```bash
+cd /var/www/multiplan.teacuplive.com
+git pull origin master
+```
+
+## Rollback
+
+**On live server:**
+```bash
+cd /var/www/multiplan.teacuplive.com
+git log --oneline           # see all deploy points
+git reset --hard <hash>     # revert to any point instantly
+```
+
+**On dev server:**
+```bash
+git revert <hash>           # safely undo a commit
+git push origin master      # push revert to Gitea
+# Then on live: git pull origin master
+```
+
+## Live Server SSH Config
+
+```
+Host g.pozi.co.za
+    HostName g.pozi.co.za
+    User git
+    Port 2222
+    IdentityFile ~/.ssh/id_gitea
+```