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