# .github Directory

_Last updated: 2025-01-27_

## Purpose

The `.github/` directory contains Gitea Actions workflows, issue templates, and documentation for repository automation and maintenance.

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

---

## Contents

### Workflows (`workflows/`)

Gitea Actions workflows that automate various aspects of the repository:

- **`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`** (this file) - Overview of .github directory structure and purpose
- **`CHANGELOG.md`** - Tracks all changes to workflows and .github folder
- **`decisions.md`** - Documents decisions about workflows, automation, and Gitea Actions
- **`LLM-Usage-Guide--tendril.md`** - LLM instructions for this repository's workflows and automation

---

## Workflow Overview

### KB Lint

- **Triggers**: Push and pull requests when `kb/**/*.md` files change
- **Purpose**: Validates KB file naming, frontmatter, and structure
- **Output**: Pass/fail validation results

### KB Index Update

- **Triggers**: Push to `main` branch when `kb/**/*.md` files change
- **Purpose**: Automatically regenerates `kb/_index.md` when KB files are added or modified
- **Output**: Updated `kb/_index.md` file committed to repository

---

## Maintenance

### When Adding New Workflows

1. **Update `CHANGELOG.md`** - Document the new workflow and its purpose
2. **Update `decisions.md`** - Document why this workflow was added
3. **Update this README** - Add workflow to the overview section
4. **Update `LLM-Usage-Guide--tendril.md`** - Add instructions for the new workflow

### When Modifying Existing Workflows

1. **Update `CHANGELOG.md`** - Document what changed and why
2. **Update `decisions.md`** - Document the decision behind the change
3. **Test workflow** - Verify changes work as expected
4. **Update documentation** - Ensure README and LLM guide reflect changes

### When Removing Workflows

1. **Update `CHANGELOG.md`** - Document removal and reason
2. **Update `decisions.md`** - Document why workflow was removed
3. **Update this README** - Remove from overview
4. **Update `LLM-Usage-Guide--tendril.md`** - Remove references

---

## Gitea Platform Notes

- **Repository**: https://git.parkingmeter.info/Mycelium/tendril
- **Platform**: Gitea (self-hosted)
- **Actions System**: Gitea Actions (compatible with GitHub Actions format)
- **Documentation**: See `docs/GITEA/Gitea-Actions-Guide.md` for Gitea-specific guidance

---

**Location**: `.github/`  
**Maintained by**: Tendril Project Team