docs(kb): migrate Gitea documentation to KB system

Migrated all Gitea documentation from docs/GITEA/ folder into the Knowledge Base system, following KB naming conventions and frontmatter requirements. ## What Was Migrated ### Gitea Documentation Guides (6 KB entries) 1. **Gitea Basics Guide** () - Core concepts and features of Gitea - Key differences from GitHub - Terminology and common workflows - System requirements 2. **Gitea Actions Guide** () - Gitea Actions CI/CD system - Compatibility with GitHub Actions - Workflow creation and patterns - Troubleshooting guide 3. **LLM Guidelines for Gitea** () - Terminology guidelines for LLMs - Documentation standards - Common scenarios and checklist - Quick reference 4. **Gitea Workflows Guide** () - Common workflows (repository setup, branches, PRs, issues) - Best practices (branch naming, commits, PR process) - Integration with documentation systems - Troubleshooting 5. **Gitea API Reference** () - API authentication and endpoints - Differences from GitHub API - Common use cases - MCP server integration 6. **Gitea Documentation Overview** () - Overview and index of all Gitea documentation - Quick reference guide - Links to all Gitea KB entries ## KB System Compliance ✅ All files follow KB naming convention (YYYY-MM-DD--slug--type.md) ✅ All files have complete frontmatter (all 18 required fields) ✅ All files categorized in 02_systems/ (infrastructure/tooling) ✅ All files reference original documentation location ✅ KB changelog updated with migration entry ✅ KB index regenerated via script (8 files, 23 topics, 31 tags) ## Category Decision All Gitea documentation entries were placed in **02_systems/** category because: - Gitea is infrastructure/tooling (not project-specific) - Documentation covers platform usage and integration - Guides are system-level references - Fits KB category definition: "Infrastructure, DevOps, tooling" ## Original Documentation Original documentation remains in folder: - docs/GITEA/Gitea-Basics.md - docs/GITEA/Gitea-Actions-Guide.md - docs/GITEA/LLM-Gitea-Guidelines.md - docs/GITEA/Gitea-Workflows.md - docs/GITEA/Gitea-API-Reference.md - docs/GITEA/README.md KB entries reference original locations for full documentation. ## Benefits - Gitea documentation now searchable via KB index - Integrated with KB system for LLM discovery - Consistent with other KB entries - Maintains reference to original documentation - Provides comprehensive Gitea platform reference
2025-11-11 12:36:12 -07:00
parent 197f44b4d3
commit 5b8bf62130
8 changed files with 1255 additions and 5 deletions
--- a/kb/02_systems/2025-11-11--gitea-actions-guide--howto.md
+++ b/kb/02_systems/2025-11-11--gitea-actions-guide--howto.md
@@ -0,0 +1,192 @@
+---
+title: "Gitea Actions Guide"
+date: "2025-11-11"
+captured_at: "2025-11-11"
+author: ["datawarrior"]
+source: { kind: doc, ref: "docs/GITEA/Gitea-Actions-Guide.md" }
+source_type: personal_note
+project: ["tendril"]
+related_projects: ["tendril"]
+topics: ["gitea", "actions", "ci-cd", "workflows", "automation"]
+tags: ["gitea", "actions", "ci-cd", "workflows", "automation", "github-compatible"]
+type: howto
+status: active
+phase_relevance: ["phase-03"]
+routing_hint: "Gitea Actions CI/CD guide - infrastructure/tooling documentation"
+proposed_path: "kb/02_systems/"
+routing_confidence: 0.95
+related: ["docs/GITEA/Gitea-Actions-Guide.md", ".github/workflows/"]
+summary: "Comprehensive guide to Gitea Actions (CI/CD system compatible with GitHub Actions). Covers compatibility, workflow creation, common patterns, troubleshooting, and LLM documentation guidelines."
+key_takeaways: []
+action_candidates: []
+---
+
+# Gitea Actions Guide
+
+## Overview
+
+**Gitea Actions** is Gitea's CI/CD system that is **compatible with GitHub Actions**. This means:
+- Same YAML workflow format
+- Same `.github/workflows/` directory structure
+- Same triggers and syntax
+- Existing GitHub Actions workflows work with minimal or no modifications
+- Actions plugins can be downloaded from any Git website
+
+## Key Compatibility Points
+
+### 1. Directory Structure
+**Same as GitHub**:
+```
+.github/
+└── workflows/
+    ├── workflow1.yml
+    ├── workflow2.yml
+    └── ...
+```
+
+### 2. YAML Format
+**Identical to GitHub Actions** - Same workflow syntax, triggers, jobs, steps
+
+### 3. Triggers
+**Same triggers as GitHub Actions**:
+- `push` - On push to repository
+- `pull_request` - On pull request events
+- `workflow_dispatch` - Manual trigger
+- `schedule` - Scheduled runs (cron syntax)
+- `repository_dispatch` - External events
+
+### 4. Runners
+- **Gitea Runners** (similar to GitHub Runners)
+- Self-hosted runners
+- Can run on various platforms
+- Register runners with Gitea instance
+
+## Differences from GitHub Actions
+
+1. **Actions Marketplace**
+   - GitHub: Centralized marketplace
+   - Gitea: Actions can be downloaded from any Git website
+
+2. **Runner Registration**
+   - GitHub: Runners managed by GitHub (or self-hosted)
+   - Gitea: All runners are self-hosted
+
+3. **Some GitHub-Specific Features**
+   - Some GitHub Actions features may not be available
+   - Check Gitea Actions documentation for specific limitations
+   - Most common workflows work identically
+
+## Common Workflow Patterns
+
+### Linting Workflow
+```yaml
+name: Lint
+
+on:
+  push:
+    paths:
+      - 'src/**/*.rs'
+  pull_request:
+    paths:
+      - 'src/**/*.rs'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run linter
+        run: cargo clippy
+```
+
+### Testing Workflow
+```yaml
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run tests
+        run: cargo test
+```
+
+### Index Update Workflow
+```yaml
+name: Update Index
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'kb/**/*.md'
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Generate index
+        run: ./kb/scripts/generate-index.sh
+      - name: Commit changes
+        run: |
+          git config user.name "Gitea Actions"
+          git config user.email "actions@gitea.io"
+          git add kb/_index.md
+          git commit -m "chore: update KB index" || exit 0
+          git push
+```
+
+## For LLMs: Documentation Guidelines
+
+### When Creating Workflow Documentation
+
+1. **Reference as "Gitea Actions"**:
+   - "This workflow runs in Gitea Actions"
+   - "Gitea Actions will execute this workflow on push"
+
+2. **Note Compatibility**:
+   - "Gitea Actions is compatible with GitHub Actions"
+   - "This workflow uses the same YAML format as GitHub Actions"
+
+3. **Use Correct Terminology**:
+   - "Gitea Actions workflows" (not "GitHub Actions workflows")
+   - "Gitea Runners" (not "GitHub Runners")
+   - But note: "Same format as GitHub Actions"
+
+## Troubleshooting
+
+### Workflow Not Running
+1. Check runner registration
+2. Check workflow syntax
+3. Check triggers
+4. Check permissions
+
+### Actions Not Found
+1. Check action source
+2. Check network access
+3. Use full URL for custom actions
+
+### Runner Issues
+1. Check runner status
+2. Check runner labels
+3. Check runner logs
+
+## References
+
+- **Gitea Actions Docs**: https://docs.gitea.com/usage/actions/
+- **Gitea Runner**: https://docs.gitea.com/usage/actions/runner/
+- **Workflow Syntax**: https://docs.gitea.com/usage/actions/usage/
+
+---
+
+**Original Location**: `docs/GITEA/Gitea-Actions-Guide.md`  
+**Last Updated**: 2025-01-27  
+**Related**: 
+- `.github/workflows/` - Workflow files
+- `docs/GITEA/Gitea-Basics.md`
+- `docs/GITEA/Gitea-Workflows.md`
+
--- a/kb/02_systems/2025-11-11--gitea-api-reference--howto.md
+++ b/kb/02_systems/2025-11-11--gitea-api-reference--howto.md
@@ -0,0 +1,239 @@
+---
+title: "Gitea API Reference"
+date: "2025-11-11"
+captured_at: "2025-11-11"
+author: ["datawarrior"]
+source: { kind: doc, ref: "docs/GITEA/Gitea-API-Reference.md" }
+source_type: personal_note
+project: ["tendril"]
+related_projects: ["tendril"]
+topics: ["gitea", "api", "programming", "integration", "mcp"]
+tags: ["gitea", "api", "programming", "integration", "mcp", "rest-api"]
+type: howto
+status: active
+phase_relevance: []
+routing_hint: "Gitea API reference guide - infrastructure/tooling documentation"
+proposed_path: "kb/02_systems/"
+routing_confidence: 0.95
+related: ["docs/GITEA/Gitea-API-Reference.md", "src/mcp_server_gitea.rs"]
+summary: "API differences and considerations when working with Gitea programmatically. Covers authentication, common endpoints, differences from GitHub API, and MCP server integration for Tendril."
+key_takeaways: []
+action_candidates: []
+---
+
+# Gitea API Reference
+
+## Overview
+
+Gitea provides a REST API that is **similar to GitHub's API** but not identical. The API allows programmatic access to repositories, issues, pull requests, and more.
+
+**Base URL**: `https://your-gitea-instance.com/api/v1`
+
+For Tendril: `https://git.parkingmeter.info/api/v1`
+
+## Authentication
+
+### Personal Access Token
+
+**Creating a token**:
+1. Log in to Gitea
+2. Go to Settings → Applications → Generate New Token
+3. Set name and permissions
+4. Copy token
+
+**Using token**:
+```bash
+curl -H "Authorization: token YOUR_TOKEN" \
+  https://git.parkingmeter.info/api/v1/user
+```
+
+**In code** (Rust example):
+```rust
+let client = reqwest::Client::new();
+let response = client
+    .get("https://git.parkingmeter.info/api/v1/user")
+    .header("Authorization", format!("token {}", token))
+    .send()
+    .await?;
+```
+
+## Common Endpoints
+
+### User Information
+
+**Get authenticated user**:
+```
+GET /api/v1/user
+```
+
+**Get user by username**:
+```
+GET /api/v1/users/{username}
+```
+
+### Repositories
+
+**List repositories**:
+```
+GET /api/v1/user/repos
+GET /api/v1/users/{username}/repos
+GET /api/v1/orgs/{org}/repos
+```
+
+**Get repository**:
+```
+GET /api/v1/repos/{owner}/{repo}
+```
+
+**Create repository**:
+```
+POST /api/v1/user/repos
+```
+
+### Issues
+
+**List issues**:
+```
+GET /api/v1/repos/{owner}/{repo}/issues
+```
+
+**Get issue**:
+```
+GET /api/v1/repos/{owner}/{repo}/issues/{index}
+```
+
+**Create issue**:
+```
+POST /api/v1/repos/{owner}/{repo}/issues
+```
+
+### Pull Requests
+
+**List pull requests**:
+```
+GET /api/v1/repos/{owner}/{repo}/pulls
+```
+
+**Get pull request**:
+```
+GET /api/v1/repos/{owner}/{repo}/pulls/{index}
+```
+
+**Create pull request**:
+```
+POST /api/v1/repos/{owner}/{repo}/pulls
+```
+
+## Differences from GitHub API
+
+### 1. Base URL
+- **GitHub**: `https://api.github.com`
+- **Gitea**: `https://your-instance.com/api/v1`
+
+### 2. Issue/PR Numbers
+- **GitHub**: Uses sequential numbers across repository
+- **Gitea**: Uses index (similar, but may differ in some cases)
+
+### 3. Some Endpoints
+- Gitea may have different endpoints for some operations
+- Check Gitea API documentation for specific endpoints
+- Most common operations are similar
+
+### 4. Webhooks
+- Gitea webhooks are compatible with GitHub format
+- Same payload structure
+- Same event types (push, pull_request, etc.)
+
+## For LLMs: API Usage Guidelines
+
+### When Documenting API Usage
+
+**Reference Gitea API**:
+```markdown
+## API Integration
+
+This project uses the **Gitea API** for programmatic access.
+
+**Base URL**: `https://git.parkingmeter.info/api/v1`
+
+**Authentication**: Personal Access Token
+
+**Example**:
+```bash
+curl -H "Authorization: token YOUR_TOKEN" \
+  https://git.parkingmeter.info/api/v1/user/repos
+```
+```
+
+### When Creating API Clients
+
+**Use Gitea base URL**:
+```rust
+const GITEA_BASE_URL: &str = "https://git.parkingmeter.info/api/v1";
+```
+
+**Use Gitea authentication**:
+```rust
+let client = reqwest::Client::new();
+let response = client
+    .get(&format!("{}/user", GITEA_BASE_URL))
+    .header("Authorization", format!("token {}", token))
+    .send()
+    .await?;
+```
+
+## Common Use Cases
+
+### 1. Listing Repositories
+
+```bash
+curl -H "Authorization: token YOUR_TOKEN" \
+  https://git.parkingmeter.info/api/v1/user/repos
+```
+
+### 2. Creating an Issue
+
+```bash
+curl -X POST \
+  -H "Authorization: token YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"New Issue","body":"Issue description"}' \
+  https://git.parkingmeter.info/api/v1/repos/owner/repo/issues
+```
+
+### 3. Creating a Pull Request
+
+```bash
+curl -X POST \
+  -H "Authorization: token YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"PR Title","head":"feature-branch","base":"main"}' \
+  https://git.parkingmeter.info/api/v1/repos/owner/repo/pulls
+```
+
+## MCP Server Integration
+
+**Tendril** uses the Gitea MCP server for integration with Zed IDE. The MCP server provides:
+
+- Repository management
+- Issue management
+- Pull request management
+- File operations
+- And more
+
+**Reference**: See `src/mcp_server_gitea.rs` for implementation details.
+
+## References
+
+- **Gitea API Docs**: https://docs.gitea.com/api/
+- **API Overview**: https://docs.gitea.com/api/overview/
+- **Authentication**: https://docs.gitea.com/api/authentication/
+
+---
+
+**Original Location**: `docs/GITEA/Gitea-API-Reference.md`  
+**Last Updated**: 2025-01-27  
+**Related**: 
+- `src/mcp_server_gitea.rs` - MCP server implementation
+- `docs/GITEA/Gitea-Basics.md`
+
--- a/kb/02_systems/2025-11-11--gitea-basics-guide--howto.md
+++ b/kb/02_systems/2025-11-11--gitea-basics-guide--howto.md
@@ -0,0 +1,110 @@
+---
+title: "Gitea Basics Guide"
+date: "2025-11-11"
+captured_at: "2025-11-11"
+author: ["datawarrior"]
+source: { kind: doc, ref: "docs/GITEA/Gitea-Basics.md" }
+source_type: personal_note
+project: ["tendril"]
+related_projects: ["tendril"]
+topics: ["gitea", "platform", "basics", "documentation"]
+tags: ["gitea", "basics", "guide", "platform", "self-hosted", "documentation"]
+type: howto
+status: active
+phase_relevance: []
+routing_hint: "Gitea platform basics guide - infrastructure/tooling documentation"
+proposed_path: "kb/02_systems/"
+routing_confidence: 0.95
+related: ["docs/GITEA/Gitea-Basics.md"]
+summary: "Comprehensive guide to Gitea platform basics including core concepts, features, differences from GitHub, terminology, and common workflows. Reference documentation for LLMs working with Gitea-based projects."
+key_takeaways: []
+action_candidates: []
+---
+
+# Gitea Basics Guide
+
+## Overview
+
+**Gitea** is a painless, self-hosted, all-in-one software development service. It includes Git hosting, code review, issue tracking, CI/CD, package registry, and team collaboration tools.
+
+**Key Point**: Gitea is similar to GitHub, Bitbucket, and GitLab, but is designed to be lightweight and self-hosted.
+
+## Core Features
+
+1. **Code Hosting** - Repository management, commit history, code browsing
+2. **Code Review** - Pull Request workflow (same as GitHub) and AGit workflow (Gitea-specific)
+3. **Issue Tracking** - Requirements, features, bugs with assignments, milestones, dependencies
+4. **CI/CD** - Gitea Actions (compatible with GitHub Actions)
+5. **Package Registry** - 20+ package types (Cargo, npm, PyPI, Maven, etc.)
+6. **Security** - User permissions, ACLs, security-focused design
+
+## Key Differences from GitHub
+
+1. **Self-Hosted** - Runs on your own infrastructure
+2. **Lightweight** - Fast and resource-efficient
+3. **Open Source** - MIT licensed, community-driven
+4. **Actions Compatibility** - Same format as GitHub Actions
+5. **API Differences** - Similar but not identical to GitHub's API
+
+## Terminology
+
+### Same as GitHub
+- Repository/Repo, Branch, Pull Request/PR, Issue, Commit, Tag, Fork, Clone
+
+### Gitea-Specific
+- **AGit workflow** - Alternative to Pull Request workflow
+- **Gitea Actions** - CI/CD system (compatible with GitHub Actions)
+- **Self-hosted** - Running on your own infrastructure
+
+## Common Workflows
+
+### Creating a Repository
+1. Log in to Gitea instance
+2. Click "New Repository"
+3. Configure settings
+4. Push code or initialize with README
+
+### Creating a Pull Request
+1. Create a branch
+2. Make changes and commit
+3. Push branch to Gitea
+4. Click "New Pull Request"
+5. Review and merge (same as GitHub)
+
+### Using Gitea Actions
+1. Create `.github/workflows/` directory
+2. Write workflow YAML (same format as GitHub Actions)
+3. Push to repository
+4. Gitea Actions will execute workflows
+
+## For LLMs: Important Notes
+
+- Always refer to "Gitea" (not "GitHub") when the platform is Gitea
+- Note that Gitea Actions is compatible with GitHub Actions
+- Use Gitea terminology consistently
+- Link to Gitea documentation: `https://docs.gitea.com/`
+
+## System Requirements
+
+- **Minimum**: Raspberry Pi 3 (for small workloads)
+- **Typical**: 2 CPU cores, 1GB RAM (for small teams/projects)
+- **Git**: Version 2.0.0 or later required
+- **Platforms**: Linux, macOS, Windows (x86, amd64, ARM, PowerPC)
+
+## References
+
+- **Gitea Documentation**: https://docs.gitea.com/
+- **Gitea Features**: https://docs.gitea.com/installation/comparison#general-features
+- **Gitea Actions**: https://docs.gitea.com/usage/actions/
+- **Gitea API**: https://docs.gitea.com/api/
+
+---
+
+**Original Location**: `docs/GITEA/Gitea-Basics.md`  
+**Last Updated**: 2025-01-27  
+**Related**: 
+- `docs/GITEA/Gitea-Actions-Guide.md`
+- `docs/GITEA/Gitea-Workflows.md`
+- `docs/GITEA/LLM-Gitea-Guidelines.md`
+- `docs/GITEA/Gitea-API-Reference.md`
+
--- a/kb/02_systems/2025-11-11--gitea-documentation-overview--note.md
+++ b/kb/02_systems/2025-11-11--gitea-documentation-overview--note.md
@@ -0,0 +1,133 @@
+---
+title: "Gitea Documentation Overview"
+date: "2025-11-11"
+captured_at: "2025-11-11"
+author: ["datawarrior"]
+source: { kind: doc, ref: "docs/GITEA/README.md" }
+source_type: personal_note
+project: ["tendril"]
+related_projects: ["tendril"]
+topics: ["gitea", "documentation", "overview", "platform"]
+tags: ["gitea", "documentation", "overview", "platform", "self-hosted", "reference"]
+type: note
+status: active
+phase_relevance: []
+routing_hint: "Gitea documentation overview and index - infrastructure/tooling documentation"
+proposed_path: "kb/02_systems/"
+routing_confidence: 0.95
+related: ["docs/GITEA/README.md"]
+summary: "Overview of Gitea documentation directory. Provides quick reference for Gitea platform basics, Actions, workflows, API, and LLM guidelines. Index to all Gitea-related documentation."
+key_takeaways: []
+action_candidates: []
+---
+
+# Gitea Documentation Overview
+
+## Purpose
+
+This directory contains documentation to help AI assistants (LLMs) understand and work with Gitea, a self-hosted Git service.
+
+## What is Gitea?
+
+**Gitea** is a painless, self-hosted, all-in-one software development service. It includes Git hosting, code review, team collaboration, package registry, and CI/CD. It is similar to GitHub, Bitbucket and GitLab.
+
+**Key Reference**: [Gitea Official Documentation](https://docs.gitea.com/)
+
+## Documentation Contents
+
+### Core Guides
+
+- **[Gitea-Basics.md](./Gitea-Basics.md)** - Core concepts, features, and how Gitea differs from GitHub
+- **[Gitea-Actions-Guide.md](./Gitea-Actions-Guide.md)** - Gitea Actions (CI/CD) compatibility and usage
+- **[Gitea-Workflows.md](./Gitea-Workflows.md)** - Common workflows and best practices
+- **[Gitea-API-Reference.md](./Gitea-API-Reference.md)** - API differences and considerations
+- **[LLM-Gitea-Guidelines.md](./LLM-Gitea-Guidelines.md)** - Guidelines for LLMs working with Gitea
+
+## Quick Reference
+
+### What is Gitea?
+
+Gitea is a self-hosted Git service that provides:
+- Git hosting and repository management
+- Code review (Pull Requests and AGit workflow)
+- Issue tracking and project management
+- CI/CD via Gitea Actions (compatible with GitHub Actions)
+- Package registry (20+ package types)
+- Team collaboration tools
+
+### Key Differences from GitHub
+
+1. **Self-Hosted**: Gitea runs on your own infrastructure
+2. **Lightweight**: Designed to be fast and resource-efficient
+3. **Open Source**: MIT licensed, community-driven
+4. **Actions Compatibility**: Gitea Actions uses the same YAML format as GitHub Actions
+5. **API Compatibility**: Gitea API is similar to GitHub's but has some differences
+
+### Gitea Actions Compatibility
+
+**Critical**: Gitea Actions is compatible with GitHub Actions:
+- Same `.github/workflows/` directory structure
+- Same YAML workflow format
+- Same triggers and syntax
+- Existing GitHub Actions workflows work with minimal or no modifications
+- Actions plugins can be downloaded from any Git website
+
+**Reference**: [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/)
+
+## For LLMs Working with Gitea
+
+### Terminology
+
+- Use **"Gitea"** (not "GitHub") when referring to the platform
+- Use **"Gitea Actions"** (not "GitHub Actions") but note compatibility
+- Use **"Pull Request"** or **"PR"** (same as GitHub)
+- Use **"Issues"** (same as GitHub)
+- Use **"Repository"** or **"Repo"** (same as GitHub)
+
+### Documentation References
+
+When creating documentation:
+- Reference Gitea-specific features when relevant
+- Note GitHub Actions compatibility when discussing workflows
+- Use Gitea terminology consistently
+- Link to Gitea documentation: `https://docs.gitea.com/`
+
+### Workflow Files
+
+- Workflows use `.github/workflows/` directory (same as GitHub)
+- YAML format is identical to GitHub Actions
+- Reference as "Gitea Actions workflows" in documentation
+- Note compatibility: "Gitea Actions is compatible with GitHub Actions"
+
+## Repository Context
+
+**Tendril Repository**: https://git.parkingmeter.info/Mycelium/tendril  
+**Gitea Instance**: Self-hosted at git.parkingmeter.info  
+**Primary Platform**: Gitea (not GitHub)
+
+## Additional Resources
+
+- **Official Gitea Docs**: https://docs.gitea.com/
+- **Gitea Actions**: https://docs.gitea.com/usage/actions/
+- **Gitea API**: https://docs.gitea.com/api/
+- **Gitea Source**: https://gitea.com/gitea/gitea
+
+## KB Entries
+
+All Gitea documentation has been migrated to KB system:
+
+- `kb/02_systems/2025-11-11--gitea-basics-guide--howto.md` - Gitea basics
+- `kb/02_systems/2025-11-11--gitea-actions-guide--howto.md` - Gitea Actions
+- `kb/02_systems/2025-11-11--gitea-llm-guidelines--howto.md` - LLM guidelines
+- `kb/02_systems/2025-11-11--gitea-workflows-guide--howto.md` - Workflows
+- `kb/02_systems/2025-11-11--gitea-api-reference--howto.md` - API reference
+- `kb/02_systems/2025-11-11--gitea-documentation-overview--note.md` - This overview
+
+---
+
+**Original Location**: `docs/GITEA/README.md`  
+**Last Updated**: 2025-01-27  
+**Related**: 
+- All Gitea documentation files in `docs/GITEA/`
+- All Gitea KB entries in `kb/02_systems/`
+
--- a/kb/02_systems/2025-11-11--gitea-llm-guidelines--howto.md
+++ b/kb/02_systems/2025-11-11--gitea-llm-guidelines--howto.md
@@ -0,0 +1,174 @@
+---
+title: "LLM Guidelines for Working with Gitea"
+date: "2025-11-11"
+captured_at: "2025-11-11"
+author: ["datawarrior"]
+source: { kind: doc, ref: "docs/GITEA/LLM-Gitea-Guidelines.md" }
+source_type: personal_note
+project: ["tendril"]
+related_projects: ["tendril"]
+topics: ["gitea", "llm", "guidelines", "documentation", "terminology"]
+tags: ["gitea", "llm", "guidelines", "documentation", "terminology", "best-practices"]
+type: howto
+status: active
+phase_relevance: []
+routing_hint: "LLM guidelines for Gitea - infrastructure/tooling documentation"
+proposed_path: "kb/02_systems/"
+routing_confidence: 0.95
+related: ["docs/GITEA/LLM-Gitea-Guidelines.md", ".cursorrules"]
+summary: "Specific guidelines for AI assistants (LLMs) when working with Gitea-based projects. Covers terminology, documentation standards, workflow file creation, and common scenarios."
+key_takeaways: []
+action_candidates: []
+---
+
+# LLM Guidelines for Working with Gitea
+
+## 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
+2. **Note compatibility** where relevant
+
+## 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`
+
+### Scenario 2: Referencing Repository
+
+**What to do**:
+1. Use Gitea repository URL
+2. Reference as "Gitea repository"
+3. Link to Gitea instance
+
+### Scenario 3: Discussing Features
+
+**What to do**:
+1. Reference Gitea features
+2. Note similarities to GitHub when helpful
+3. Link to Gitea documentation
+
+## 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
+
+---
+
+**Original Location**: `docs/GITEA/LLM-Gitea-Guidelines.md`  
+**Last Updated**: 2025-01-27  
+**Related**: 
+- `docs/AGENT-GUIDELINES.md`
+- `.cursorrules`
+- `docs/GITEA/Gitea-Basics.md`
+
--- a/kb/02_systems/2025-11-11--gitea-workflows-guide--howto.md
+++ b/kb/02_systems/2025-11-11--gitea-workflows-guide--howto.md
@@ -0,0 +1,230 @@
+---
+title: "Gitea Workflows Guide"
+date: "2025-11-11"
+captured_at: "2025-11-11"
+author: ["datawarrior"]
+source: { kind: doc, ref: "docs/GITEA/Gitea-Workflows.md" }
+source_type: personal_note
+project: ["tendril"]
+related_projects: ["tendril"]
+topics: ["gitea", "workflows", "best-practices", "git", "collaboration"]
+tags: ["gitea", "workflows", "best-practices", "git", "pull-requests", "issues", "branches"]
+type: howto
+status: active
+phase_relevance: []
+routing_hint: "Gitea workflows and best practices guide - infrastructure/tooling documentation"
+proposed_path: "kb/02_systems/"
+routing_confidence: 0.95
+related: ["docs/GITEA/Gitea-Workflows.md"]
+summary: "Common workflows and best practices for working with Gitea repositories. Covers repository setup, branch management, pull requests, issues, Gitea Actions, and integration with documentation systems."
+key_takeaways: []
+action_candidates: []
+---
+
+# Gitea Workflows Guide
+
+## Common Workflows
+
+### 1. Repository Setup
+
+**Creating a new repository**:
+1. Log in to Gitea instance
+2. Click "New Repository" or "+" → "New Repository"
+3. Configure repository settings (name, description, visibility, README, .gitignore, license)
+4. Click "Create Repository"
+
+**Cloning a repository**:
+```bash
+git clone https://git.parkingmeter.info/owner/repo.git
+cd repo
+```
+
+### 2. Branch Management
+
+**Creating a branch**:
+```bash
+git checkout -b feature/new-feature
+git push -u origin feature/new-feature
+```
+
+**In Gitea UI**: Use branch dropdown to create new branch
+
+### 3. Pull Requests
+
+**Creating a Pull Request**:
+1. Push branch to Gitea
+2. Click "New Pull Request" button
+3. Select base branch (usually `main` or `master`)
+4. Fill in PR title and description
+5. Add reviewers, labels, milestones if needed
+6. Click "Create Pull Request"
+
+**PR Workflow** (same as GitHub):
+- Review code
+- Add comments
+- Request changes
+- Approve
+- Merge (merge, squash, or rebase)
+
+### 4. Issues
+
+**Creating an Issue**:
+1. Go to repository
+2. Click "Issues" tab
+3. Click "New Issue"
+4. Fill in title and description
+5. Add labels, assignees, milestones
+6. Click "Submit new issue"
+
+**Issue Features**:
+- Assign to team members
+- Link to milestones
+- Add labels
+- Set due dates
+- Track dependencies
+- Reference commits and PRs
+
+### 5. Gitea Actions (CI/CD)
+
+**Setting up workflows**:
+1. Create `.github/workflows/` directory
+2. Create workflow YAML file
+3. Push to repository
+4. Gitea Actions will execute workflows
+
+**Workflow triggers**:
+- `push` - On push to repository
+- `pull_request` - On PR events
+- `workflow_dispatch` - Manual trigger
+- `schedule` - Scheduled runs
+
+## Best Practices
+
+### 1. Branch Naming
+
+**Conventions**:
+- `feature/description` - New features
+- `fix/description` - Bug fixes
+- `docs/description` - Documentation
+- `refactor/description` - Code refactoring
+- `test/description` - Test improvements
+
+### 2. Commit Messages
+
+**Format**: `type(scope): description`
+
+**Types**:
+- `feat` - New feature
+- `fix` - Bug fix
+- `docs` - Documentation
+- `chore` - Maintenance
+- `ci` - CI/CD changes
+
+**Examples**:
+```
+feat(phase-01): Add Zapier integration
+fix(phase-02): Resolve web link capture
+docs(kb): add api-auth-decision and update index/changelog
+```
+
+### 3. Pull Request Process
+
+1. Create feature branch
+2. Make changes and commit
+3. Push branch to Gitea
+4. Create Pull Request
+5. Request review
+6. Address feedback
+7. Merge when approved
+
+### 4. Issue Management
+
+- Use labels for categorization
+- Link issues to milestones
+- Reference issues in commits: `Fixes #123`
+- Close issues via PR: `Closes #123`
+
+## For LLMs: Workflow Documentation
+
+### When Documenting Workflows
+
+**Use Gitea terminology**:
+```markdown
+## Development Workflow
+
+1. Create a feature branch: `git checkout -b feature/name`
+2. Make changes and commit
+3. Push to Gitea: `git push origin feature/name`
+4. Create Pull Request in Gitea
+5. Request review and address feedback
+6. Merge when approved
+```
+
+**Reference Gitea Actions**:
+```markdown
+## CI/CD Workflow
+
+This repository uses **Gitea Actions** for continuous integration.
+
+**Note**: Gitea Actions is compatible with GitHub Actions, so workflows 
+use the same YAML format and `.github/workflows/` directory structure.
+
+Workflows run automatically on:
+- Push to main branch
+- Pull requests
+- Manual trigger via `workflow_dispatch`
+```
+
+## Integration with Documentation System
+
+### Phase Documentation
+- Reference Gitea repository URLs
+- Use Gitea terminology in tasks.md
+- Link to Gitea issues in tasks
+- Reference Gitea Actions workflows
+
+### KB System
+- Reference Gitea features when relevant
+- Link to Gitea documentation
+- Use Gitea terminology consistently
+
+### Cursor Rules
+- Use "Gitea Actions" (not "GitHub Actions")
+- Reference Gitea repository
+- Note compatibility where relevant
+
+## Troubleshooting
+
+### Common Issues
+
+**Workflow not running**:
+- Check runner registration
+- Verify workflow syntax
+- Check trigger conditions
+- Review runner logs
+
+**PR not showing**:
+- Verify branch was pushed
+- Check branch visibility
+- Verify base branch is correct
+
+**Issues not linking**:
+- Use correct issue number format: `#123`
+- Verify issue exists
+- Check repository permissions
+
+## References
+
+- **Gitea Usage**: https://docs.gitea.com/usage/
+- **Gitea Actions**: https://docs.gitea.com/usage/actions/
+- **Pull Requests**: https://docs.gitea.com/usage/pull-request/
+- **Issues**: https://docs.gitea.com/usage/issues/
+
+---
+
+**Original Location**: `docs/GITEA/Gitea-Workflows.md`  
+**Last Updated**: 2025-01-27  
+**Related**: 
+- `docs/GITEA/Gitea-Basics.md`
+- `docs/GITEA/Gitea-Actions-Guide.md`
+