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