chore: update KB index [skip ci]

.github/decisions.md

@@ -0,0 +1,111 @@
+# Decisions — .github Directory
+
+_Last updated: 2025-01-27_
+
+## Purpose
+
+This document tracks decisions made about Gitea Actions workflows, automation, and the .github directory structure. Decisions are documented with context, rationale, and alternatives considered.
+
+---
+
+## Decision Format
+
+Each decision entry includes:
+- **Date**: When the decision was made
+- **Context**: What problem or need prompted this decision
+- **Decision**: What was decided
+- **Rationale**: Why this approach was chosen
+- **Alternatives**: Other options considered
+- **Impact**: What this affects
+
+---
+
+## Decisions
+
+### [2025-01-27] Use Gitea Actions (not GitHub Actions)
+
+**Context**: Repository is hosted on Gitea platform (self-hosted), not GitHub. Need to configure CI/CD automation for repository maintenance.
+
+**Decision**: Use Gitea Actions with GitHub Actions compatibility.
+
+**Rationale**:
+- Gitea Actions uses the same YAML format as GitHub Actions
+- Workflows are compatible and can be migrated seamlessly
+- Same `.github/workflows/` directory structure
+- Familiar syntax for developers
+- No need to learn a different workflow system
+
+**Alternatives Considered**:
+- Use GitHub Actions (not possible - repository is on Gitea)
+- Use external CI/CD service (adds complexity, external dependency)
+- Manual automation (not scalable, error-prone)
+
+**Impact**:
+- All workflows use `.github/workflows/` structure
+- Workflows use standard GitHub Actions YAML format
+- Documentation references "Gitea Actions" with compatibility notes
+- Workflows can be tested and run on Gitea platform
+
+---
+
+### [2025-01-27] Automate KB Index Updates
+
+**Context**: KB index (`kb/_index.md`) must stay current with KB files. Manual updates are error-prone and easy to forget.
+
+**Decision**: Auto-update index on push to main branch when KB files change.
+
+**Rationale**:
+- Reduces manual maintenance burden
+- Ensures index always reflects current KB state
+- Prevents index from becoming stale
+- Automated process is more reliable than manual updates
+- Index generation script already exists and works
+
+**Alternatives Considered**:
+- Manual index updates (error-prone, easy to forget)
+- Update on every push (too frequent, unnecessary commits)
+- Scheduled updates (may miss recent changes)
+
+**Impact**:
+- Index is automatically updated when KB files are added/modified on main
+- Requires `contents: write` permission for workflow
+- Creates automatic commits with index updates
+- Index always reflects current KB state
+
+---
+
+### [2025-01-27] Validate KB Files in CI
+
+**Context**: KB files must follow strict naming and frontmatter rules. Invalid files break the KB system and cause index generation to fail.
+
+**Decision**: Validate KB files on push and pull requests when KB files change.
+
+**Rationale**:
+- Catch errors early before they reach main branch
+- Maintain KB system integrity
+- Prevent invalid files from breaking index generation
+- Provide clear error messages for developers
+- Enforce KB file standards automatically
+
+**Alternatives Considered**:
+- Manual validation (error-prone, easy to miss)
+- Validate only on main branch (errors caught too late)
+- No validation (system breaks with invalid files)
+
+**Impact**:
+- Invalid KB files block commits
+- Developers get immediate feedback on errors
+- KB system maintains high quality standards
+- Requires `contents: read` permission for workflow
+
+---
+
+## Future Decisions
+
+Decisions about new workflows, automation changes, or .github structure modifications should be added here with the same format.
+
+---
+
+**Location**: `.github/decisions.md`  
+**Maintained by**: Tendril Project Team
+