gadmin/ai-prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Richard Brandon
2026-02-22 15:48:49 +00:00
commit 22c28a27c2
9 changed files with 703 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
CONTRIBUTING.md Normal file
View File

@@ -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/
```

79
README.md Normal file
View File

@@ -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
```

0
arduino/.gitkeep Normal file
View File

65
dotfiles/dotfiles-setup.md Normal file
View File

@@ -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)
```

55
general/git-conventions.md Normal file
View File

@@ -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
```

57
gitea-server/client-ssh-setup.md Normal file
View File

@@ -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.
```

84
gitea-server/new-server-onboarding.md Normal file
View File

@@ -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
```

160
gitea-server/server-briefing.md Normal file
View File

@@ -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

70
multiplan/deployment-pipeline.md Normal file
View File

@@ -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
```