feat(phase-0): establish comprehensive documentation and automation system

Phase 0: Foundation & Cursor Rules Setup - Complete This commit establishes the foundation for a comprehensive documentation and project management system for Tendril, following best practices from the COMPLETE-SYSTEM-REPLICATION-GUIDE.md. ## What Was Created ### 1. Cursor Rules System (.cursorrules) - Comprehensive rules for AI agent behavior in Cursor IDE - Phase documentation synchronization rules (auto-update changelog, tasks, decisions) - KB (Knowledge Base) ingestion and routing rules - Gitea Actions workflow maintenance rules - README maintenance rules - File deletion protection rules - Customized for Tendril project with Gitea platform ### 2. Directory Structure - tendril/phases/ - Phase-based project management structure - kb/ - Knowledge Base system with 8 categories: * 01_projects/tendril/ - Project-specific notes * 02_systems/ - Infrastructure/tooling * 03_research/ - Informal research * 04_design/ - Product specs/UX * 05_decisions/ - Project-level ADRs * 06_glossary/ - Terms/acronyms * 07_playbooks/ - How-to guides * 08_archive/ - Superseded content * Special directories: _guides/, _templates/, _inbox/, _review_queue/, scripts/ - .github/workflows/ - Gitea Actions workflows (compatible with GitHub Actions) - docs/PROMPTS/ - LLM usage guides ### 3. Agent Guidelines (docs/AGENT-GUIDELINES.md) - Comprehensive guide for AI agents working on Tendril - Documents project structure, workflows, and conventions - Mandatory workflows and critical rules - Project-specific context (Rust/WASM, Zed extension) - Links to all documentation systems ### 4. Gitea Documentation (docs/GITEA/) Complete documentation suite for working with Gitea: - README.md - Overview and quick reference - Gitea-Basics.md - Core concepts, features, differences from GitHub - Gitea-Actions-Guide.md - CI/CD guide with compatibility notes - Gitea-Workflows.md - Common workflows and best practices - Gitea-API-Reference.md - API differences and usage - LLM-Gitea-Guidelines.md - LLM-specific guidelines and terminology ### 5. Phase Updates Documentation (docs/PHASE-UPDATES/) - COMPLETE-SYSTEM-REPLICATION-GUIDE.md - Complete replication guide - PHASE-0-GITEA-UPDATES.md - Documents Gitea-specific updates - README.md - Directory overview and navigation ## Why This Was Done 1. **Establish AI-Friendly Documentation System** - Enables consistent AI agent behavior across the project - Provides clear guidelines for documentation maintenance - Ensures automated synchronization of related documents 2. **Platform-Specific Adaptation (Gitea)** - Tendril uses self-hosted Gitea, not GitHub - Gitea Actions is compatible with GitHub Actions but needs proper documentation - Ensures all references use correct terminology (Gitea vs GitHub) 3. **Foundation for Phase-Based Management** - Sets up structure for phase documentation system - Prepares for KB system implementation - Establishes automation workflows foundation 4. **Knowledge Management** - KB system structure ready for capturing project knowledge - Templates and guides prepared for future use - Index generation system prepared ## How It Benefits the Project ### 1. Automated Documentation Synchronization - When phase blueprints are modified, related documents (changelog, tasks, decisions) are automatically checked and updated - Reduces manual synchronization errors - Ensures consistency across all phase documents ### 2. AI Agent Consistency - Cursor rules ensure all AI interactions follow the same patterns - Clear guidelines prevent inconsistent documentation - Automated checks ensure nothing is missed ### 3. Gitea Platform Understanding - Comprehensive Gitea documentation helps LLMs understand the platform - Correct terminology prevents confusion (Gitea vs GitHub) - Workflow compatibility clearly documented ### 4. Scalable Structure - Phase-based system supports long-term project management - KB system ready for knowledge capture and organization - Automation workflows prepared for CI/CD ### 5. Developer Experience - Clear documentation structure makes onboarding easier - Automated workflows reduce manual maintenance - Consistent patterns across all documentation ### 6. Future-Proof Foundation - Structure supports future phases (1-6) - KB system ready for knowledge capture - Automation system ready for workflow implementation ## Technical Details ### Gitea Actions Compatibility - Gitea Actions uses same YAML format as GitHub Actions - Same .github/workflows/ directory structure - Workflows are largely interchangeable - Documentation notes compatibility throughout ### File Organization - All documentation organized in docs/ directory - Phase updates tracked in docs/PHASE-UPDATES/ - Gitea-specific docs in docs/GITEA/ - Agent guidelines in docs/AGENT-GUIDELINES.md ### Cursor Rules Customization - Project name: Tendril - Phase directory: tendril/phases/ - KB project: tendril - Platform: Gitea (self-hosted) ## Next Steps Phase 0 is complete. Ready for: - Phase 1: Phase Documentation System setup - Phase 2: KB System implementation - Phase 3: Gitea Actions workflows - Phase 4: LLM Usage Guides - Phase 5: Documentation migration - Phase 6: Validation and testing ## Files Added - .cursorrules (root) - docs/AGENT-GUIDELINES.md - docs/GITEA/ (6 files) - docs/PHASE-UPDATES/ (3 files) - Directory structures for phases, KB, workflows, and prompts All files validated with no linter errors.
2025-11-11 11:09:36 -07:00
parent 7e49d8c8d4
commit 0a131a296e
11 changed files with 4399 additions and 0 deletions
--- a/.cursorrules
+++ b/.cursorrules
@@ -0,0 +1,278 @@
+# Cursor Rules for Tendril
+
+## Phase Documentation Synchronization Rules
+
+### MANDATORY: When blueprint.md is modified, automatically update related phase documents
+
+When ANY file matching `tendril/phases/phase-*/blueprint.md` is edited or updated:
+
+1. **ALWAYS check and update `changelog.md`** in the same phase directory:
+   - Add a new entry with today's date (YYYY-MM-DD format)
+   - Describe what changed in the blueprint
+   - Use format: `- **YYYY-MM-DD:** [Description of change]`
+
+2. **ALWAYS check and update `tasks.md`** in the same phase directory:
+   - Sync task checkboxes with "Definition of Done" items from blueprint
+   - Sync task list with "Phase Deliverables" section from blueprint
+   - Ensure task status aligns with milestone statuses in blueprint
+   - Update phase status if blueprint status changed
+
+3. **ALWAYS check `decisions.md`** in the same phase directory:
+   - If blueprint changes reflect new architectural decisions, add ADR entry
+   - If decisions are mentioned in blueprint but not in decisions.md, add them
+   - Review that existing ADRs still align with blueprint specifications
+
+4. **ALWAYS verify consistency**:
+   - Project name matches across all phase documents
+   - Dates are consistent (or marked as TBD consistently)
+   - Team roles match where applicable
+   - Status indicators are aligned
+
+#### When Gitea Actions workflows (`.github/workflows/*.yml`) are modified:
+
+1. **ALWAYS update `.github/CHANGELOG.md`**:
+   - Document workflow changes, new triggers, or automation updates
+   - Note any changes to scheduled times or conditions
+   - Include affected workflow name and file path
+
+2. **ALWAYS update `.github/decisions.md`** (if decision-related):
+   - Document the decision behind the workflow change
+   - Explain rationale and alternatives considered
+   - Note impact on automation
+
+3. **ALWAYS update `.github/README.md`** (if structure or behavior changed):
+   - Update workflow descriptions if behavior changed significantly
+   - Add new workflows to overview section
+   - Remove references to deleted workflows
+
+4. **ALWAYS verify workflow references**:
+   - Check that documentation references to workflows use correct file names
+   - Ensure workflow descriptions in docs match actual workflow logic
+
+#### When `.github/` folder is modified (any file):
+
+1. **ALWAYS update `.github/CHANGELOG.md`**:
+   - Document all changes to .github folder structure
+   - Include file paths and what changed
+   - Note if workflows, documentation, or structure was modified
+
+2. **ALWAYS update `.github/decisions.md`** (if decision-related):
+   - Document decisions about .github folder structure
+   - Explain rationale for documentation organization
+   - Note impact on workflow maintenance
+
+3. **ALWAYS update `.github/README.md`** (if structure or purpose changed):
+   - Update overview if folder structure changed
+   - Update workflow descriptions if documentation changed
+   - Ensure all workflows are listed in overview
+
+### Specific Blueprint Change Triggers
+
+When blueprint.md changes include:
+- **Project name change** → Update all phase documents to reflect new name
+- **Milestone status changes** → Update tasks.md and changelog.md
+- **Deliverables completion** → Update tasks.md checkboxes and changelog.md
+- **Team role assignments** → Update changelog.md if significant
+- **Timeline changes** → Update changelog.md with reason
+- **Scope changes** → Update decisions.md if architectural decision involved
+- **Status changes** → Update tasks.md status line
+
+### Workflow for Blueprint Updates
+
+1. After editing blueprint.md, immediately:
+   - Read changelog.md, tasks.md, and decisions.md from the same phase directory
+   - Compare blueprint content with related documents
+   - Identify discrepancies or missing updates
+   - Update all related documents to maintain consistency
+   - Verify no information is lost (only added or synchronized)
+
+2. Before completing any blueprint edit session:
+   - Confirm all related documents have been checked
+   - Confirm all necessary updates have been made
+   - **ALWAYS provide a summary** of what was updated:
+     * List each file that was modified
+     * Describe what changes were made to each file
+     * Note any files that were checked but didn't need updates
+   - **ALWAYS ask the user** if they want to push these changes to the remote repository
+
+### Never Skip These Steps
+
+- ❌ **NEVER delete files or folders when committing or pushing to the repository**
+- ❌ NEVER edit blueprint.md without checking related documents
+- ❌ NEVER leave related documents out of sync
+- ❌ NEVER assume related documents are already updated
+- ✅ ALWAYS read related documents before making changes
+- ✅ ALWAYS update related documents in the same session
+- ✅ ALWAYS verify consistency across all phase documents
+
+## General Project Rules
+
+- Always read phase blueprints before making changes
+- **CRITICAL: NEVER delete files or folders when committing or pushing**
+  - **UNDER NO CIRCUMSTANCES** are you to delete files or folders whenever the user requests for you to commit from the local repo or push to the remote repo
+  - Commits and pushes should only include file modifications, additions, and updates
+  - If file deletion is needed, it must be explicitly requested by the user in a separate, clear request
+  - Never perform cleanup, organization, or deletion operations as part of commit/push workflows
+- Update documentation incrementally, not at the end
+- Follow the structure defined in `docs/AGENT-GUIDELINES.md`
+- Use conventional commit messages with phase references
+
+## KB Ingestion & Routing Rules
+
+### MANDATORY: KB Ingestion System Behavior
+
+When the chat starts with the text "SYSTEM — KB Ingestion & Routing" (from `/kb/_guides/KB_INGEST_PROMPT.md`), treat it as a system message and follow KB ingestion protocols.
+
+### KB Write Scope & Constraints
+
+**Assistant Rules:**
+- Only create or update files under `/kb` except when explicitly asked otherwise
+- Never modify files in `/kb/_guides` or `/kb/_templates`
+- Enforce the filename pattern: `^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)\.md$`
+- Before writing KB files, ensure YAML frontmatter contains all required keys: `title`, `date`, `captured_at`, `author`, `source`, `source_type`, `project`, `related_projects`, `topics`, `tags`, `type`, `status`, `phase_relevance`, `routing_hint`, `proposed_path`, `routing_confidence`, `related`, `summary`
+- Include project-specific fields: `captured_at` (same as date), `source_type` (voice|web|pdf|image|personal_note|chat|pulse), `related_projects` (same as project), `phase_relevance[]` (array of phase-XX or empty)
+- Optional fields: `key_takeaways[]`, `action_candidates[]`
+- If the user pastes multiple unrelated chunks, split into separate files (max 5) and suffix with `--p1`, `--p2`, etc.
+- If routing is ambiguous, write to `/kb/_inbox` and include `routing_hint` explaining uncertainty
+- Respond with a single JSON code block as specified by the KB ingestion system prompt
+- Default `author` is `["unknown author"]` if not specified
+- Default `project` is `["tendril"]` for Tendril project
+
+**User Guidelines:**
+- Provide raw content after the system prompt
+- Avoid mixing unrelated topics when possible
+- Paste `/kb/_guides/KB_INGEST_PROMPT.md` contents as the first message in a Cursor chat before pasting any material
+
+### KB System vs Research System
+
+**When to use KB system (`/kb/`):**
+- Pulse Daily chats and ideas
+- Informal notes and thoughts about the project
+- External information that may inform the project
+- Project-level decisions (complements phase-specific ADRs)
+- How-to guides and playbooks
+- Glossary entries
+- Design ideas and UX concepts
+
+**When to use Research system (`tendril/research/notes/` or equivalent):**
+- Formal research articles, papers, and web content
+- Content that will be actively researched and indexed
+- Research materials that go through ingestion pipeline
+- Content requiring full research metadata schema
+
+**Integration:**
+- KB entries can reference project phases via `phase_relevance[]` field
+- KB decisions complement (not replace) phase-specific ADRs
+- KB entries use aligned metadata schema for compatibility
+
+### KB Workflow Maintenance
+
+**When KB structure or guidelines change:**
+- Check and update Gitea Actions workflows (`.github/workflows/kb-lint.yml`) if KB validation rules change
+- Check and update README.md if KB system is added or significantly modified
+- Ensure workflows stay in sync with KB guidelines in `/kb/_guides/`
+
+### KB Index Check Requirements
+
+**MANDATORY: Pre-Planning KB Check**
+
+Before starting any planning or development work, ALWAYS:
+
+1. **Read `kb/README.md`** to understand the KB system (if first time working with KB)
+2. **Read `kb/_index.md`** to check for relevant KB content
+3. **Search `kb/_index.md`** for keywords related to current task:
+   - Check topics index for relevant topics
+   - Check tags index for relevant tags
+   - Search file titles and summaries
+   - Check relevant categories (e.g., decisions, specs, research)
+   - Check phase relevance index for content related to current phase
+4. **If relevant KB content found:**
+   - List specific KB files that might be relevant (with paths from index)
+   - Summarize relevant entries from index (title, summary, topics, tags, phase relevance)
+   - Ask user if they want to incorporate KB knowledge into current work
+   - If user confirms, read the actual KB files referenced in index
+   - Reference KB files in documentation or code comments when appropriate
+
+**KB Index and Changelog Update Requirement**
+
+**MANDATORY:** After creating, modifying, or deleting ANY file in `kb/` (except `_guides/`, `_templates/`, `README.md`, `_index.md`, and `CHANGELOG.md`):
+
+1. **Run index generation script:**
+   ```bash
+   kb/scripts/generate-index.sh
+   ```
+   - This regenerates `kb/_index.md` with current KB content
+   - Verify the script completes successfully
+   - Check that changes appear in `kb/_index.md`
+
+2. **Update KB changelog:**
+   - Add entry to `kb/CHANGELOG.md` with date-based format:
+     ```markdown
+     ## [YYYY-MM-DD] KB File Added/Modified/Deleted
+     
+     ### Added/Changed/Removed
+     - `kb/XX_category/filename.md` - [Brief description]
+     ```
+   - Use today's date (YYYY-MM-DD format)
+   - Include the full file path relative to repository root
+   - Provide a brief description (1-2 sentences) of what changed
+
+3. **Commit all changes together:**
+   - Commit KB file change, index update, and changelog entry together
+   - Use commit message: `docs(kb): [action] [filename-slug] and update index/changelog`
+   - Examples:
+     - `docs(kb): add api-auth-decision and update index/changelog`
+     - `docs(kb): update cursor-workflow and update index/changelog`
+     - `docs(kb): remove obsolete-note and update index/changelog`
+
+4. **Note:** Gitea Actions will auto-update index on push to main, but local updates should also regenerate index. Changelog updates are always manual and must be done locally.
+
+**NEVER skip these steps** - Both index and changelog updates are mandatory for KB system integrity.
+
+## README Maintenance Rules
+
+### MANDATORY: Check and Update README After Work Completion
+
+**After completing ANY work session that involves:**
+- Phase blueprint updates
+- Phase status changes
+- New deliverables or features
+- Directory structure changes
+- Project name or description changes
+- Major architectural decisions
+
+**You MUST:**
+
+1. **Read the current README.md** to understand its current state
+
+2. **Check if updates are needed** by verifying:
+   - Phase statuses are accurate (✅ Complete, 🔄 In Progress, ⏳ Planned)
+   - Phase names match current blueprints
+   - Directory structure reflects actual project layout
+   - Links to phase blueprints are correct
+   - Project description matches current state
+   - Getting Started section is accurate
+
+3. **Update README.md if any of the following changed:**
+   - Phase status (e.g., Phase 1 moved from Planned to In Progress)
+   - Phase names or descriptions
+   - Project structure (new directories, renamed files)
+   - Project name or branding
+   - Key features or capabilities
+   - Documentation links or paths
+
+4. **Before completing work session:**
+   - Confirm README.md has been checked
+   - Update README.md if needed
+   - Verify all links in README.md are valid
+   - Ensure README.md accurately reflects current project state
+
+### Never Skip README Updates
+
+- ❌ NEVER complete work without checking README.md
+- ❌ NEVER leave README.md out of sync with project state
+- ❌ NEVER assume README.md is already up to date
+- ✅ ALWAYS check README.md after making significant changes
+- ✅ ALWAYS update README.md when phase statuses change
+- ✅ ALWAYS verify README.md accuracy before committing
+
--- a/docs/AGENT-GUIDELINES.md
+++ b/docs/AGENT-GUIDELINES.md
@@ -0,0 +1,217 @@
+# Agent Guidelines for Tendril
+
+**Purpose**: This document provides guidelines for AI agents (like Cursor AI) working on the Tendril project. It defines the project structure, documentation standards, and workflow expectations.
+
+**Last Updated**: 2025-01-27
+
+---
+
+## Project Overview
+
+**Tendril** is a Zed IDE extension that integrates with Gitea through the Model Context Protocol (MCP). It provides seamless access to Gitea repositories, issues, pull requests, and more directly within the Zed editor.
+
+**Repository**: https://git.parkingmeter.info/Mycelium/tendril  
+**Current Version**: v0.1.0  
+**Language**: Rust (compiled to WASM for Zed extension)  
+**License**: Apache 2.0
+
+---
+
+## Documentation System Architecture
+
+Tendril uses a comprehensive documentation system with the following components:
+
+### Phase Documentation System
+
+**Location**: `tendril/phases/phase-XX-name/`
+
+Each phase has four synchronized documents:
+- **`blueprint.md`** - Complete phase specification
+- **`tasks.md`** - Task tracking (mirrors Gitea issues)
+- **`decisions.md`** - Architecture Decision Records (ADRs)
+- **`changelog.md`** - Change history
+
+**Critical Rule**: When `blueprint.md` is modified, ALL related documents must be checked and updated in the same session.
+
+### Knowledge Base (KB) System
+
+**Location**: `kb/`
+
+The KB system provides a lightweight, LLM-friendly staging area for external information:
+- `kb/01_projects/tendril/` - Project-specific notes
+- `kb/02_systems/` - Infrastructure/tooling
+- `kb/03_research/` - Informal research
+- `kb/04_design/` - Product specs/UX
+- `kb/05_decisions/` - Project-level ADRs
+- `kb/06_glossary/` - Terms/acronyms
+- `kb/07_playbooks/` - How-to guides
+- `kb/08_archive/` - Superseded content
+
+**KB File Naming**: `YYYY-MM-DD--slug--type.md`  
+**KB Frontmatter**: All KB files require complete YAML frontmatter with 18 required fields.
+
+### Gitea Automation
+
+**Location**: `.github/`
+
+- `.github/workflows/` - Gitea Actions workflows (compatible with GitHub Actions format)
+- `.github/README.md` - Automation overview
+- `.github/CHANGELOG.md` - Workflow change tracking
+- `.github/decisions.md` - Automation decisions
+
+**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure.
+
+---
+
+## Core Principles
+
+1. **Documentation is the Single Source of Truth** - Always read phase blueprints before making changes
+2. **Synchronization is Mandatory** - Related documents must stay in sync automatically
+3. **LLM-Friendly Structure** - All documentation is structured for AI agent consumption
+4. **Incremental Updates** - Update documentation as you work, not at the end
+5. **Validation at Every Step** - Automated validation ensures consistency
+
+---
+
+## Mandatory Workflows
+
+### When Editing Phase Blueprints
+
+1. **Read related documents first**:
+   - `changelog.md` - Check recent changes
+   - `tasks.md` - Understand current task status
+   - `decisions.md` - Review existing ADRs
+
+2. **After editing `blueprint.md`**:
+   - Update `changelog.md` with today's date and description
+   - Sync `tasks.md` with blueprint deliverables and definition of done
+   - Review `decisions.md` for new ADRs needed
+   - Verify project name consistency across all documents
+
+3. **Before completing**:
+   - Provide summary of all files modified
+   - Ask user if they want to push changes
+
+### When Creating KB Files
+
+1. **Before creating**:
+   - Check `kb/_index.md` for existing related content
+   - Determine appropriate category using routing decision tree
+   - Assess routing confidence (0.00-1.00)
+
+2. **After creating**:
+   - Run `kb/scripts/generate-index.sh` to update index
+   - Update `kb/CHANGELOG.md` with entry
+   - Commit all three changes together
+
+### When Modifying Gitea Actions Workflows
+
+1. **Update `.github/CHANGELOG.md`** - Document what changed
+2. **Update `.github/decisions.md`** - Document decision rationale (if applicable)
+3. **Update `.github/README.md`** - Update workflow descriptions (if needed)
+
+**Note**: Gitea Actions workflows use the same YAML format as GitHub Actions, so existing GitHub Actions workflows can be used with minimal or no modifications.
+
+### When Completing Work Sessions
+
+1. **Check README.md**:
+   - Verify phase statuses are accurate
+   - Update if phase statuses changed
+   - Verify links are correct
+
+2. **Verify consistency**:
+   - Project name matches across documents
+   - Dates are consistent
+   - Status indicators are aligned
+
+---
+
+## File Structure Conventions
+
+### Directory Naming
+- **Phase directories**: `phase-XX-name` where XX is zero-padded (00, 01, 02, etc.)
+- **KB categories**: `01_projects/`, `02_systems/`, etc. (numbered for ordering)
+- **Special KB directories**: `_guides/`, `_templates/`, `_inbox/`, `_review_queue/` (underscore prefix)
+
+### File Naming
+- **Phase documentation**: `blueprint.md`, `tasks.md`, `decisions.md`, `changelog.md`
+- **KB files**: `YYYY-MM-DD--slug--type.md`
+- **Workflows**: `kebab-case.yml`
+
+### Commit Messages
+
+**Format**: `type(scope): description`
+
+**Types**:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `chore`: Maintenance tasks
+- `ci`: CI/CD changes
+
+**Examples**:
+- `feat(phase-01): Add Zapier integration`
+- `fix(phase-02): Resolve web link capture (#123)`
+- `docs(kb): add api-auth-decision and update index/changelog`
+
+---
+
+## Critical Rules
+
+### NEVER Do These Things
+
+- ❌ **NEVER delete files or folders when committing or pushing**
+- ❌ NEVER edit blueprint.md without checking related documents
+- ❌ NEVER leave related documents out of sync
+- ❌ NEVER assume related documents are already updated
+- ❌ NEVER skip KB index/changelog updates
+- ❌ NEVER complete work without checking README.md
+
+### ALWAYS Do These Things
+
+- ✅ ALWAYS read related documents before making changes
+- ✅ ALWAYS update related documents in the same session
+- ✅ ALWAYS verify consistency across all phase documents
+- ✅ ALWAYS run KB index generation after KB file changes
+- ✅ ALWAYS check README.md after significant changes
+- ✅ ALWAYS provide summaries of what was updated
+
+---
+
+## Project-Specific Context
+
+### Technology Stack
+- **Language**: Rust
+- **Target**: WASM (WebAssembly) for Zed extension
+- **Dependencies**: zed_extension_api, serde, schemars
+- **Build**: `cargo build --target wasm32-unknown-unknown --release`
+
+### Key Files
+- `src/mcp_server_gitea.rs` - Main extension logic
+- `extension.toml` - Zed extension manifest
+- `Cargo.toml` - Rust project configuration
+- `configuration/default_settings.jsonc` - Configuration template
+
+### Current Status
+- **Version**: v0.1.0
+- **Status**: Feature-complete for core functionality
+- **Features**: Binary path resolution, Docker support, cross-platform detection
+- **Limitations**: SSE mode not supported (Zed API limitation)
+
+---
+
+## Getting Help
+
+If you're unsure about:
+- **Documentation structure**: See `docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
+- **KB system**: See `kb/README.md` and `kb/_guides/`
+- **Phase documentation**: See `tendril/phases/phase-00-foundation/` for examples
+- **Gitea automation**: See `.github/README.md` and `.github/LLM-Usage-Guide--tendril.md`
+- **Gitea platform**: See `docs/GITEA/` for comprehensive Gitea documentation
+
+---
+
+**Location**: `docs/AGENT-GUIDELINES.md`  
+**Maintained by**: Tendril Project Maintainers  
+**Based on**: `docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
+
--- a/docs/GITEA/Gitea-API-Reference.md
+++ b/docs/GITEA/Gitea-API-Reference.md
@@ -0,0 +1,243 @@
+# Gitea API Reference for LLMs
+
+**Purpose**: API differences and considerations when working with Gitea programmatically.
+
+**Reference**: [Gitea API Documentation](https://docs.gitea.com/api/)
+
+---
+
+## 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`
+
+---
+
+## 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
+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?;
+```
+
+### When Referencing Documentation
+
+**Link to Gitea API docs**:
+```markdown
+For complete API documentation, see:
+https://docs.gitea.com/api/
+```
+
+---
+
+## 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/
+
+---
+
+**Location**: `docs/GITEA/Gitea-API-Reference.md`  
+**Last Updated**: 2025-01-27
+
--- a/docs/GITEA/Gitea-Actions-Guide.md
+++ b/docs/GITEA/Gitea-Actions-Guide.md
@@ -0,0 +1,286 @@
+# Gitea Actions Guide for LLMs
+
+**Purpose**: Guide for LLMs working with Gitea Actions (CI/CD system compatible with GitHub Actions).
+
+**Reference**: [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/)
+
+---
+
+## 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**:
+```yaml
+name: Workflow Name
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run command
+        run: echo "Hello, Gitea Actions!"
+```
+
+### 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 Actions uses **Gitea Runners** (similar to GitHub Runners):
+- Self-hosted runners
+- Can run on various platforms
+- Register runners with Gitea instance
+- Similar to GitHub Actions runners
+
+---
+
+## Differences from GitHub Actions
+
+### 1. Actions Marketplace
+
+- **GitHub**: Centralized marketplace at github.com/marketplace
+- **Gitea**: Actions can be downloaded from any Git website
+- **Impact**: Actions plugins can come from GitHub, Gitea, or any Git repository
+
+### 2. Runner Registration
+
+- **GitHub**: Runners managed by GitHub (or self-hosted)
+- **Gitea**: All runners are self-hosted
+- **Impact**: Must register and manage your own runners
+
+### 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
+
+---
+
+## Creating Workflows
+
+### Basic Workflow Template
+
+```yaml
+name: Workflow Name
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  job-name:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Run command
+        run: |
+          echo "Running in Gitea Actions"
+          # Your commands here
+```
+
+### Using Actions from Different Sources
+
+**From GitHub**:
+```yaml
+- uses: actions/checkout@v4
+```
+
+**From Gitea**:
+```yaml
+- uses: gitea.com/owner/action@v1
+```
+
+**From Any Git Repository**:
+```yaml
+- uses: https://git.example.com/owner/action@v1
+```
+
+---
+
+## 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"
+
+### When Creating Workflow Files
+
+1. **Use `.github/workflows/` directory** (same as GitHub)
+2. **YAML format is identical** to GitHub Actions
+3. **Reference in documentation** as "Gitea Actions workflows"
+4. **Note compatibility** when relevant
+
+### Example Documentation
+
+```markdown
+## CI/CD Workflows
+
+This repository uses **Gitea Actions** for continuous integration and deployment.
+
+**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/workflows/` directory structure.
+
+### Workflows
+
+- **`kb-lint.yml`** - Validates KB file naming and frontmatter
+- **`kb-index-update.yml`** - Auto-updates KB index on push
+
+All workflows are located in `.github/workflows/` and use standard GitHub Actions YAML format.
+```
+
+---
+
+## 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
+```
+
+---
+
+## Troubleshooting
+
+### Workflow Not Running
+
+1. **Check runner registration**: Ensure runners are registered with Gitea instance
+2. **Check workflow syntax**: Validate YAML syntax
+3. **Check triggers**: Verify `on:` conditions match events
+4. **Check permissions**: Ensure workflow has necessary permissions
+
+### Actions Not Found
+
+1. **Check action source**: Verify action URL is correct
+2. **Check network access**: Ensure runner can access action repository
+3. **Use full URL**: For custom actions, use full Git URL
+
+### Runner Issues
+
+1. **Check runner status**: Verify runner is online and connected
+2. **Check runner labels**: Ensure `runs-on` matches runner labels
+3. **Check runner logs**: Review runner logs for errors
+
+---
+
+## 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/
+
+---
+
+**Location**: `docs/GITEA/Gitea-Actions-Guide.md`  
+**Last Updated**: 2025-01-27
+
--- a/docs/GITEA/Gitea-Basics.md
+++ b/docs/GITEA/Gitea-Basics.md
@@ -0,0 +1,213 @@
+# Gitea Basics for LLMs
+
+**Purpose**: Core concepts and features of Gitea that LLMs should understand when working with Gitea-based projects.
+
+**Reference**: [Gitea Official Documentation](https://docs.gitea.com/)
+
+---
+
+## What is Gitea?
+
+Gitea is a **painless, self-hosted, all-in-one software development service**. It includes:
+
+- 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: Cargo, npm, PyPI, Maven, etc.)
+- 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
+
+- Create and manage repositories
+- Browse commit history and code files
+- Review and merge code submissions
+- Manage collaborators
+- Handle branches, tags, cherry-picking, hooks
+- Integrated collaboration tools
+
+### 2. Code Review
+
+- **Pull Request workflow** (same as GitHub)
+- **AGit workflow** (Gitea-specific alternative)
+- Online code browsing
+- Review comments and feedback
+- Inline code modifications
+
+### 3. Issue Tracking
+
+- Track requirements, features, and bugs
+- Support for branches, tags, milestones
+- Assignments, time tracking, due dates
+- Dependencies between issues
+- Project columns and boards
+
+### 4. CI/CD (Gitea Actions)
+
+- **Compatible with GitHub Actions**
+- Write workflows in YAML format
+- Reuse existing Actions plugins
+- Actions plugins can be downloaded from any Git website
+- Same `.github/workflows/` directory structure
+
+### 5. Package Registry
+
+Supports 20+ package types:
+- Cargo, Chef, Composer, Conan, Conda
+- Container, Helm, Maven, npm, NuGet
+- Pub, PyPI, RubyGems, Vagrant
+- And more
+
+### 6. Security
+
+- User permission management
+- Access control lists (ACLs)
+- Security-focused design
+- Non-root system account recommended
+
+---
+
+## 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)
+
+---
+
+## Key Differences from GitHub
+
+### 1. Self-Hosted
+
+- Runs on your own infrastructure
+- Full control over data and access
+- No dependency on external services
+- Can be air-gapped if needed
+
+### 2. Lightweight
+
+- Designed to be fast and resource-efficient
+- Suitable for resource-limited environments
+- Lower system requirements than GitHub/GitLab
+
+### 3. Open Source
+
+- MIT licensed
+- Community-driven development
+- Transparent codebase
+- No vendor lock-in
+
+### 4. Actions Compatibility
+
+- Gitea Actions uses same format as GitHub Actions
+- Workflows are largely interchangeable
+- Some GitHub-specific features may not be available
+- Actions can be sourced from any Git repository
+
+### 5. API Differences
+
+- Gitea API is similar to GitHub's but not identical
+- Some endpoints may differ
+- Authentication methods are similar
+- Webhook formats are compatible
+
+---
+
+## Terminology
+
+### Same as GitHub
+
+- **Repository** / **Repo** - Code storage
+- **Branch** - Code versioning
+- **Pull Request** / **PR** - Code review request
+- **Issue** - Bug/feature tracking
+- **Commit** - Code change
+- **Tag** - Release marker
+- **Fork** - Copy of repository
+- **Clone** - Local copy
+
+### 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 repository 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
+
+### Managing Issues
+
+1. Create issue from repository
+2. Assign to team members
+3. Link to milestones, labels, projects
+4. Track dependencies and due dates
+
+---
+
+## For LLMs: Important Notes
+
+### When Documenting
+
+- 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/`
+
+### When Creating Workflows
+
+- Use `.github/workflows/` directory (same as GitHub)
+- YAML format is identical to GitHub Actions
+- Reference as "Gitea Actions workflows"
+- Note compatibility in documentation
+
+### When Working with API
+
+- Gitea API is similar but not identical to GitHub's
+- Check Gitea API documentation for specific endpoints
+- Authentication uses tokens (similar to GitHub)
+- Webhooks are compatible
+
+---
+
+## 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/
+
+---
+
+**Location**: `docs/GITEA/Gitea-Basics.md`  
+**Last Updated**: 2025-01-27
+
--- a/docs/GITEA/Gitea-Workflows.md
+++ b/docs/GITEA/Gitea-Workflows.md
@@ -0,0 +1,278 @@
+# Gitea Workflows for LLMs
+
+**Purpose**: Common workflows and best practices for working with Gitea repositories.
+
+**Reference**: [Gitea Usage Documentation](https://docs.gitea.com/usage/)
+
+---
+
+## 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 (public/private)
+   - Initialize with README (optional)
+   - Add .gitignore (optional)
+   - Choose license (optional)
+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**:
+1. Go to repository
+2. Click branch dropdown
+3. Type new branch name
+4. Click "Create Branch"
+
+### 3. Pull Requests
+
+**Creating a Pull Request**:
+1. Push branch to Gitea
+2. Click "New Pull Request" button (appears after push)
+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
+
+**Example workflow**:
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run tests
+        run: cargo test
+```
+
+---
+
+## 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`
+```
+
+### When Creating Workflow Files
+
+**Location and format**:
+- Use `.github/workflows/` directory
+- Use standard GitHub Actions YAML format
+- Reference as "Gitea Actions workflows" in documentation
+
+**Example**:
+```yaml
+# Gitea Actions workflow
+# Compatible with GitHub Actions format
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run tests
+        run: cargo test
+```
+
+---
+
+## Integration with Documentation System
+
+### Phase Documentation
+
+When working with phase documentation:
+- Reference Gitea repository URLs
+- Use Gitea terminology in tasks.md
+- Link to Gitea issues in tasks
+- Reference Gitea Actions workflows
+
+### KB System
+
+When creating KB entries:
+- Reference Gitea features when relevant
+- Link to Gitea documentation
+- Use Gitea terminology consistently
+
+### Cursor Rules
+
+When updating 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/
+
+---
+
+**Location**: `docs/GITEA/Gitea-Workflows.md`  
+**Last Updated**: 2025-01-27
+
--- a/docs/GITEA/LLM-Gitea-Guidelines.md
+++ b/docs/GITEA/LLM-Gitea-Guidelines.md
@@ -0,0 +1,220 @@
+# 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`
+
--- a/docs/GITEA/README.md
+++ b/docs/GITEA/README.md
@@ -0,0 +1,106 @@
+# Gitea Documentation for LLMs
+
+**Purpose**: This directory contains documentation to help AI assistants (LLMs) understand and work with Gitea, a self-hosted Git service.
+
+**Last Updated**: 2025-01-27
+
+---
+
+## Overview
+
+**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/)
+
+---
+
+## Contents
+
+- **[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
+
+---
+
+**Location**: `docs/GITEA/`  
+**Maintained by**: Tendril Project Maintainers
+
--- a/docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md
+++ b/docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md
--- a/docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md
+++ b/docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md
@@ -0,0 +1,62 @@
+# Phase 0 Gitea Updates Summary
+
+**Date**: 2025-01-27  
+**Purpose**: Document updates made to Phase 0 files to reflect Gitea (self-hosted) instead of GitHub
+
+## Changes Made
+
+### 1. `.cursorrules` File Updates
+
+**Updated References:**
+- "GitHub Actions workflows" → "Gitea Actions workflows" (3 occurrences)
+- "GitHub Actions will auto-update" → "Gitea Actions will auto-update"
+
+**Note**: Gitea Actions is compatible with GitHub Actions, so the `.github/workflows/` directory structure and YAML format remain the same.
+
+### 2. `docs/AGENT-GUIDELINES.md` Updates
+
+**Updated References:**
+- "GitHub issues" → "Gitea issues"
+- "GitHub Automation" → "Gitea Automation" (section title)
+- "GitHub Actions workflows" → "Gitea Actions workflows (compatible with GitHub Actions format)"
+- "When Modifying GitHub Workflows" → "When Modifying Gitea Actions Workflows"
+- Added note: "Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure."
+- Added note: "Gitea Actions workflows use the same YAML format as GitHub Actions, so existing GitHub Actions workflows can be used with minimal or no modifications."
+- "GitHub automation" → "Gitea automation" (in Getting Help section)
+
+## Key Points
+
+1. **Gitea Actions Compatibility**: Gitea Actions is compatible with GitHub Actions, meaning:
+   - Same `.github/workflows/` directory structure
+   - Same YAML workflow format
+   - Same triggers and syntax
+   - Existing GitHub Actions workflows can be used with minimal or no modifications
+
+2. **Repository Context**: 
+   - Primary repository: https://git.parkingmeter.info/Mycelium/tendril (Gitea)
+   - Self-hosted Gitea instance
+   - Uses Gitea Actions for CI/CD automation
+
+3. **No Structural Changes Needed**:
+   - Directory structure remains the same
+   - Workflow files will work as-is
+   - Only documentation references needed updating
+
+## Files Modified
+
+1. `.cursorrules` - Updated 3 references from GitHub to Gitea
+2. `docs/AGENT-GUIDELINES.md` - Updated 6 references and added compatibility notes
+
+## Next Steps
+
+When creating workflows in Phase 3:
+- Use standard GitHub Actions YAML format
+- Workflows will work with Gitea Actions automatically
+- Reference "Gitea Actions" in documentation, but note GitHub Actions compatibility
+- Test workflows in Gitea Actions interface (similar to GitHub Actions tab)
+
+---
+
+**Location**: `docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md`  
+**Related**: Phase 0 setup, Gitea Actions compatibility
+
--- a/docs/PHASE-UPDATES/README.md
+++ b/docs/PHASE-UPDATES/README.md
@@ -0,0 +1,59 @@
+# Phase Updates Documentation
+
+**Purpose**: This directory contains documentation related to phase updates, system replication guides, and migration notes.
+
+**Last Updated**: 2025-01-27
+
+---
+
+## Contents
+
+### System Replication
+
+- **[COMPLETE-SYSTEM-REPLICATION-GUIDE.md](./COMPLETE-SYSTEM-REPLICATION-GUIDE.md)** - Comprehensive guide for replicating the PAIRS documentation and automation system in another project. Includes all structures, schemas, templates, rationale, and step-by-step instructions.
+
+### Phase Updates
+
+- **[PHASE-0-GITEA-UPDATES.md](./PHASE-0-GITEA-UPDATES.md)** - Documents updates made to Phase 0 files to reflect Gitea (self-hosted) instead of GitHub. Includes changes to `.cursorrules` and `docs/AGENT-GUIDELINES.md`.
+
+---
+
+## Purpose
+
+This directory serves as a reference for:
+
+1. **System Replication**: Complete guide for setting up the documentation and automation system in new projects
+2. **Phase Updates**: Tracking changes and updates made during each phase of project setup
+3. **Migration Notes**: Documenting platform-specific adaptations (e.g., Gitea vs GitHub)
+
+---
+
+## Usage
+
+### For System Replication
+
+If you want to replicate this documentation system in another project:
+1. Read `COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
+2. Follow the step-by-step replication guide
+3. Customize for your project's needs
+
+### For Phase Updates
+
+When making updates during phase setup:
+1. Document changes in phase-specific update files
+2. Reference these files when reviewing phase work
+3. Use as historical record of decisions made
+
+---
+
+## Related Documentation
+
+- **Agent Guidelines**: `docs/AGENT-GUIDELINES.md` - Guidelines for AI agents
+- **Gitea Documentation**: `docs/GITEA/` - Gitea-specific documentation
+- **Phase Documentation**: `tendril/phases/` - Phase blueprints and related docs
+
+---
+
+**Location**: `docs/PHASE-UPDATES/`  
+**Maintained by**: Tendril Project Maintainers
+