commit 22c28a27c2350b0ac7a944cde85a0738f231cc7b Author: Richard Brandon Date: Sun Feb 22 15:48:49 2026 +0000 init: ai-prompts repo with project briefings and onboarding prompts diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5a899d9 --- /dev/null +++ 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/ +``` diff --git a/README.md b/README.md new file mode 100644 index 0000000..4d16cb3 --- /dev/null +++ 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 +**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// +``` + +Example: +```bash +curl https://g.pozi.co.za/gadmin/ai-prompts/raw/branch/main/gitea-server/server-briefing.md +``` diff --git a/arduino/.gitkeep b/arduino/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/dotfiles/dotfiles-setup.md b/dotfiles/dotfiles-setup.md new file mode 100644 index 0000000..0094726 --- /dev/null +++ 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) +``` diff --git a/general/git-conventions.md b/general/git-conventions.md new file mode 100644 index 0000000..1175ca3 --- /dev/null +++ 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 +``` diff --git a/gitea-server/client-ssh-setup.md b/gitea-server/client-ssh-setup.md new file mode 100644 index 0000000..44055b7 --- /dev/null +++ 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. +``` diff --git a/gitea-server/new-server-onboarding.md b/gitea-server/new-server-onboarding.md new file mode 100644 index 0000000..b13e8d2 --- /dev/null +++ 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 +``` diff --git a/gitea-server/server-briefing.md b/gitea-server/server-briefing.md new file mode 100644 index 0000000..f9e7d2b --- /dev/null +++ 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 diff --git a/multiplan/deployment-pipeline.md b/multiplan/deployment-pipeline.md new file mode 100644 index 0000000..9dcea87 --- /dev/null +++ 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 # revert to any point instantly +``` + +**On dev server:** +```bash +git revert # 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 +```