# LLM Usage Guide for Gitea Actions Workflows — tendril

_Last updated: 2025-01-27_

## Purpose

This guide provides instructions for AI assistants (LLMs) on how to work with Gitea Actions workflows, automation, and the `.github/` directory structure in this repository.

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

---

## Repository Context

**Repository**: tendril  
**Repository URL**: https://git.parkingmeter.info/Mycelium/tendril  
**Platform**: Gitea (self-hosted)  
**Primary System**: Tendril - Zed IDE extension for Gitea integration  
**Automation Focus**: KB system validation and index maintenance

---

## Understanding .github Directory Structure

### Workflows (`workflows/`)

Gitea Actions workflows automate repository operations:

- **`kb-lint.yml`** - Validates KB file naming, frontmatter, and structure
- **`kb-index-update.yml`** - Auto-updates KB index on push to main when KB files change

### Documentation

- **`README.md`** - Overview of .github directory and workflows
- **`CHANGELOG.md`** - Tracks all changes to workflows and .github folder
- **`decisions.md`** - Documents decisions about workflows and automation
- **`LLM-Usage-Guide--tendril.md`** (this file) - LLM instructions for this repo

---

## Working with Workflows

### When Modifying Workflows

**MANDATORY**: When any workflow file is modified:

1. **Update `.github/CHANGELOG.md`**:
   - Add entry with date and description
   - Document what changed and why
   - Include affected workflow name

2. **Update `.github/decisions.md`** (if decision-related):
   - Document the decision behind the change
   - Explain rationale and alternatives considered
   - Note impact on automation

3. **Update `.github/README.md`** (if structure changes):
   - Update workflow descriptions if behavior changed
   - Add new workflows to overview
   - Remove references to deleted workflows

4. **Test the workflow**:
   - Use `workflow_dispatch` trigger if available
   - Verify expected behavior
   - Check for errors in Gitea Actions tab

5. **Consult Gitea documentation**:
   - Reference `docs/GITEA/Gitea-Actions-Guide.md` for Gitea-specific guidance
   - Note any Gitea-specific differences from GitHub Actions

### When Adding New Workflows

1. Create workflow file in `.github/workflows/`
2. Update `.github/CHANGELOG.md` - Document new workflow
3. Update `.github/decisions.md` - Document why workflow was added
4. Update `.github/README.md` - Add to workflow overview
5. Test workflow - Verify it runs successfully
6. Update this guide - Add instructions if needed

### When Removing Workflows

1. Update `.github/CHANGELOG.md` - Document removal and reason
2. Update `.github/decisions.md` - Document why workflow was removed
3. Update `.github/README.md` - Remove from overview
4. Update this guide - Remove references

---

## Workflow-Specific Instructions

### KB Lint Workflow

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

**Purpose**: Validates KB file naming, frontmatter, and structure on push and pull requests

**When to modify**:
- KB validation rules change
- KB file naming pattern changes
- Frontmatter requirements change
- New validation rules needed

**Validation Rules**:
- Filename pattern: `YYYY-MM-DD--slug--type.md`
- Frontmatter must exist and be valid YAML
- All 18 required fields must be present
- Date in frontmatter must match filename date
- Type in frontmatter must match filename type
- `routing_confidence` must be numeric 0.00-1.00
- Files with `routing_confidence < 0.60` must be in `_review_queue/`

**Exclusions**:
- `_guides/`, `_templates/`, `README.md`, `_index.md`, `CHANGELOG.md` are excluded from validation

**Validation**:
- Workflow runs on push and pull requests when `kb/**/*.md` files change
- Provides clear error messages for each validation failure
- Exits with error code if any validation fails

---

### KB Index Update Workflow

**File**: `.github/workflows/kb-index-update.yml`

**Purpose**: Automatically regenerates `kb/_index.md` when KB files change on main branch

**When to modify**:
- Index generation script changes
- Index update logic needs modification
- Commit message format needs change
- Branch name changes (if not using `main`)

**Workflow Steps**:
1. Checkout repository
2. Run `kb/scripts/generate-index.sh`
3. Check if `kb/_index.md` changed
4. If changed, commit and push update
5. Use git user: "Gitea Actions" <actions@gitea.io>

**Validation**:
- Workflow runs on push to `main` branch when `kb/**/*.md` files change
- Excludes `_guides/`, `_templates/`, `README.md`, `_index.md`, `CHANGELOG.md`
- Uses `|| exit 0` to handle case where index hasn't changed
- Requires `contents: write` permission to push changes

---

## Documentation Maintenance

### .github/CHANGELOG.md

**Purpose**: Track all changes to workflows and .github folder

**Format**:
```markdown
## [YYYY-MM-DD] Brief Description

### Added
- New workflow or feature

### Changed
- Modified workflow behavior

### Fixed
- Bug fix or correction
```

**When to update**: Every time a workflow file is modified

### .github/decisions.md

**Purpose**: Document decisions about workflows and automation

**Format**:
```markdown
### [YYYY-MM-DD] Decision Title

**Context**: What prompted this decision
**Decision**: What was decided
**Rationale**: Why this approach
**Alternatives**: Other options considered
**Impact**: What this affects
```

**When to update**: When making significant workflow decisions

---

## Common Tasks

### Adding a New Workflow

1. Create workflow file in `.github/workflows/`
2. Add workflow to `.github/README.md` overview
3. Document in `.github/CHANGELOG.md`
4. Document decision in `.github/decisions.md` (if applicable)
5. Test workflow with `workflow_dispatch` (if available)
6. Commit all changes together

### Modifying an Existing Workflow

1. Make workflow changes
2. Update `.github/CHANGELOG.md` with change description
3. Update `.github/decisions.md` if decision-related
4. Update `.github/README.md` if behavior changed significantly
5. Test workflow
6. Commit changes

---

## Validation Checklist

Before committing workflow changes:

- [ ] Workflow file syntax is valid YAML
- [ ] Workflow tested with `workflow_dispatch` (if available)
- [ ] `.github/CHANGELOG.md` updated with change description
- [ ] `.github/decisions.md` updated (if decision-related)
- [ ] `.github/README.md` updated (if structure/behavior changed)
- [ ] All changes committed together
- [ ] Commit message follows conventional format: `ci(workflows): description`
- [ ] Consulted `docs/GITEA/Gitea-Actions-Guide.md` for Gitea-specific guidance

---

## Gitea-Specific Notes

- **Platform**: Gitea (self-hosted)
- **Actions**: Gitea Actions (compatible with GitHub Actions format)
- **Runners**: Must be configured on Gitea instance
- **Documentation**: See `docs/GITEA/Gitea-Actions-Guide.md` for detailed guidance
- **API**: See `docs/GITEA/Gitea-API-Reference.md` for API differences

---

**Repository**: `tendril`  
**Location**: `.github/LLM-Usage-Guide--tendril.md`  
**Maintained by**: Tendril Project Team