tendril/docs/GITEA/LLM-Gitea-Guidelines.md

# LLM Guidelines for Working with Gitea

**Purpose**: Specific guidelines for AI assistants (LLMs) when working with Gitea-based projects like Tendril.

**Last Updated**: 2025-01-27

---

## Core Principles

1. **Always refer to "Gitea"** (not "GitHub") when the platform is Gitea
2. **Note compatibility** when discussing Gitea Actions (compatible with GitHub Actions)
3. **Use Gitea terminology** consistently
4. **Link to Gitea documentation** when referencing features

---

## Terminology Guidelines

### Correct Usage

✅ **Use These Terms**:
- "Gitea" - The platform
- "Gitea Actions" - CI/CD system
- "Gitea Runners" - CI/CD execution environment
- "Gitea instance" - Self-hosted Gitea server
- "Pull Request" or "PR" - Code review (same as GitHub)
- "Issues" - Bug/feature tracking (same as GitHub)
- "Repository" or "Repo" - Code storage (same as GitHub)

❌ **Avoid These Terms** (when referring to Gitea):
- "GitHub" - Wrong platform
- "GitHub Actions" - Should be "Gitea Actions" (but note compatibility)
- "GitHub Runners" - Should be "Gitea Runners"
- "GitHub repository" - Should be "Gitea repository"

### Compatibility Notes

When discussing workflows or Actions:
- ✅ "Gitea Actions workflows (compatible with GitHub Actions format)"
- ✅ "Gitea Actions uses the same YAML format as GitHub Actions"
- ✅ "Workflows use `.github/workflows/` directory (same as GitHub)"

---

## Documentation Standards

### When Creating Documentation

1. **Platform Reference**:
   ```markdown
   This repository uses **Gitea** for version control and collaboration.
   ```

2. **Actions Reference**:
   ```markdown
   This project uses **Gitea Actions** for CI/CD. Gitea Actions is compatible 
   with GitHub Actions, so workflows use the same YAML format and 
   `.github/workflows/` directory structure.
   ```

3. **Repository Links**:
   ```markdown
   Repository: https://git.parkingmeter.info/Mycelium/tendril
   ```

### When Creating Workflow Files

1. **File Location**: `.github/workflows/` (same as GitHub)
2. **YAML Format**: Identical to GitHub Actions
3. **Documentation**: Reference as "Gitea Actions workflows"
4. **Comments**: Note compatibility if relevant

**Example**:
```yaml
# Gitea Actions workflow
# Compatible with GitHub Actions format
name: KB Lint

on:
  push:
    paths:
      - 'kb/**/*.md'
```

### When Updating Cursor Rules

1. **Use "Gitea Actions"** in rules:
   ```markdown
   #### When Gitea Actions workflows (`.github/workflows/*.yml`) are modified:
   ```

2. **Note compatibility**:
   ```markdown
   **Note**: Gitea Actions is compatible with GitHub Actions, so workflows 
   use the same YAML format and `.github/` directory structure.
   ```

---

## Common Scenarios

### Scenario 1: Creating a New Workflow

**What to do**:
1. Create workflow in `.github/workflows/`
2. Use standard GitHub Actions YAML format
3. Document as "Gitea Actions workflow"
4. Note compatibility in documentation
5. Update `.github/CHANGELOG.md`
6. Update `.github/README.md`

**Example documentation**:
```markdown
### KB Lint Workflow

**File**: `.github/workflows/kb-lint.yml`

**Purpose**: Validates KB file naming and frontmatter

**Platform**: Gitea Actions (compatible with GitHub Actions format)

**Triggers**: Runs on push and pull requests when KB files change
```

### Scenario 2: Referencing Repository

**What to do**:
1. Use Gitea repository URL
2. Reference as "Gitea repository"
3. Link to Gitea instance

**Example**:
```markdown
**Repository**: https://git.parkingmeter.info/Mycelium/tendril  
**Platform**: Gitea (self-hosted)
```

### Scenario 3: Discussing Features

**What to do**:
1. Reference Gitea features
2. Note similarities to GitHub when helpful
3. Link to Gitea documentation

**Example**:
```markdown
Gitea supports Pull Requests (similar to GitHub) and also provides 
an AGit workflow alternative. For more information, see the 
[Gitea documentation](https://docs.gitea.com/).
```

---

## File Structure Guidelines

### Workflow Files

- **Location**: `.github/workflows/`
- **Format**: YAML (same as GitHub Actions)
- **Naming**: `kebab-case.yml`
- **Documentation**: Reference as "Gitea Actions workflows"

### Documentation Files

- **Location**: `.github/` or project root
- **Content**: Use "Gitea" terminology
- **Links**: Link to Gitea documentation when relevant

### Cursor Rules

- **Location**: `.cursorrules` or `.cursor/rules/`
- **Content**: Use "Gitea Actions" (not "GitHub Actions")
- **Notes**: Include compatibility notes where relevant

---

## Checklist for LLMs

When working with Gitea-based projects:

- [ ] Use "Gitea" (not "GitHub") when referring to the platform
- [ ] Use "Gitea Actions" (not "GitHub Actions") but note compatibility
- [ ] Reference Gitea repository URLs correctly
- [ ] Link to Gitea documentation: `https://docs.gitea.com/`
- [ ] Note compatibility when discussing workflows
- [ ] Use `.github/workflows/` directory (same as GitHub)
- [ ] Use standard GitHub Actions YAML format for workflows
- [ ] Update `.github/CHANGELOG.md` when modifying workflows
- [ ] Update `.github/README.md` when adding workflows
- [ ] Use Gitea terminology consistently

---

## Quick Reference

### Repository Information

- **Platform**: Gitea (self-hosted)
- **Instance**: git.parkingmeter.info
- **Repository**: https://git.parkingmeter.info/Mycelium/tendril

### Documentation Links

- **Gitea Docs**: https://docs.gitea.com/
- **Gitea Actions**: https://docs.gitea.com/usage/actions/
- **Gitea API**: https://docs.gitea.com/api/

### Key Points

1. Gitea is self-hosted (not GitHub)
2. Gitea Actions is compatible with GitHub Actions
3. Workflows use same format and directory structure
4. Terminology should reference "Gitea" consistently

---

**Location**: `docs/GITEA/LLM-Gitea-Guidelines.md`  
**Related**: `docs/AGENT-GUIDELINES.md`, `.cursorrules`