docs(kb): implement Phase 2 KB System Setup

This commit implements the complete Knowledge Base (KB) system for the Tendril
project, establishing a structured, LLM-friendly system for capturing and
organizing external information that informs project development.

## What Was Implemented

### 1. KB System Documentation (kb/README.md)
   - Comprehensive documentation explaining the KB system's purpose and structure
   - Directory structure explanation with all 8 category directories
   - File naming schema: YYYY-MM-DD--slug--type.md with regex validation
   - Complete frontmatter schema documentation (18 required fields for Tendril)
   - Routing decision tree for categorizing content
   - Routing confidence system (0.00-1.00 scale) with policy for low-confidence items
   - Usage guidelines for creating and managing KB files
   - Integration notes with phase documentation system
   - Index generation and changelog update procedures

### 2. KB File Templates (kb/_templates/)
   Created three template files with complete frontmatter:

   - note.md: General notes template with draft status default
   - decision.md: ADR-style decision template with active status default
   - howto.md: How-to guide template with active status default

   All templates include:
   - All 18 required frontmatter fields (base + Tendril-specific)
   - Placeholder syntax (${VARIABLE}) for easy customization
   - Appropriate default values (routing_confidence, status, etc.)
   - Template-specific content sections
   - Customized for Tendril project (project: ["tendril"])

### 3. KB Ingestion Prompt (kb/_guides/KB_INGEST_PROMPT.md)
   Complete system prompt for LLM-assisted KB ingestion:

   - System instructions for content analysis and routing
   - Classification and routing rules for all 8 categories
   - Routing decision tree with 9-step decision process
   - Routing confidence assessment guidelines
   - File naming standards with examples and validation
   - Complete frontmatter requirements documentation
   - JSON output format specification
   - Quality and style guidelines
   - Safety constraints (NEVER/ALWAYS rules)
   - Validation checklist
   - Completion summary format with mandatory index/changelog updates

### 4. Index Generation Script (kb/scripts/generate-index.sh)
   Bash script for automatic KB index generation:

   - Scans all KB files in category directories (01_projects through 08_archive)
   - Excludes special directories (_guides, _templates, _inbox, _review_queue)
   - Extracts YAML frontmatter from each KB file
   - Parses metadata fields (title, date, type, summary, topics, tags, phases)
   - Generates kb/_index.md with:
     * File listing organized by category
     * Topics index (all unique topics with file references)
     * Tags index (all unique tags with file references)
     * Phase relevance index (files organized by phase)
     * Summary statistics
   - Compatible with Windows (Git Bash) and Unix systems
   - Uses temporary files for cross-platform compatibility
   - Handles errors gracefully (missing frontmatter, invalid files)
   - Script is executable (chmod +x)

### 5. KB Changelog (kb/CHANGELOG.md)
   Change tracking for KB system:

   - Initial entry documenting Phase 2 setup
   - Date-based format: ## [YYYY-MM-DD] KB System Setup
   - Lists all files created during setup
   - Notes about customization for Tendril project

### 6. Initial Index (kb/_index.md)
   Auto-generated searchable index:

   - Generated by running generate-index.sh
   - Currently empty (no KB files exist yet)
   - Ready to be populated as KB files are added
   - Includes proper structure for all index sections

## Why This Implementation

### Structured Knowledge Capture
   The KB system provides a lightweight staging area for external information
   (Pulse Daily chats, ideas, notes, research) that may inform Tendril project
   development. Unlike formal phase documentation, KB entries capture informal
   knowledge that complements the structured phase blueprints.

### LLM-Friendly Design
   The system is designed for LLM-assisted ingestion and management:
   - Clear routing decision tree enables automated classification
   - Confidence scoring allows human review of uncertain routing
   - Complete frontmatter ensures rich metadata for searchability
   - JSON output format enables automated file creation

### Searchability and Discovery
   The automatic index generation creates multiple access paths:
   - By category (for browsing related content)
   - By topic (for finding content on specific subjects)
   - By tag (for cross-cutting categorization)
   - By phase relevance (for finding content related to specific phases)

### Integration with Phase Documentation
   KB decisions complement phase-specific ADRs, KB research informs phase
   planning, and KB playbooks provide operational guides. The phase_relevance
   field creates explicit links between KB content and project phases.

### Project Customization
   All files are customized for Tendril:
   - Project name: "tendril" (replaced "pairs" references)
   - Default project field: ["tendril"]
   - Path references updated for Tendril structure
   - Gitea Actions noted (not GitHub Actions) for Phase 3

## Technical Details

### Frontmatter Schema (18 Fields)
   Base fields (14): title, date, author, source, project, topics, tags, type,
   status, routing_hint, proposed_path, routing_confidence, related, summary

   Tendril-specific (4): captured_at, source_type, related_projects,
   phase_relevance

   Optional (2): key_takeaways, action_candidates

### File Naming Pattern
   Regex: ^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$

   Components: Date (YYYY-MM-DD) + Slug (3-8 words, no stop-words) + Type

### Routing Confidence Policy
   - >= 0.60: File goes to proposed_path
   - < 0.60: File goes to _review_queue/ (with proposed_path in frontmatter)

## Next Steps

Phase 2 complete. Ready for Phase 3: Gitea Actions Workflows configuration.

## Files Added

- kb/README.md (290 lines)
- kb/_templates/note.md
- kb/_templates/decision.md
- kb/_templates/howto.md
- kb/_guides/KB_INGEST_PROMPT.md (~400 lines)
- kb/scripts/generate-index.sh (executable)
- kb/CHANGELOG.md
- kb/_index.md (auto-generated)

.cursorrules

@@ -0,0 +1,309 @@
+# 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:
+
+**Reference**: See `docs/GITEA/Gitea-Actions-Guide.md` for Gitea Actions workflow guidance and compatibility notes.
+
+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
+   - Consult `docs/GITEA/Gitea-Actions-Guide.md` for workflow best practices
+
+#### 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
+- Consult `docs/GITEA/` documentation for Gitea-specific guidance and platform questions
+
+## Gitea Platform Context
+
+**Repository**: https://git.parkingmeter.info/Mycelium/tendril  
+**Platform**: Gitea (self-hosted)  
+**Actions System**: Gitea Actions (compatible with GitHub Actions format)
+
+### Gitea Documentation References
+
+When working with Gitea-specific features, workflows, or platform questions:
+
+1. **Consult Gitea Documentation**: See `docs/GITEA/` for comprehensive Gitea guidance
+2. **LLM Guidelines**: See `docs/GITEA/LLM-Gitea-Guidelines.md` for LLM-specific guidelines
+3. **Actions Guide**: See `docs/GITEA/Gitea-Actions-Guide.md` when working with workflows
+4. **API Reference**: See `docs/GITEA/Gitea-API-Reference.md` for API differences
+5. **Workflows Guide**: See `docs/GITEA/Gitea-Workflows.md` for common workflows and best practices
+6. **Basics Guide**: See `docs/GITEA/Gitea-Basics.md` for core concepts and features
+
+### Platform Terminology
+
+- Use **"Gitea"** (not "GitHub") when referring to the platform
+- Use **"Gitea Actions"** (not "GitHub Actions") but note compatibility when relevant
+- Use **"Gitea issues"** (not "GitHub issues")
+- Use **"Gitea repository"** (not "GitHub repository")
+- Use **"Gitea Runners"** (not "GitHub Runners")
+- **Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure
+
+## 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
+  - Consult `docs/GITEA/Gitea-Actions-Guide.md` for workflow guidance
+- 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
+

CONTRIBUTING.md

@@ -0,0 +1,613 @@
+# Contributing to Tendril
+
+Thank you for your interest in contributing to Tendril! This guide will help you understand the development workflow, documentation standards, and how to submit changes.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Branch Management](#branch-management)
+- [Documentation Guidelines](#documentation-guidelines)
+- [Code Standards](#code-standards)
+- [Submitting Changes](#submitting-changes)
+- [Documentation Types](#documentation-types)
+
+## Getting Started
+
+### Prerequisites
+
+Before you begin, ensure you have:
+
+1. **Rust installed** (via rustup - required for dev extensions)
+   ```bash
+   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+   ```
+
+2. **Zed IDE** installed from https://zed.dev
+
+3. **Git** configured with your credentials
+
+4. **Access to the repository** (fork or direct access)
+
+### Development Environment Setup
+
+**Windows Users with Cursor IDE:**
+
+If you're setting up a Windows development environment with Cursor IDE, see [CURSOR_WINDOWS_SETUP.md](kb/_guides/CURSOR_WINDOWS_SETUP.md) for detailed step-by-step instructions on:
+- Installing and configuring the Gitea MCP Server
+- Setting up Cursor IDE to work with Gitea
+- Configuring authentication tokens
+- Testing the connection
+
+### Repository Setup
+
+1. **Fork the repository** (if you don't have direct write access):
+   - Go to https://git.parkingmeter.info/Mycelium/tendril
+   - Click "Fork" to create your own copy
+
+2. **Clone your fork** (or the main repo if you have access):
+   ```bash
+   git clone https://git.parkingmeter.info/Mycelium/tendril.git
+   cd tendril
+   ```
+
+3. **Add upstream remote** (if you forked):
+   ```bash
+   git remote add upstream https://git.parkingmeter.info/Mycelium/tendril.git
+   ```
+
+4. **Verify setup**:
+   ```bash
+   git remote -v
+   # Should show origin (your fork) and upstream (main repo)
+   ```
+
+## Development Workflow
+
+### 1. Checkout a New Branch
+
+Always create a new branch for your work. Never commit directly to `main`.
+
+**Branch Naming Conventions:**
+
+- `feature/description` - New features (e.g., `feature/http-streaming`)
+- `docs/description` - Documentation updates (e.g., `docs/contributing-guide`)
+- `fix/description` - Bug fixes (e.g., `fix/docker-path-resolution`)
+- `refactor/description` - Code refactoring (e.g., `refactor/error-handling`)
+- `test/description` - Test improvements (e.g., `test/windows-compatibility`)
+
+**Example:**
+```bash
+# Update your local main branch first
+git checkout main
+git pull upstream main  # or: git pull origin main
+
+# Create and checkout a new branch
+git checkout -b feature/your-feature-name
+
+# Or for documentation:
+git checkout -b docs/your-doc-update
+```
+
+### 2. Make Your Changes
+
+Work on your feature, fix, or documentation update.
+
+**For Code Changes:**
+- Edit `src/mcp_server_gitea.rs` for extension logic
+- Edit `extension.toml` for extension metadata
+- Edit `Cargo.toml` for dependencies
+
+**For Documentation:**
+- See [Documentation Guidelines](#documentation-guidelines) below
+
+### 3. Test Your Changes
+
+**For Code Changes:**
+```bash
+# Check for compilation errors
+cargo check
+
+# Run linter
+cargo clippy
+
+# Build release version
+cargo build --release
+
+# Test in Zed:
+# 1. Open Zed
+# 2. Extensions → Install Dev Extension
+# 3. Select the tendril directory
+# 4. Test your changes in Assistant panel
+```
+
+**For Documentation:**
+- Review markdown formatting
+- Check all links work
+- Verify code examples are correct
+- Ensure consistency with existing docs
+
+### 4. Commit Your Changes
+
+Use clear, descriptive commit messages:
+
+```bash
+# Good commit messages:
+git commit -m "Add feature: HTTP streaming transport support"
+git commit -m "Fix: Docker binary path resolution on Windows"
+git commit -m "Docs: Add contributing guide and workflow documentation"
+
+# Bad commit messages:
+git commit -m "fix stuff"
+git commit -m "updates"
+git commit -m "WIP"
+```
+
+**Commit Message Format:**
+```
+Type: Brief description (50 chars or less)
+
+Optional longer explanation if needed. Can wrap to 72 characters.
+Explain what and why, not how.
+
+- Bullet points for multiple changes
+- Reference issues: Fixes #123
+```
+
+**Types:**
+- `Add` - New feature
+- `Fix` - Bug fix
+- `Docs` - Documentation only
+- `Refactor` - Code refactoring
+- `Test` - Test additions/changes
+- `Chore` - Maintenance tasks
+
+### 5. Push Your Branch
+
+```bash
+# Push to your fork
+git push origin feature/your-feature-name
+
+# If branch doesn't exist remotely yet:
+git push -u origin feature/your-feature-name
+```
+
+### 6. Create a Pull Request
+
+1. Go to https://git.parkingmeter.info/Mycelium/tendril
+2. Click "New Pull Request" or "Create Pull Request"
+3. Select your branch
+4. Fill out the PR template:
+
+**PR Title:** Same as your commit message
+
+**PR Description:**
+```markdown
+## Description
+Brief description of what this PR does.
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Refactoring
+- [ ] Other (please describe)
+
+## Changes Made
+- Change 1
+- Change 2
+- Change 3
+
+## Testing
+- [ ] Code compiles: `cargo check`
+- [ ] No clippy warnings: `cargo clippy`
+- [ ] Tested in Zed IDE
+- [ ] Documentation reviewed
+
+## Related Issues
+Closes #123
+Fixes #456
+
+## Screenshots (if applicable)
+[Add screenshots for UI changes]
+
+## Checklist
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] Comments added for complex logic
+- [ ] Documentation updated
+- [ ] No new warnings generated
+- [ ] Tests pass (if applicable)
+```
+
+## Branch Management
+
+### Keeping Your Branch Up to Date
+
+If the main branch has moved forward while you're working:
+
+```bash
+# Switch to main
+git checkout main
+
+# Pull latest changes
+git pull upstream main  # or: git pull origin main
+
+# Switch back to your branch
+git checkout feature/your-feature-name
+
+# Rebase your changes on top of main
+git rebase main
+
+# If conflicts occur, resolve them, then:
+git add .
+git rebase --continue
+
+# Force push (only after rebase)
+git push --force-with-lease origin feature/your-feature-name
+```
+
+**Note:** Only use `--force-with-lease` on your own feature branches. Never force push to `main`.
+
+### Switching Between Branches
+
+```bash
+# List all branches
+git branch -a
+
+# Switch to a branch
+git checkout branch-name
+
+# Create and switch in one command
+git checkout -b new-branch-name
+
+# See what branch you're on
+git branch
+```
+
+## Documentation Guidelines
+
+### Documentation Structure
+
+Tendril has several types of documentation files:
+
+1. **README.md** - Main user-facing documentation
+   - Installation instructions
+   - Configuration examples
+   - Troubleshooting
+   - User-focused content
+
+2. **DEVELOPMENT.md** - Developer guide
+   - Architecture details
+   - Code structure
+   - Development setup
+   - Roadmap
+
+3. **PROJECT_STATUS.md** - Project status and roadmap
+   - Current version status
+   - Completed features
+   - Known issues
+   - Testing status
+
+4. **QUICKSTART.md** - Quick setup guide
+   - TL;DR version
+   - Minimal steps to get started
+
+5. **CONTRIBUTING.md** - This file
+   - Contribution guidelines
+   - Development workflow
+
+6. **Configuration Documentation:**
+   - `configuration/default_settings.jsonc` - Settings template with comments
+   - `configuration/installation_instructions.md` - UI-visible setup guide
+
+7. **Analysis/Research Docs:**
+   - `SSE_MODE_ANALYSIS.md` - Technical decisions
+   - `TESTING_FINDINGS.md` - Test results and learnings
+
+### When to Update Documentation
+
+**Update README.md when:**
+- Adding new configuration options
+- Changing installation steps
+- Adding new features users interact with
+- Fixing common issues
+
+**Update DEVELOPMENT.md when:**
+- Changing code architecture
+- Adding new code patterns
+- Updating development setup
+- Changing build process
+
+**Update PROJECT_STATUS.md when:**
+- Releasing new versions
+- Completing major features
+- Changing project status
+- Updating roadmap
+
+**Create new documentation when:**
+- Making significant technical decisions
+- Documenting test results
+- Explaining complex features
+- Providing detailed guides
+
+### Documentation Standards
+
+1. **Markdown Formatting:**
+   - Use proper heading hierarchy (## for sections, ### for subsections)
+   - Use code blocks with language tags: ` ```bash `, ` ```rust `, ` ```json `
+   - Use tables for structured data
+   - Use lists for step-by-step instructions
+
+2. **Code Examples:**
+   - Always test code examples before committing
+   - Include expected output when relevant
+   - Use realistic examples, not placeholders
+   - Show both success and error cases when helpful
+
+3. **Links:**
+   - Use relative links for internal documentation: `[README](README.md)`
+   - Use absolute links for external resources
+   - Verify all links work before committing
+
+4. **Consistency:**
+   - Follow existing documentation style
+   - Use consistent terminology (e.g., "gitea-mcp" not "gitea mcp")
+   - Match formatting patterns in similar documents
+
+### Creating New Documentation
+
+**For a new feature guide:**
+```bash
+# Create new doc file
+git checkout -b docs/feature-name-guide
+touch FEATURE_NAME.md
+
+# Write documentation following existing patterns
+# Reference it from README.md or appropriate location
+```
+
+**For technical analysis:**
+```bash
+# Create analysis document
+git checkout -b docs/technical-decision-name
+touch TECHNICAL_DECISION.md
+
+# Document:
+# - Problem statement
+# - Options considered
+# - Decision made
+# - Rationale
+# - Implementation details
+```
+
+**Example Documentation Template:**
+```markdown
+# Feature Name / Analysis Title
+
+**Date**: YYYY-MM-DD  
+**Status**: Draft / In Progress / Complete  
+**Related**: Issue #123, PR #456
+
+## Overview
+
+Brief description of what this document covers.
+
+## Details
+
+### Section 1
+Content here.
+
+### Section 2
+More content.
+
+## References
+
+- [Link 1](https://example.com)
+- [Link 2](https://example.com)
+
+## Conclusion
+
+Summary of key points.
+```
+
+## Code Standards
+
+### Rust Code Quality
+
+Before submitting code:
+
+```bash
+# Format code
+cargo fmt
+
+# Check for issues
+cargo check
+
+# Run linter
+cargo clippy
+
+# Build release
+cargo build --release
+```
+
+**Code Style:**
+- Follow Rust naming conventions
+- Keep functions focused (< 50 lines preferred)
+- Add comments for complex logic
+- Use meaningful variable names
+- Handle errors explicitly
+
+### Error Messages
+
+- Be specific about what went wrong
+- Provide actionable solutions
+- Include file paths or commands when relevant
+- Format multi-line errors clearly
+
+### Testing Checklist
+
+Before submitting:
+- [ ] Code compiles: `cargo check`
+- [ ] No clippy warnings: `cargo clippy`
+- [ ] Builds successfully: `cargo build --release`
+- [ ] Tested manually in Zed IDE
+- [ ] Documentation updated if needed
+- [ ] No breaking changes (or documented if intentional)
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Ensure your branch is up to date** (see Branch Management above)
+
+2. **Push your branch:**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+3. **Create Pull Request:**
+   - Go to repository on Gitea
+   - Click "New Pull Request"
+   - Select your branch
+   - Fill out PR description (see template above)
+
+4. **Respond to feedback:**
+   - Address review comments
+   - Make requested changes
+   - Push updates to your branch (PR updates automatically)
+   - Mark conversations as resolved when done
+
+5. **After approval:**
+   - Maintainer will merge your PR
+   - Your branch can be deleted after merge
+
+### PR Review Criteria
+
+Your PR will be reviewed for:
+
+- **Functionality**: Does it work as intended?
+- **Code Quality**: Follows Rust best practices?
+- **Documentation**: Is it documented appropriately?
+- **Testing**: Has it been tested?
+- **Breaking Changes**: Are any breaking changes documented?
+- **Consistency**: Matches existing code style?
+
+### After Your PR is Merged
+
+1. **Update your local main:**
+   ```bash
+   git checkout main
+   git pull upstream main
+   ```
+
+2. **Delete your feature branch** (optional):
+   ```bash
+   git branch -d feature/your-feature-name
+   git push origin --delete feature/your-feature-name
+   ```
+
+## Documentation Types
+
+### User-Facing Documentation
+
+**README.md** - Main entry point
+- Installation instructions
+- Configuration examples
+- Troubleshooting
+- Quick start guide
+
+**QUICKSTART.md** - Fast setup
+- Minimal steps
+- TL;DR version
+- Quick reference
+
+**configuration/installation_instructions.md** - UI guide
+- Shown in Zed extension UI
+- Concise setup steps
+- Links to full docs
+
+### Developer Documentation
+
+**DEVELOPMENT.md** - Developer guide
+- Architecture overview
+- Code structure
+- Development setup
+- Roadmap
+
+**CONTRIBUTING.md** - This file
+- Contribution process
+- Workflow guidelines
+- Standards
+
+**PROJECT_STATUS.md** - Project state
+- Current version
+- Feature status
+- Testing matrix
+- Roadmap
+
+### Technical Documentation
+
+**SSE_MODE_ANALYSIS.md** - Technical decisions
+- Why SSE was removed
+- Alternatives considered
+- Implementation details
+
+**TESTING_FINDINGS.md** - Test results
+- What was tested
+- Results and learnings
+- Recommendations
+
+**ZedExtensions.md** - Research notes
+- Zed extension development
+- MCP integration
+- Reference material
+
+### Configuration Documentation
+
+**configuration/default_settings.jsonc** - Settings template
+- All available options
+- Inline comments
+- Examples
+- Default values
+
+## Getting Help
+
+If you need help:
+
+1. **Check existing documentation:**
+   - README.md for user questions
+   - DEVELOPMENT.md for developer questions
+   - This file for contribution questions
+
+2. **Search issues:**
+   - Check if your question was already asked
+   - Look for similar problems
+
+3. **Ask in issues:**
+   - Open a new issue with your question
+   - Use "Question" label if available
+   - Provide context about what you're trying to do
+
+4. **Contact maintainers:**
+   - @parkingmeter on Gitea
+   - Open a discussion if available
+
+## Code of Conduct
+
+- Be respectful and constructive
+- Focus on the code, not the person
+- Help others learn and improve
+- Follow the project's coding standards
+- Ask questions when unsure
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache License 2.0, the same license as the project.
+
+---
+
+**Thank you for contributing to Tendril!** 🎉
+
+Your contributions help make this project better for everyone.
+

PROJECT_STATUS.md

@@ -508,7 +508,7 @@ The extension is being mirrored to GitHub for Zed marketplace publication for th
 
 # Keep in sync:
 git push --mirror https://github.com/your-username/tendril.git
-# Or use GitHub Actions for automatic syncing
+# Or use Gitea Actions (or GitHub Actions) for automatic syncing
 ```
 
 ### Marketplace Publication

README.md

@@ -459,13 +459,22 @@ For issues or questions:
 
 ## Contributing
 
-Contributions are welcome! Please:
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:
 
+- Development workflow
+- Branch management
+- Documentation standards
+- Code quality requirements
+- Pull request process
+
+**Quick Start:**
 1. Fork the repository
-2. Create a feature branch
+2. Create a feature branch: `git checkout -b feature/your-feature-name`
 3. Make your changes and test thoroughly
 4. Submit a pull request with a clear description
 
+For full details, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Authors
 
 - Ryan Parmeter ([@parkingmeter](https://git.parkingmeter.info/parkingmeter))

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 `kb/_guides/PROJECT-SETUP-GUIDE/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**: `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
+

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
+

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
+

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
+

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
+

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`
+

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
+

kb/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog — KB System
+
+All notable changes to KB files and system.
+
+## [2025-01-27] KB System Setup
+
+### Added
+- `kb/README.md` - KB system documentation
+- `kb/_templates/note.md` - Note template
+- `kb/_templates/decision.md` - Decision template
+- `kb/_templates/howto.md` - HowTo template
+- `kb/_guides/KB_INGEST_PROMPT.md` - KB ingestion system prompt
+- `kb/scripts/generate-index.sh` - Index generation script
+- `kb/CHANGELOG.md` - KB changelog (this file)
+
+### Notes
+- Phase 2 KB System Setup completed
+- All templates include complete frontmatter with all 18 required fields
+- Index generation script created and tested
+- System customized for Tendril project (replaced "pairs" references with "tendril")
+
+---
+

kb/README.md

@@ -0,0 +1,289 @@
+# Knowledge Base (KB) System
+
+**Last updated**: 2025-01-27
+
+## Overview
+
+The KB system provides a lightweight, LLM-friendly staging area for external information that may inform Tendril project development. It uses structured routing, confidence scoring, and automatic indexing.
+
+The KB system complements the phase documentation system by capturing:
+- 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
+
+---
+
+## Directory Structure
+
+```
+kb/
+├── 01_projects/              # Project-specific notes
+│   ├── tendril/               # Tendril project notes
+│   └── _shared/               # Cross-project notes
+├── 02_systems/               # Infrastructure, DevOps, tooling
+├── 03_research/              # Informal research, links
+├── 04_design/                # Product specs, UX, copy
+├── 05_decisions/              # ADR-style decisions
+├── 06_glossary/               # Terms, acronyms
+├── 07_playbooks/             # How-to guides, SOPs
+├── 08_archive/                # Superseded content
+├── _guides/                   # KB system guidelines (read-only)
+│   └── KB_INGEST_PROMPT.md    # System prompt for ingestion
+├── _templates/                # File templates (read-only)
+│   ├── note.md
+│   ├── decision.md
+│   └── howto.md
+├── _inbox/                    # Unclassified content (rare)
+├── _review_queue/             # Low-confidence routing (<0.60)
+├── _index.md                  # Auto-generated searchable index
+├── CHANGELOG.md               # KB change tracking
+├── README.md                  # KB system documentation (this file)
+└── scripts/
+    └── generate-index.sh      # Index generation script
+```
+
+---
+
+## File Naming Schema
+
+**Pattern**: `YYYY-MM-DD--slug--type.md`
+
+### Components
+
+- **Date (YYYY-MM-DD)**: Date content was created or captured
+- **Slug**: 3-8 lowercase words, hyphen-joined, no stop-words (a, an, the, and, or, but, etc.)
+- **Type**: One of: `idea`, `note`, `spec`, `decision`, `howto`, `retro`, `meeting`
+- **Multi-part files**: Append `--p1`, `--p2`, etc. for long content
+
+### Examples
+
+- ✅ `2025-01-27--api-authentication-flow--spec.md`
+- ✅ `2025-01-27--user-onboarding-decision--decision.md`
+- ✅ `2025-01-27--comprehensive-api-design--spec--p1.md` (multi-part)
+- ❌ `api-design.md` (missing date and type)
+- ❌ `2025-01-27--the-api--note.md` (contains stop-word "the")
+
+### Regex Pattern
+
+```
+^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$
+```
+
+---
+
+## Frontmatter Schema
+
+Every KB file MUST have complete YAML frontmatter with all 18 required fields.
+
+### Required Fields (18)
+
+```yaml
+---
+title: "Descriptive title in sentence case"
+date: "YYYY-MM-DD"                    # Must match filename date
+captured_at: "YYYY-MM-DD"             # Same as date (project compatibility)
+author: ["author name"]                # Array, default ["unknown author"]
+source: { kind: pulse|chat|web|doc, ref: "<link-or-id>" }
+source_type: voice|web|pdf|image|personal_note|chat|pulse
+project: ["tendril"]                  # Array, default ["tendril"] for Tendril
+related_projects: ["tendril"]         # Same as project (compatibility)
+topics: ["topic1", "topic2"]          # Array of 2-5 topic keywords
+tags: ["tag1", "tag2"]                # Array of 2-8 tags
+type: idea|note|spec|decision|howto|retro|meeting  # Must match filename type
+status: draft|active|archived
+phase_relevance: ["phase-01", "phase-02"]  # Array of relevant phases or []
+routing_hint: "Brief explanation of routing decision"
+proposed_path: "kb/XX_category/"      # Where LLM intends to file it
+routing_confidence: 0.87              # Numeric 0.00-1.00
+related: []                           # Array of related file paths
+summary: "One to three sentence summary of the content"
+---
+```
+
+### Optional Fields
+
+```yaml
+key_takeaways: ["takeaway1", "takeaway2"]
+action_candidates: ["action1", "action2"]
+```
+
+### Field Guidelines
+
+- **title**: Clear, descriptive, sentence case (not title case)
+- **date**: Must match filename date prefix (YYYY-MM-DD)
+- **author**: Array format, use `["unknown author"]` if unknown
+- **source**: Object with `kind` (pulse, chat, web, doc) and `ref` (link, ID, or identifier)
+- **project**: Array, default `["tendril"]` for Tendril project
+- **topics**: Array of 2-5 topic keywords (e.g., `["authentication", "security", "api"]`)
+- **tags**: Array of 2-8 tags for cross-cutting categorization (e.g., `["backend", "urgent", "review-needed"]`)
+- **type**: Must match filename type suffix exactly
+- **status**: `draft` for new content, `active` for current/relevant, `archived` for old
+- **routing_hint**: Brief explanation (1-2 sentences) of routing decision
+- **proposed_path**: The directory path where the LLM intends to file the content
+- **routing_confidence**: Numeric value between 0.00 and 1.00 indicating confidence in the routing decision
+- **related**: Array of related file paths or references
+- **summary**: Concise 1-3 sentence summary of the content
+- **phase_relevance**: Array of relevant phases (e.g., `["phase-01", "phase-02"]`) or empty array `[]`
+
+---
+
+## Routing Decision Tree
+
+Content must be routed to one of these directories based on its primary purpose:
+
+1. **Is it project-specific?** → `/kb/01_projects/tendril/` or `_shared/`
+2. **Is it a how-to or procedure?** → `/kb/07_playbooks/`
+3. **Is it a decision with rationale?** → `/kb/05_decisions/`
+4. **Is it about infrastructure/tooling?** → `/kb/02_systems/`
+5. **Is it research or external reference?** → `/kb/03_research/`
+6. **Is it design/UX/copy?** → `/kb/04_design/`
+7. **Is it a definition or term?** → `/kb/06_glossary/`
+8. **Is it obsolete?** → `/kb/08_archive/` (only if truly superseded)
+9. **Unclear?** → `/kb/_inbox/` (should be rare)
+
+### Routing Destinations
+
+- **`/kb/01_projects/tendril/`** - Tendril project-specific notes, tasks, or updates
+- **`/kb/01_projects/_shared/`** - Cross-project notes that apply to multiple projects
+- **`/kb/02_systems/`** - Infrastructure, DevOps, tooling, technical systems, architecture decisions
+- **`/kb/03_research/`** - Links, papers, competitor notes, external research, learning materials
+- **`/kb/04_design/`** - Product specs, UX design, copy, user experience, interface design
+- **`/kb/05_decisions/`** - ADR-style decisions with rationale, architectural decisions, strategic choices
+- **`/kb/06_glossary/`** - Terms, acronyms, definitions, vocabulary
+- **`/kb/07_playbooks/`** - How-to guides, SOPs, runbooks, procedures, operational guides
+- **`/kb/08_archive/`** - Old or superseded content (use sparingly, prefer deletion if truly obsolete)
+- **`/kb/_inbox/`** - Use only if content cannot be clearly classified (should be rare)
+- **`/kb/_review_queue/`** - Low-confidence routing items requiring human review (routing_confidence < 0.60)
+
+---
+
+## Routing Confidence System
+
+After determining the proposed routing destination, you MUST assess your confidence level:
+
+- **0.90–1.00**: Crystal clear placement - content clearly matches category
+- **0.75–0.89**: Good guess - content fits well but might have minor ambiguity
+- **0.60–0.74**: Uncertain - content could fit multiple categories, needs review
+- **<0.60**: Low confidence - unclear routing, send to `_review_queue/` instead of proposed path
+
+### Routing Policy
+
+If `routing_confidence < 0.60`, the file MUST be placed in `kb/_review_queue/` instead of the proposed path, but still include `proposed_path` in frontmatter for human review.
+
+---
+
+## Usage Guidelines
+
+### Creating KB Files
+
+1. **Use templates**: Copy from `kb/_templates/` and fill in all required fields
+2. **Follow naming convention**: `YYYY-MM-DD--slug--type.md`
+3. **Complete frontmatter**: All 18 required fields must be present
+4. **Route appropriately**: Use routing decision tree to determine correct category
+5. **Assess confidence**: Set `routing_confidence` honestly (0.00-1.00)
+
+### KB Ingestion
+
+For LLM-assisted KB ingestion:
+
+1. Paste `/kb/_guides/KB_INGEST_PROMPT.md` contents as the first message in Cursor chat
+2. Provide raw content after the system prompt
+3. LLM will analyze and route content appropriately
+4. Review generated JSON output before creating file
+5. Update index and changelog after creating KB file
+
+See `kb/_guides/KB_INGEST_PROMPT.md` for complete ingestion instructions.
+
+### Index and Changelog Updates
+
+**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`
+
+**NEVER skip these steps** - Both index and changelog updates are mandatory for KB system integrity.
+
+---
+
+## Integration with Phase Documentation
+
+The KB system complements the phase documentation system:
+
+- **KB decisions** (`kb/05_decisions/`) complement phase-specific ADRs (`tendril/phases/phase-XX-name/decisions.md`)
+- **KB entries** can reference project phases via `phase_relevance[]` field
+- **KB research** (`kb/03_research/`) may inform phase planning and development
+- **KB playbooks** (`kb/07_playbooks/`) provide operational guides for phase work
+
+---
+
+## Index Generation
+
+The KB index (`kb/_index.md`) is automatically generated and provides:
+
+- File listing by category
+- Topics index (all unique topics with file references)
+- Tags index (all unique tags with file references)
+- Phase relevance index (files organized by phase)
+
+### Manual Index Generation
+
+```bash
+kb/scripts/generate-index.sh
+```
+
+### Automatic Index Updates
+
+Gitea Actions workflow (`.github/workflows/kb-index-update.yml`) will auto-update the index on push to main when KB files change. (To be configured in Phase 3)
+
+---
+
+## Templates
+
+Templates are available in `kb/_templates/`:
+
+- **`note.md`** - General notes template
+- **`decision.md`** - ADR-style decision template
+- **`howto.md`** - How-to guide template
+
+All templates include complete frontmatter with all 18 required fields and placeholder values.
+
+---
+
+## Related Documentation
+
+- **KB Ingestion Prompt**: `kb/_guides/KB_INGEST_PROMPT.md` - Complete system prompt for LLM-assisted KB ingestion
+- **KB Changelog**: `kb/CHANGELOG.md` - Change tracking for KB system
+- **KB Index**: `kb/_index.md` - Auto-generated searchable index
+- **Phase Documentation**: `tendril/phases/phase-XX-name/` - Phase-specific documentation
+
+---
+
+**Location**: `kb/`  
+**Maintained by**: Tendril Project Team  
+**Repository**: https://git.parkingmeter.info/Mycelium/tendril
+

kb/_guides/CURSOR_WINDOWS_SETUP.md

@@ -0,0 +1,172 @@
+# Gitea Development Environment Setup Guide for Windows & Cursor
+
+**Objective:** This document details the complete process for configuring a local development environment on a Windows PC to work with a Gitea-hosted source code repository. It covers connecting the Cursor IDE using the Model Context Protocol (MCP) and cloning a project repository to begin work.
+
+## Core Components
+
+*   **Gitea:** The remote Git server where the project's code is stored.
+
+*   **Gitea MCP Server:** A command-line application that acts as a bridge between Cursor and Gitea.
+
+*   **Cursor IDE:** The code editor used for development.
+
+*   **Git for Windows:** The underlying version control software used for all `git` commands.
+
+---
+
+## Phase 1: Environment Setup and Configuration
+
+### Step 1: Download and Prepare the Gitea MCP Server
+
+The first step is to get the bridge application that allows Cursor to communicate with Gitea.
+
+1.  **Download the Binary:**
+
+    *   Navigate to the official Gitea MCP releases page: [https://gitea.com/gitea/gitea-mcp/releases](https://gitea.com/gitea/gitea-mcp/releases)
+
+    *   From the latest release, download the zip archive for Windows, named `gitea-mcp_Windows_x86_64.zip`.
+
+2.  **Create a Permanent Location:**
+
+    *   Create a dedicated folder on your computer where this tool will live permanently. For this guide, we used: `D:\OneDrive\GIT_Parkingmeter\gitea-mcp_Windows_x86_64`
+
+3.  **Extract the Files:**
+
+    *   Extract the contents of the downloaded `.zip` file into the folder you just created. The most important file is `gitea-mcp.exe`.
+
+### Step 2: Generate a Gitea Access Token
+
+Cursor needs a secure "password" to access your Gitea account. This is called an Access Token.
+
+1.  **Navigate to Gitea Settings:** Go to your Gitea instance's Applications page: [https://git.parkingmeter.info/user/settings/applications](https://git.parkingmeter.info/user/settings/applications)
+
+2.  **Generate a New Token:**
+
+    *   Give the token a descriptive name (e.g., "Cursor on Windows PC").
+
+    *   Set the following permissions to **Read and Write**:
+
+        *   `issue`
+
+        *   `repository`
+
+        *   `user`
+
+    *   Click **"Generate Token"**.
+
+3.  **Copy and Save the Token:**
+
+    *   **CRITICAL:** Gitea will display the token only once. Copy it immediately and save it in a secure place (like a password manager or a temporary text file). You will need it in the next steps.
+
+### Step 3: Create the Server Startup Script (`run-gitea.bat`)
+
+To ensure the Gitea MCP Server starts reliably every time, we will create a simple startup script.
+
+1.  **Create the File:**
+
+    *   In the same folder where you extracted `gitea-mcp.exe`, create a new file named `run-gitea.bat`.
+
+2.  **Edit the Script:**
+
+    *   Open `run-gitea.bat` with a text editor (like Notepad) and paste the following content:
+
+    ```batch
+    @echo off
+    echo Starting Gitea MCP server in HTTP mode...
+    echo Do not close this window!
+    D:\OneDrive\GIT_Parkingmeter\gitea-mcp_Windows_x86_64\gitea-mcp.exe -t http --host https://git.parkingmeter.info --token YOUR_GITEA_TOKEN_HERE
+    ```
+
+3.  **Add Your Token:**
+
+    *   In the script, **replace `YOUR_GITEA_TOKEN_HERE` with the actual Gitea token** you copied in Step 2.
+
+    *   Save and close the file.
+
+### Step 4: Configure Cursor's MCP Tools
+
+This is the most important step. We need to tell Cursor how to find and use your new Gitea server.
+
+1.  **Open Cursor's MCP Settings:**
+
+    *   In Cursor, navigate to the settings UI.
+
+    *   Go to the **"Tools & MCP"** section.
+
+    *   You will see a file named **`mcp.json`**. Open this file.
+
+2.  **Add the Gitea Server Configuration:**
+
+    *   Inside the `"mcpServers": { ... }` object, add the following configuration block. Be sure to add a comma `,` after the preceding entry.
+
+    ```json
+        "gitea-local": {
+          "url": "http://localhost:8080/mcp",
+          "headers": {
+            "Authorization": "Bearer YOUR_GITEA_TOKEN_HERE"
+          }
+        }
+    ```
+
+3.  **Add Your Token:**
+
+    *   Again, **replace `YOUR_GITEA_TOKEN_HERE` with your actual Gitea token**.
+
+    *   **IMPORTANT:** The word `Bearer` followed by a space must be kept in front of the token.
+
+4.  **Save the `mcp.json` file.**
+
+### Step 5: Test the Connection Workflow
+
+This is the process you will follow each time you want to use the Gitea integration.
+
+1.  **Manually Start the Server:**
+
+    *   Using File Explorer, navigate to your `gitea-mcp_Windows_x86_64` folder.
+
+    *   **Double-click the `run-gitea.bat` script.**
+
+    *   A black command prompt window will appear and stay open. This is your server. **You must keep this window running** while you use the integration in Cursor.
+
+2.  **Restart and Test in Cursor:**
+
+    *   Completely close and reopen the Cursor application to ensure it loads the new configuration.
+
+    *   Open the AI Chat panel (`Ctrl + L`).
+
+    *   Send the command: `@gitea-local list my repositories`.
+
+    *   The AI may initially be confused. **Confirm that it should make a direct API call** to your Gitea instance, providing the URL (`https://git.parkingmeter.info`) when prompted.
+
+    *   **Success is confirmed when the AI returns a formatted list of your Gitea repositories.**
+
+### Step 6: Clone the Project Repository
+
+The final setup step is to download the project's source code to your machine.
+
+1.  **Open a Terminal in Cursor:**
+
+    *   Go to the top menu and select **Terminal -> New Terminal**.
+
+2.  **Navigate to Your Projects Directory:**
+
+    *   In the terminal, change to the folder where you want to store your projects. We used:
+
+        ```bash
+        cd /d/OneDrive/GIT_Parkingmeter
+        ```
+
+3.  **Clone the Repository:**
+
+    *   Run the `git clone` command with the project's URL:
+
+        ```bash
+        git clone https://git.parkingmeter.info/Mycelium/tendril.git
+        ```
+
+---
+
+## Phase One Complete
+
+At this point, your environment is fully configured. You have successfully linked Cursor to your Gitea account and downloaded a local copy of the project code. You are now ready to move on to Phase Two: The Development Workflow (editing, pushing, and pulling code).
+

kb/_guides/KB_INGEST_PROMPT.md

@@ -0,0 +1,309 @@
+# KB Ingestion System Prompt
+
+**Use this prompt in Cursor before pasting content to be ingested into the Knowledge Base.**
+
+---
+
+## System Instructions
+
+You are a Knowledge Base ingestion assistant. Your role is to analyze incoming content (from "Pulse Daily" chats, ideas, notes, etc.) and route it to the appropriate location in the `/kb/` directory structure with proper naming, frontmatter, and formatting.
+
+## Classification and Routing Rules
+
+Content must be routed to one of these directories based on its primary purpose:
+
+- **`/kb/01_projects/tendril/`** - Tendril project-specific notes, tasks, or updates
+- **`/kb/01_projects/_shared/`** - Cross-project notes that apply to multiple projects
+- **`/kb/02_systems/`** - Infrastructure, DevOps, tooling, technical systems, architecture decisions
+- **`/kb/03_research/`** - Links, papers, competitor notes, external research, learning materials
+- **`/kb/04_design/`** - Product specs, UX design, copy, user experience, interface design
+- **`/kb/05_decisions/`** - ADR-style decisions with rationale, architectural decisions, strategic choices
+- **`/kb/06_glossary/`** - Terms, acronyms, definitions, vocabulary
+- **`/kb/07_playbooks/`** - How-to guides, SOPs, runbooks, procedures, operational guides
+- **`/kb/08_archive/`** - Old or superseded content (use sparingly, prefer deletion if truly obsolete)
+- **`/kb/_inbox/`** - Use only if content cannot be clearly classified (should be rare)
+- **`/kb/_review_queue/`** - Low-confidence routing items requiring human review (routing_confidence < 0.60)
+
+### Routing Decision Tree
+
+1. **Is it project-specific?** → `/kb/01_projects/tendril/` or `_shared/`
+2. **Is it a how-to or procedure?** → `/kb/07_playbooks/`
+3. **Is it a decision with rationale?** → `/kb/05_decisions/`
+4. **Is it about infrastructure/tooling?** → `/kb/02_systems/`
+5. **Is it research or external reference?** → `/kb/03_research/`
+6. **Is it design/UX/copy?** → `/kb/04_design/`
+7. **Is it a definition or term?** → `/kb/06_glossary/`
+8. **Is it obsolete?** → `/kb/08_archive/` (only if truly superseded)
+9. **Unclear?** → `/kb/_inbox/` (should be rare)
+
+### Routing Confidence Assessment
+
+After determining the proposed routing destination, you MUST assess your confidence level:
+
+- **0.90–1.00:** Crystal clear placement - content clearly matches category, type, and purpose
+- **0.75–0.89:** Good guess - content fits well but might have minor ambiguity
+- **0.60–0.74:** Uncertain - content could fit multiple categories, needs review
+- **<0.60:** Low confidence - unclear routing, send to `_review_queue/` instead of proposed path
+
+**Routing Policy:** If `routing_confidence < 0.60`, the file MUST be placed in `kb/_review_queue/` instead of the proposed path, but still include `proposed_path` in frontmatter for human review.
+
+## File Naming Standards
+
+**Format:** `YYYY-MM-DD--slug--type.md`
+
+### Components
+
+- **Date (YYYY-MM-DD):** Use the date the content was created or captured (today's date if unknown)
+- **Slug:** 3-8 lowercase words, hyphen-joined, no stop-words (a, an, the, and, or, but, etc.)
+  - Good: `user-authentication-flow`, `api-rate-limiting-strategy`, `cursor-workflow-setup`
+  - Bad: `the-api`, `a-user`, `and-authentication`
+- **Type:** One of: `idea`, `note`, `spec`, `decision`, `howto`, `retro`, `meeting`
+- **Multi-part files:** If content is too long, append `--p1`, `--p2`, etc. to the filename
+  - Example: `2025-01-27--comprehensive-api-design--spec--p1.md`
+
+### Type Selection
+
+- **`idea`** - New concepts, proposals, brainstorming
+- **`note`** - General notes, observations, thoughts
+- **`spec`** - Specifications, requirements, detailed plans
+- **`decision`** - ADR-style decisions (should go in `/kb/05_decisions/`)
+- **`howto`** - Step-by-step guides (should go in `/kb/07_playbooks/`)
+- **`retro`** - Retrospectives, post-mortems, lessons learned
+- **`meeting`** - Meeting notes, summaries
+
+## Frontmatter Requirements
+
+Every KB file MUST have complete YAML frontmatter with all required fields. The base system requires 14 fields, but projects may add additional fields (like `captured_at`, `source_type`, `related_projects`, `phase_relevance` for Tendril).
+
+**Base Required Fields (14):**
+```yaml
+---
+title: "Descriptive title in sentence case"
+date: "YYYY-MM-DD"
+author: ["author name"]  # Array, default to ["unknown author"] if unknown
+source: { kind: pulse|chat|web|doc, ref: "<link-or-id>" }
+project: ["tendril"]  # Array, default ["tendril"] for Tendril project
+topics: []  # Array of topic keywords
+tags: []  # Array of tags for categorization
+type: idea|note|spec|decision|howto|retro|meeting
+status: draft|active|archived
+routing_hint: "Brief explanation of why this was routed here"
+proposed_path: "kb/XX_category/"  # Where LLM intends to file it
+routing_confidence: 0.87  # Numeric value 0.00-1.00
+related: []  # Array of related file paths or references
+summary: "One to three sentence summary of the content"
+---
+```
+
+**Optional Project-Specific Fields** (add as needed):
+- `captured_at` - Same as date (for compatibility)
+- `source_type` - voice|web|pdf|image|personal_note|chat|pulse
+- `related_projects` - Same as project (for compatibility)
+- `phase_relevance` - Array of relevant phases (e.g., `["phase-01", "phase-02"]`)
+- `key_takeaways` - Array of key insights
+- `action_candidates` - Array of potential action items
+
+### Field Guidelines
+
+- **title:** Clear, descriptive, sentence case (not title case)
+- **date:** Must match filename date prefix (YYYY-MM-DD)
+- **author:** Array format, use `["unknown author"]` if unknown
+- **source:** Object with `kind` (pulse, chat, web, doc) and `ref` (link, ID, or identifier)
+- **project:** Array, default `["tendril"]` for Tendril project, expandable for future projects
+- **topics:** Array of 2-5 topic keywords (e.g., `["authentication", "security", "api"]`)
+- **tags:** Array of 2-8 tags for cross-cutting categorization (e.g., `["backend", "urgent", "review-needed"]`)
+- **type:** Must match filename type suffix exactly
+- **status:** `draft` for new content, `active` for current/relevant, `archived` for old
+- **routing_hint:** Brief explanation (1-2 sentences) of routing decision
+- **proposed_path:** The directory path where the LLM intends to file the content
+- **routing_confidence:** Numeric value between 0.00 and 1.00 indicating confidence in the routing decision
+- **related:** Array of related file paths or references
+- **summary:** Concise 1-3 sentence summary of the content
+
+## Output Format
+
+**CRITICAL:** You MUST output your response in a JSON code block with this exact structure:
+
+```json
+{
+  "file_path": "kb/XX_category/YYYY-MM-DD--slug--type.md",
+  "frontmatter": {
+    "title": "...",
+    "date": "YYYY-MM-DD",
+    "author": ["..."],
+    "source": { "kind": "...", "ref": "..." },
+    "project": ["tendril"],
+    "topics": ["..."],
+    "tags": ["..."],
+    "type": "...",
+    "status": "...",
+    "routing_hint": "...",
+    "proposed_path": "kb/XX_category/",
+    "routing_confidence": 0.87,
+    "related": [],
+    "summary": "..."
+  },
+  "content": "# Title\n\n[Markdown content here]"
+}
+```
+
+**IMPORTANT:** The `file_path` in the JSON output MUST reflect the actual destination:
+- If `routing_confidence >= 0.60`: Use the `proposed_path` as the actual `file_path`
+- If `routing_confidence < 0.60`: Use `kb/_review_queue/` as the actual `file_path` (but still include `proposed_path` in frontmatter)
+
+## Quality and Style Guidelines
+
+1. **Content Quality:**
+   - Preserve original meaning and intent
+   - Improve clarity and structure without changing substance
+   - Use proper Markdown formatting (headers, lists, code blocks)
+   - Break long content into logical sections
+
+2. **Writing Style:**
+   - Use clear, concise language
+   - Prefer active voice
+   - Use proper grammar and spelling
+   - Maintain professional tone
+
+3. **Structure:**
+   - Start with a clear title (H1)
+   - Use H2 for major sections
+   - Use H3 for subsections
+   - Include a summary section if helpful
+   - Add "Related" section for cross-references
+
+4. **Markdown Best Practices:**
+   - Use fenced code blocks with language tags
+   - Use proper list formatting
+   - Use links for references
+   - Use emphasis (bold/italic) sparingly
+
+## Safety Constraints
+
+**NEVER:**
+- Modify files in `/kb/_guides/` or `/kb/_templates/`
+- Overwrite existing files without explicit user permission
+- Create files outside `/kb/` directory structure
+- Skip frontmatter validation
+- Use invalid filename patterns
+- Create duplicate files (check existing files first)
+
+**ALWAYS:**
+- Validate filename matches pattern: `YYYY-MM-DD--slug--type.md`
+- Ensure all required frontmatter fields are present
+- Verify date in frontmatter matches filename date
+- Verify type in frontmatter matches filename type
+- Check for existing similar files to avoid duplicates
+- Use appropriate routing based on content purpose
+- Assess routing confidence honestly (0.00-1.00)
+- Route low-confidence items (<0.60) to `kb/_review_queue/` instead of proposed path
+
+## Example Workflow
+
+1. User pastes content into Cursor
+2. You analyze the content to determine:
+   - Primary purpose and routing destination
+   - Appropriate type (idea, note, spec, etc.)
+   - Key topics and tags
+   - Related content
+   - **Routing confidence level (0.00-1.00)**
+3. You generate:
+   - Proper filename following naming standards
+   - Complete frontmatter with all required fields
+   - Well-structured Markdown content
+4. You determine actual file path:
+   - If `routing_confidence >= 0.60`: Use `proposed_path` as actual destination
+   - If `routing_confidence < 0.60`: Use `kb/_review_queue/` as actual destination
+5. You output JSON code block with file_path, frontmatter, and content
+6. User (or automation) creates the file from your JSON output
+
+## Validation Checklist
+
+Before outputting JSON, verify:
+
+- [ ] Filename matches pattern: `YYYY-MM-DD--slug--type.md`
+- [ ] All required frontmatter fields are present
+- [ ] Date in frontmatter matches filename date
+- [ ] Type in frontmatter matches filename type
+- [ ] Routing confidence is assessed honestly (0.00-1.00)
+- [ ] `proposed_path` is set to intended destination directory
+- [ ] Actual `file_path` reflects routing policy (if confidence < 0.60, use `kb/_review_queue/`)
+- [ ] Routing destination is appropriate for content
+- [ ] Content is well-structured Markdown
+- [ ] Summary accurately describes the content
+- [ ] Topics and tags are relevant and useful
+- [ ] Related references are valid (if any)
+
+---
+
+## Completion Summary and Reporting
+
+**CRITICAL:** After outputting the JSON code block, you MUST also provide a completion summary in markdown format with the following sections:
+
+### What Was Accomplished
+
+- **File Created**: `kb/XX_category/YYYY-MM-DD--slug--type.md`
+- **Routing Decision**: [Brief explanation of why this content was routed to this category]
+- **Content Type**: [type] in [category]
+- **File Status**: [draft/active/archived]
+
+### KB File Details
+
+- **Title**: [title from frontmatter]
+- **Type**: [type from frontmatter]
+- **Topics**: [list of topics from frontmatter]
+- **Tags**: [list of tags from frontmatter]
+- **Summary**: [summary from frontmatter]
+- **Author**: [author from frontmatter]
+- **Source**: [source kind and ref from frontmatter]
+
+### Possible Uses in Project
+
+- [How this KB can be used in project planning/development]
+- [Related workflows or decisions this informs]
+- [Potential integrations with other systems or documentation]
+- [Who might benefit from this knowledge]
+
+### Local Document Update Report
+
+**MANDATORY STEPS:** After creating the KB file, you must:
+
+1. **Update Index:**
+   - Run: `kb/scripts/generate-index.sh`
+   - This regenerates `kb/_index.md` with the new file's metadata
+   - Verify the script completes successfully
+   - Check that the new file appears in `kb/_index.md`
+
+2. **Update Changelog:**
+   - Add entry to `kb/CHANGELOG.md` with the following format:
+     ```markdown
+     ## [YYYY-MM-DD] KB File Added
+     
+     ### Added
+     - `kb/XX_category/YYYY-MM-DD--slug--type.md` - [Brief description of content]
+     ```
+   - 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 the KB file contains
+
+3. **Commit Changes:**
+   - Commit all three changes together:
+     - The new KB file
+     - The updated `kb/_index.md`
+     - The updated `kb/CHANGELOG.md`
+   - Use commit message: `docs(kb): add [filename-slug] and update index/changelog`
+   - Example: `docs(kb): add api-auth-decision and update index/changelog`
+
+**Status Checklist:**
+- [ ] KB file created at correct path
+- [ ] Index updated: `kb/scripts/generate-index.sh` run successfully
+- [ ] Changelog updated: Entry added to `kb/CHANGELOG.md`
+- [ ] All changes committed together
+- [ ] Commit message follows format: `docs(kb): add [filename-slug] and update index/changelog`
+
+**Note:** If you cannot run the index generation script or update the changelog automatically, clearly indicate what needs to be done manually in the "Local Document Update Report" section.
+
+---
+
+**Remember:** The goal is to create well-organized, discoverable knowledge that can be easily found and referenced later. Take time to classify correctly and provide complete metadata. Always update the index and changelog after creating KB files.
+

kb/_guides/PROJECT-SETUP-GUIDE/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**: `kb/_guides/PROJECT-SETUP-GUIDE/PHASE-0-GITEA-UPDATES.md`  
+**Related**: Phase 0 setup, Gitea Actions compatibility
+

kb/_guides/PROJECT-SETUP-GUIDE/PHASE-1-PLAN.md

@@ -0,0 +1,209 @@
+# Phase 1: Phase Documentation System - Detailed Plan
+
+**Objective**: Set up phase-based project management with synchronized documents
+
+**Status**: Ready for Review  
+**Date**: 2025-01-27
+
+---
+
+## Overview
+
+Phase 1 establishes the phase documentation system that will track all project work in synchronized documents. Each phase will have four documents that stay in sync automatically via Cursor rules.
+
+---
+
+## Tasks Breakdown
+
+### Task 1: Create Phase Documentation Templates
+
+**Location**: `tendril/phases/phase-00-foundation/`
+
+**Files to Create**:
+1. **`blueprint.md`** - Complete phase specification template
+2. **`tasks.md`** - Task tracking template (mirrors Gitea issues)
+3. **`decisions.md`** - ADR (Architecture Decision Record) template
+4. **`changelog.md`** - Change history template
+
+**Templates Source**: `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
+
+**Customizations Needed**:
+- Replace `pairs/phases/` with `tendril/phases/`
+- Replace "GitHub issues" with "Gitea issues" in tasks.md
+- Update project name to "Tendril"
+- Update repository URL to Gitea instance
+
+---
+
+### Task 2: Populate Phase 0 (Foundation) with Current Project State
+
+**Location**: `tendril/phases/phase-00-foundation/`
+
+**Data Sources**:
+- `PROJECT_STATUS.md` - Current v0.1.0 status
+- `README.md` - Project description and features
+- `DEVELOPMENT.md` - Architecture and roadmap
+- Phase 0 work just completed (Cursor rules, directory structure, Gitea docs)
+
+**Phase 0 Content to Document**:
+
+**Blueprint.md**:
+- **Project**: Tendril
+- **Phase**: Phase 0: Foundation & Cursor Rules Setup
+- **Status**: ✅ Complete
+- **Objectives**:
+  - Establish Cursor rules system
+  - Create directory structure
+  - Set up agent guidelines
+  - Create Gitea documentation
+  - Organize phase updates documentation
+- **Deliverables**:
+  - `.cursorrules` file
+  - `docs/AGENT-GUIDELINES.md`
+  - `docs/GITEA/` documentation suite
+  - `kb/_guides/PROJECT-SETUP-GUIDE/` organization
+  - Complete directory structure
+- **Timeline**: Completed 2025-01-27
+- **Definition of Done**: All Phase 0 tasks completed and committed
+
+**Tasks.md**:
+- Mirror completed work from Phase 0
+- Mark all Phase 0 tasks as complete
+- Reference commit: `0a131a2`
+
+**Decisions.md**:
+- ADR-000: Use Gitea (self-hosted) instead of GitHub
+- ADR-001: Use `tendril/phases/` directory structure
+- ADR-002: Implement comprehensive Cursor rules system
+- ADR-003: Create Gitea-specific documentation
+
+**Changelog.md**:
+- **2025-01-27**: Phase 0 completed - Established foundation
+  - Created `.cursorrules` with comprehensive rules
+  - Created directory structure (phases, KB, workflows, prompts)
+  - Created `docs/AGENT-GUIDELINES.md`
+  - Created Gitea documentation suite
+  - Organized phase updates documentation
+  - Committed all changes (commit `0a131a2`)
+
+---
+
+### Task 3: Create Phase 1 Blueprint for Next Development Cycle
+
+**Location**: `tendril/phases/phase-01-testing-validation/` (or similar name)
+
+**Phase 1 Content** (based on PROJECT_STATUS.md roadmap):
+
+**Blueprint.md**:
+- **Project**: Tendril
+- **Phase**: Phase 1: Testing & Validation
+- **Status**: ⏳ Planned
+- **Objectives**:
+  - Test with actual Gitea instances (various versions)
+  - Test binary discovery on multiple systems
+  - Test Docker mode on Linux, macOS, Windows
+  - Test with self-hosted Gitea instances
+  - Validate error messages are helpful
+  - Performance testing with large repositories
+- **Deliverables**:
+  - Test results documentation
+  - Platform compatibility matrix
+  - Error message improvements
+  - Performance benchmarks
+- **Timeline**: TBD
+- **Definition of Done**: All testing complete, results documented, issues resolved
+
+**Tasks.md**:
+- Create tasks from PROJECT_STATUS.md "What's Next" section
+- Link to Gitea issues when created
+- Organize by category (Testing, UX, Documentation, Release)
+
+**Decisions.md**:
+- Will be populated as decisions are made during Phase 1
+
+**Changelog.md**:
+- Will be populated as Phase 1 progresses
+
+---
+
+## Customizations for Tendril
+
+### Directory Structure
+- **Use**: `tendril/phases/` (not `pairs/phases/`)
+- **Reason**: Matches project name and structure
+
+### Platform References
+- **Use**: "Gitea" (not "GitHub")
+- **Tasks.md**: "mirrors Gitea issues" (not "GitHub issues")
+- **Repository**: https://git.parkingmeter.info/Mycelium/tendril
+
+### Project Context
+- **Project Name**: Tendril
+- **Current Version**: v0.1.0
+- **Language**: Rust (WASM for Zed extension)
+- **Platform**: Gitea (self-hosted)
+
+---
+
+## Synchronization Rules (Already in .cursorrules)
+
+When `blueprint.md` is modified:
+1. ✅ Update `changelog.md` with today's date and description
+2. ✅ Sync `tasks.md` with blueprint deliverables
+3. ✅ Review `decisions.md` for new ADRs needed
+4. ✅ Verify consistency across all documents
+
+---
+
+## Files to Create
+
+### Phase 0 (Foundation)
+```
+tendril/phases/phase-00-foundation/
+├── blueprint.md      # Phase 0 specification
+├── tasks.md          # Phase 0 tasks (all complete)
+├── decisions.md       # Phase 0 ADRs
+└── changelog.md      # Phase 0 change history
+```
+
+### Phase 1 (Testing & Validation)
+```
+tendril/phases/phase-01-testing-validation/
+├── blueprint.md      # Phase 1 specification
+├── tasks.md          # Phase 1 tasks (from PROJECT_STATUS.md)
+├── decisions.md      # Phase 1 ADRs (empty initially)
+└── changelog.md      # Phase 1 change history (empty initially)
+```
+
+---
+
+## Review Checklist
+
+Before implementing Phase 1, verify:
+
+- [ ] Templates use `tendril/phases/` (not `pairs/phases/`)
+- [ ] All references say "Gitea" (not "GitHub")
+- [ ] Tasks.md says "mirrors Gitea issues"
+- [ ] Project name is "Tendril" throughout
+- [ ] Repository URL is Gitea instance
+- [ ] Phase 0 content accurately reflects completed work
+- [ ] Phase 1 objectives align with PROJECT_STATUS.md roadmap
+- [ ] All dates are in YYYY-MM-DD format
+- [ ] Status indicators are consistent (✅ Complete, 🔄 In Progress, ⏳ Planned)
+
+---
+
+## Next Steps After Phase 1
+
+Once Phase 1 is complete:
+- Phase 2: KB System Setup
+- Phase 3: Gitea Actions Workflows
+- Phase 4: LLM Usage Guides
+- Phase 5: Documentation Migration
+- Phase 6: Validation and Testing
+
+---
+
+**Location**: `kb/_guides/PROJECT-SETUP-GUIDE/PHASE-1-PLAN.md`  
+**Related**: `kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`, `PROJECT_STATUS.md`
+

kb/_guides/PROJECT-SETUP-GUIDE/README.md

@@ -0,0 +1,63 @@
+# Project Setup Guide
+
+**Purpose**: This directory contains documentation related to project setup, phase plans, 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 Plans and 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`.
+
+- **[PHASE-1-PLAN.md](./PHASE-1-PLAN.md)** - Detailed plan for Phase 1: Phase Documentation System setup. Includes tasks breakdown, customizations for Tendril, and review checklist.
+
+---
+
+## 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 Plans**: Detailed plans for each phase of project setup
+3. **Phase Updates**: Tracking changes and updates made during each phase of project setup
+4. **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 Plans and Updates
+
+When planning or updating phases:
+1. Create phase plans in this directory (e.g., `PHASE-1-PLAN.md`)
+2. Document changes in phase-specific update files (e.g., `PHASE-0-GITEA-UPDATES.md`)
+3. Reference these files when reviewing phase work
+4. 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**: `kb/_guides/PROJECT-SETUP-GUIDE/`  
+**Maintained by**: Tendril Project Maintainers
+

kb/_index.md

@@ -0,0 +1,20 @@
+# KB Index
+
+_Last updated: 2025-11-11_
+
+This index is automatically generated from KB file metadata. It provides searchable access to all KB content organized by category, topic, tag, and phase relevance.
+
+---
+
+## File Listing by Category
+
+---
+
+## Summary
+
+- **Total KB Files**: 0
+- **Unique Topics**: 0
+- **Unique Tags**: 0
+- **Phases Referenced**: 0
+
+_Index generated on 2025-11-11 11:41:41_

kb/_templates/decision.md

@@ -0,0 +1,39 @@
+---
+title: "${TITLE}"
+date: "${DATE}"
+captured_at: "${DATE}"
+author: ["${AUTHOR}"]
+source: { kind: ${SRC_KIND}, ref: "${SRC_REF}" }
+source_type: ${SOURCE_TYPE}
+project: ["tendril"]
+related_projects: ["tendril"]
+topics: [${TOPICS}]
+tags: [decision, ${TAGS}]
+type: decision
+status: active
+phase_relevance: [${PHASE_RELEVANCE}]
+routing_hint: "${ROUTING_HINT}"
+proposed_path: "kb/05_decisions/"
+routing_confidence: 0.90
+related: [${RELATED}]
+summary: "${SUMMARY}"
+key_takeaways: []
+action_candidates: []
+---
+
+## Decision
+
+## Context
+
+## Options Considered
+
+## Rationale
+
+## Consequences
+
+## Key Takeaways
+
+## Action Candidates
+
+## Revisit Date
+

kb/_templates/howto.md

@@ -0,0 +1,39 @@
+---
+title: "${TITLE}"
+date: "${DATE}"
+captured_at: "${DATE}"
+author: ["${AUTHOR}"]
+source: { kind: ${SRC_KIND}, ref: "${SRC_REF}" }
+source_type: ${SOURCE_TYPE}
+project: ["tendril"]
+related_projects: ["tendril"]
+topics: [${TOPICS}]
+tags: [howto, ${TAGS}]
+type: howto
+status: active
+phase_relevance: [${PHASE_RELEVANCE}]
+routing_hint: "${ROUTING_HINT}"
+proposed_path: "kb/07_playbooks/"
+routing_confidence: 0.90
+related: [${RELATED}]
+summary: "${SUMMARY}"
+key_takeaways: []
+action_candidates: []
+---
+
+## Steps
+
+1.
+
+2.
+
+3.
+
+## Verification
+
+## Rollback
+
+## Key Takeaways
+
+## Action Candidates
+

kb/_templates/note.md

@@ -0,0 +1,35 @@
+---
+title: "${TITLE}"
+date: "${DATE}"
+captured_at: "${DATE}"
+author: ["${AUTHOR}"]
+source: { kind: ${SRC_KIND}, ref: "${SRC_REF}" }
+source_type: ${SOURCE_TYPE}
+project: ["tendril"]
+related_projects: ["tendril"]
+topics: [${TOPICS}]
+tags: [${TAGS}]
+type: note
+status: draft
+phase_relevance: [${PHASE_RELEVANCE}]
+routing_hint: "${ROUTING_HINT}"
+proposed_path: "kb/XX_category/"
+routing_confidence: 0.75
+related: [${RELATED}]
+summary: "${SUMMARY}"
+key_takeaways: []
+action_candidates: []
+---
+
+# Context
+
+# Key Points
+
+# Key Takeaways
+
+# Action Candidates
+
+# Actions / Next Steps
+
+# References
+

kb/scripts/generate-index.sh

@@ -0,0 +1,270 @@
+#!/bin/bash
+
+# KB Index Generation Script
+# Generates kb/_index.md with searchable metadata from all KB files
+
+set -e
+
+# Get the script directory and KB root directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+KB_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+INDEX_FILE="$KB_ROOT/_index.md"
+
+echo "Generating KB index..."
+
+# Create temporary files for indexing
+TMP_DIR=$(mktemp -d 2>/dev/null || mktemp -d -t 'kb-index')
+trap "rm -rf '$TMP_DIR'" EXIT
+
+TOPICS_FILE="$TMP_DIR/topics.txt"
+TAGS_FILE="$TMP_DIR/tags.txt"
+PHASES_FILE="$TMP_DIR/phases.txt"
+FILES_FILE="$TMP_DIR/files.txt"
+
+touch "$TOPICS_FILE" "$TAGS_FILE" "$PHASES_FILE" "$FILES_FILE"
+
+# Categories to scan
+CATEGORIES=("01_projects" "02_systems" "03_research" "04_design" "05_decisions" "06_glossary" "07_playbooks" "08_archive")
+
+# Function to extract frontmatter from a file
+extract_frontmatter() {
+    local file="$1"
+    if [[ ! -f "$file" ]]; then
+        return 1
+    fi
+    
+    # Extract content between first --- and second ---
+    awk '/^---$/{if(++count==2)exit} count==1' "$file" 2>/dev/null || echo ""
+}
+
+# Function to extract a YAML field value (simple fields)
+extract_yaml_simple() {
+    local frontmatter="$1"
+    local field="$2"
+    
+    echo "$frontmatter" | grep "^${field}:" | sed "s/^${field}:[[:space:]]*//" | sed 's/^["'\'']//;s/["'\'']$//' | head -1
+}
+
+# Function to extract array values from YAML
+extract_yaml_array() {
+    local frontmatter="$1"
+    local field="$2"
+    
+    # Try to extract array - handle both single-line and multi-line
+    local array_content=$(echo "$frontmatter" | awk -v field="$field:" '
+        BEGIN { in_array=0; found=0 }
+        $0 ~ "^" field {
+            found=1
+            sub("^" field "[[:space:]]*", "")
+            if ($0 ~ /\[.*\]/) {
+                print $0
+                exit
+            }
+            in_array=1
+            next
+        }
+        in_array {
+            if ($0 ~ /^[^[:space:]]/ && $0 !~ /^-/ && $0 !~ /^\[/) {
+                in_array=0
+                exit
+            }
+            if ($0 ~ /^-/ || $0 ~ /^\[/) {
+                print $0
+            }
+        }
+    ')
+    
+    # Extract values from array
+    echo "$array_content" | grep -oE '["'\''][^"'\'']+["'\'']|[^, \[\]]+' | sed 's/^["'\'']//;s/["'\'']$//;s/^[[:space:]]*//;s/[[:space:]]*$//' | grep -v '^$' | grep -v '^\[' | grep -v '^\]'
+}
+
+# Function to process a KB file
+process_kb_file() {
+    local file="$1"
+    local relative_path="${file#$KB_ROOT/}"
+    local category=""
+    
+    # Determine category from path
+    for cat in "${CATEGORIES[@]}"; do
+        if [[ "$relative_path" == "$cat"/* ]]; then
+            category="$cat"
+            break
+        fi
+    done
+    
+    if [[ -z "$category" ]]; then
+        return 0  # Skip files not in known categories
+    fi
+    
+    # Extract frontmatter
+    local frontmatter=$(extract_frontmatter "$file")
+    if [[ -z "$frontmatter" ]]; then
+        echo "Warning: No frontmatter found in $relative_path" >&2
+        return 0
+    fi
+    
+    # Extract metadata
+    local title=$(extract_yaml_simple "$frontmatter" "title")
+    local date=$(extract_yaml_simple "$frontmatter" "date")
+    local type=$(extract_yaml_simple "$frontmatter" "type")
+    local summary=$(extract_yaml_simple "$frontmatter" "summary")
+    
+    # Store file info
+    echo "$category|$relative_path|$title|$date|$type|$summary" >> "$FILES_FILE"
+    
+    # Extract and index topics
+    local topics=$(extract_yaml_array "$frontmatter" "topics")
+    if [[ -n "$topics" ]]; then
+        while IFS= read -r topic; do
+            topic=$(echo "$topic" | xargs)
+            if [[ -n "$topic" ]]; then
+                echo "$topic|$relative_path" >> "$TOPICS_FILE"
+            fi
+        done <<< "$topics"
+    fi
+    
+    # Extract and index tags
+    local tags=$(extract_yaml_array "$frontmatter" "tags")
+    if [[ -n "$tags" ]]; then
+        while IFS= read -r tag; do
+            tag=$(echo "$tag" | xargs)
+            if [[ -n "$tag" ]]; then
+                echo "$tag|$relative_path" >> "$TAGS_FILE"
+            fi
+        done <<< "$tags"
+    fi
+    
+    # Extract and index phase relevance
+    local phases=$(extract_yaml_array "$frontmatter" "phase_relevance")
+    if [[ -n "$phases" ]]; then
+        while IFS= read -r phase; do
+            phase=$(echo "$phase" | xargs)
+            if [[ -n "$phase" ]]; then
+                echo "$phase|$relative_path" >> "$PHASES_FILE"
+            fi
+        done <<< "$phases"
+    fi
+}
+
+# Scan all KB files
+echo "Scanning KB files..."
+
+for category in "${CATEGORIES[@]}"; do
+    category_dir="$KB_ROOT/$category"
+    if [[ ! -d "$category_dir" ]]; then
+        continue
+    fi
+    
+    # Find all .md files in category
+    find "$category_dir" -type f -name "*.md" | while read -r file; do
+        # Skip if in a special subdirectory
+        if [[ "$file" == *"/_guides/"* ]] || \
+           [[ "$file" == *"/_templates/"* ]] || \
+           [[ "$file" == *"/_inbox/"* ]] || \
+           [[ "$file" == *"/_review_queue/"* ]]; then
+            continue
+        fi
+        
+        # Check if filename matches KB pattern
+        filename=$(basename "$file")
+        if [[ "$filename" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}--[a-z0-9-]+--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$ ]]; then
+            process_kb_file "$file"
+        fi
+    done
+done
+
+# Count files
+FILE_COUNT=$(wc -l < "$FILES_FILE" 2>/dev/null || echo "0")
+
+# Generate index file
+echo "Generating index file..."
+
+{
+    cat << EOF
+# KB Index
+
+_Last updated: $(date +%Y-%m-%d)_
+
+This index is automatically generated from KB file metadata. It provides searchable access to all KB content organized by category, topic, tag, and phase relevance.
+
+---
+
+## File Listing by Category
+
+EOF
+
+    # Output files by category
+    for category in "${CATEGORIES[@]}"; do
+        category_files=$(grep "^$category|" "$FILES_FILE" 2>/dev/null || true)
+        if [[ -n "$category_files" ]]; then
+            echo "### $category"
+            echo ""
+            while IFS='|' read -r cat path title date type summary; do
+                echo "- [\`$path\`]($path) - $title ($date, $type)"
+            done <<< "$category_files"
+            echo ""
+        fi
+    done
+    
+    # Topics Index
+    if [[ -s "$TOPICS_FILE" ]]; then
+        echo "## Topics Index"
+        echo ""
+        sort -u "$TOPICS_FILE" | cut -d'|' -f1 | sort -u | while read -r topic; do
+            echo "### $topic"
+            grep "^$topic|" "$TOPICS_FILE" | cut -d'|' -f2 | sort -u | while read -r file; do
+                echo "- [\`$file\`]($file)"
+            done
+            echo ""
+        done
+    fi
+    
+    # Tags Index
+    if [[ -s "$TAGS_FILE" ]]; then
+        echo "## Tags Index"
+        echo ""
+        sort -u "$TAGS_FILE" | cut -d'|' -f1 | sort -u | while read -r tag; do
+            echo "### $tag"
+            grep "^$tag|" "$TAGS_FILE" | cut -d'|' -f2 | sort -u | while read -r file; do
+                echo "- [\`$file\`]($file)"
+            done
+            echo ""
+        done
+    fi
+    
+    # Phase Relevance Index
+    if [[ -s "$PHASES_FILE" ]]; then
+        echo "## Phase Relevance Index"
+        echo ""
+        sort -u "$PHASES_FILE" | cut -d'|' -f1 | sort -u | while read -r phase; do
+            echo "### $phase"
+            grep "^$phase|" "$PHASES_FILE" | cut -d'|' -f2 | sort -u | while read -r file; do
+                echo "- [\`$file\`]($file)"
+            done
+            echo ""
+        done
+    fi
+    
+    # Summary
+    TOPIC_COUNT=$(cut -d'|' -f1 "$TOPICS_FILE" 2>/dev/null | sort -u | wc -l || echo "0")
+    TAG_COUNT=$(cut -d'|' -f1 "$TAGS_FILE" 2>/dev/null | sort -u | wc -l || echo "0")
+    PHASE_COUNT=$(cut -d'|' -f1 "$PHASES_FILE" 2>/dev/null | sort -u | wc -l || echo "0")
+    
+    echo "---"
+    echo ""
+    echo "## Summary"
+    echo ""
+    echo "- **Total KB Files**: $FILE_COUNT"
+    echo "- **Unique Topics**: $TOPIC_COUNT"
+    echo "- **Unique Tags**: $TAG_COUNT"
+    echo "- **Phases Referenced**: $PHASE_COUNT"
+    echo ""
+    echo "_Index generated on $(date +%Y-%m-%d\ %H:%M:%S)_"
+    
+} > "$INDEX_FILE"
+
+echo "Index generated successfully: $INDEX_FILE"
+echo "  - Files indexed: $FILE_COUNT"
+echo "  - Topics: $TOPIC_COUNT"
+echo "  - Tags: $TAG_COUNT"
+echo "  - Phases: $PHASE_COUNT"

tendril/phases/phase-00-foundation/blueprint.md

@@ -0,0 +1,201 @@
+# Project Phase Document: Phase 0 - Foundation & Cursor Rules Setup
+
+**Project:** Tendril  
+**Phase:** Phase 0: Foundation & Cursor Rules Setup  
+**Project Manager:** TBD  
+**Technical Lead:** TBD  
+**Start Date:** 2025-01-27  
+**End Date:** 2025-01-27  
+**Version:** 1.0  
+**Status:** ✅ Complete
+
+---
+
+## 1. Phase Overview
+
+### 1.1. Executive Summary
+
+Phase 0 established the foundational infrastructure for the Tendril project's documentation and automation system. This phase created the Cursor rules system, comprehensive directory structure, agent guidelines, Gitea-specific documentation, and organized all project setup guides. The phase ensures consistent AI agent behavior, automated documentation synchronization, and proper platform-specific guidance for working with Gitea (self-hosted) instead of GitHub.
+
+This foundation enables all future phases to leverage automated synchronization, consistent documentation patterns, and clear guidelines for both human contributors and AI agents working on the project.
+
+### 1.2. Phase Goals & Success Criteria
+
+**Business Goals:**
+- Establish AI-friendly documentation system for consistent agent behavior
+- Create scalable project management structure
+- Enable automated documentation synchronization
+
+**Technical Goals:**
+- Implement comprehensive Cursor rules system
+- Create complete directory structure (phases, KB, workflows, prompts)
+- Set up Gitea-specific documentation and guidelines
+- Organize project setup guides
+
+**Success Metrics (KPIs):**
+- ✅ Cursor rules file created and validated
+- ✅ All directory structures created
+- ✅ Agent guidelines documented
+- ✅ Gitea documentation suite complete
+- ✅ All Phase 0 work committed (commit `0a131a2`)
+
+**Definition of Done:**
+- [x] `.cursorrules` file created with comprehensive rules
+- [x] Directory structure created (tendril/phases/, kb/, .github/, docs/)
+- [x] `docs/AGENT-GUIDELINES.md` created
+- [x] Gitea documentation suite created (`docs/GITEA/`)
+- [x] Project setup guides organized (`kb/_guides/PROJECT-SETUP-GUIDE/`)
+- [x] All changes committed to repository
+
+---
+
+## 2. Scope & Deliverables
+
+### 2.1. In-Scope Items
+- Cursor rules system implementation
+- Directory structure creation
+- Agent guidelines documentation
+- Gitea platform documentation
+- Project setup guide organization
+
+### 2.2. Out-of-Scope Items
+- Actual phase documentation creation (Phase 1)
+- KB system implementation (Phase 2)
+- Gitea Actions workflows (Phase 3)
+- LLM usage guides (Phase 4)
+
+### 2.3. Phase Deliverables
+- [x] `.cursorrules` file with comprehensive rules
+- [x] `docs/AGENT-GUIDELINES.md` - AI agent behavior reference
+- [x] `docs/GITEA/` - Complete Gitea documentation suite (6 files)
+- [x] `kb/_guides/PROJECT-SETUP-GUIDE/` - Project setup guides
+- [x] Complete directory structure for phases, KB, workflows, and prompts
+
+---
+
+## 3. Technical Specifications
+
+### 3.1. System Architecture
+
+The documentation system follows a phase-based structure with synchronized documents:
+- **Phase Documentation**: `tendril/phases/phase-XX-name/` with 4 synchronized files
+- **Knowledge Base**: `kb/` with 8 categories and special directories
+- **Automation**: `.github/workflows/` for Gitea Actions (compatible with GitHub Actions)
+- **Guides**: `kb/_guides/` for project setup and reference materials
+
+### 3.2. Technology Stack
+- **Documentation Format**: Markdown
+- **Automation**: Gitea Actions (YAML workflows)
+- **AI Integration**: Cursor IDE rules system
+- **Version Control**: Git (Gitea)
+
+### 3.3. Coding Standards & Best Practices
+- Conventional commit messages with phase references
+- YYYY-MM-DD date format throughout
+- Consistent status indicators (✅ Complete, 🔄 In Progress, ⏳ Planned)
+- Gitea terminology (not GitHub) with compatibility notes
+
+### 3.4. Data Models & Schemas
+- Phase documents: blueprint.md, tasks.md, decisions.md, changelog.md
+- KB files: `YYYY-MM-DD--slug--type.md` naming pattern
+- Workflow files: Standard Gitea Actions YAML format
+
+---
+
+## 4. Team & Resource Allocation
+
+| **Role** | **Name** | **Responsibilities** |
+| :--- | :--- | :--- |
+| Project Owner | TBD | Project oversight |
+| Technical Lead | TBD | Technical decisions |
+
+### 4.2. Resource Requirements
+- Cursor IDE for development
+- Gitea repository access
+- Markdown editing capabilities
+
+---
+
+## 5. Timeline & Milestones
+
+| **Milestone** | **Target Date** | **Status** |
+| :--- | :--- | :--- |
+| Cursor rules created | 2025-01-27 | ✅ Completed |
+| Directory structure created | 2025-01-27 | ✅ Completed |
+| Agent guidelines created | 2025-01-27 | ✅ Completed |
+| Gitea documentation created | 2025-01-27 | ✅ Completed |
+| Project setup guides organized | 2025-01-27 | ✅ Completed |
+| Phase 0 committed | 2025-01-27 | ✅ Completed |
+
+---
+
+## 6. Risk Management
+
+| **Risk Description** | **Likelihood (1-5)** | **Impact (1-5)** | **Mitigation Strategy** | **Contingency Plan** |
+| :--- | :--- | :--- | :--- | :--- |
+| Documentation drift over time | 3 | 4 | Automated synchronization rules in Cursor | Manual review process |
+| Incorrect platform references | 2 | 3 | Comprehensive Gitea documentation | Review and update process |
+
+---
+
+## 7. Communication & Reporting
+
+### 7.1. Meeting Cadence
+- **Daily:** As needed
+- **Phase Retrospective:** Upon phase completion
+
+### 7.2. Reporting
+- Documentation updates tracked in changelog.md
+- Commit history: `0a131a2`
+
+---
+
+## 8. Quality Assurance & Testing
+
+### 8.1. Testing Strategy
+- ✅ Cursor rules validated (no linter errors)
+- ✅ All directory structures created
+- ✅ Documentation references verified
+- ✅ Gitea terminology consistency checked
+
+### 8.2. Test Environments
+- **Development:** Local repository
+- **Production:** Gitea repository (https://git.parkingmeter.info/Mycelium/tendril)
+
+---
+
+## 9. Opportunities for Improvement & Lessons Learned
+
+### 9.1. Process Improvements
+- Established clear documentation structure early
+- Created comprehensive Gitea documentation to prevent confusion
+- Organized setup guides for easy reference
+
+### 9.2. Technology & Tool Suggestions
+- Cursor rules system provides excellent automation
+- Gitea Actions compatibility simplifies workflow creation
+
+### 9.3. Lessons Learned
+- Platform-specific documentation (Gitea vs GitHub) is critical
+- Comprehensive Cursor rules prevent common mistakes
+- Directory organization improves maintainability
+
+---
+
+## 10. Phase Sign-off
+
+### 10.1. Approval Criteria
+- [x] All deliverables completed
+- [x] Documentation up to date
+- [x] Ready for next phase
+
+### 10.2. Approvers
+- **Project Owner:** TBD
+
+### 10.3. Sign-off Date
+**2025-01-27** — Phase complete and ready for next phase
+
+---
+
+**Next Phase:** [Phase 1 – Phase Documentation System](./../phase-01-testing-validation/blueprint.md)
+

tendril/phases/phase-00-foundation/changelog.md

@@ -0,0 +1,12 @@
+# Phase 0 – Changelog
+
+- **2025-01-27:** Phase 0 completed - Established foundation
+  - Created `.cursorrules` with comprehensive rules for AI agent behavior
+  - Created directory structure (tendril/phases/, kb/, .github/workflows/, docs/PROMPTS/)
+  - Created `docs/AGENT-GUIDELINES.md` for AI agent reference
+  - Created Gitea documentation suite (`docs/GITEA/`) with 6 comprehensive guides
+  - Organized project setup guides into `kb/_guides/PROJECT-SETUP-GUIDE/`
+  - Updated all GitHub references to Gitea with compatibility notes
+  - Added Gitea Platform Context section to `.cursorrules`
+  - Committed all changes (commit `0a131a2`)
+

tendril/phases/phase-00-foundation/decisions.md

@@ -0,0 +1,69 @@
+# Phase 0 – Architectural Decisions (ADRs)
+
+## ADR-000: Use Gitea (Self-Hosted) Instead of GitHub
+
+**Status:** Accepted  
+**Date:** 2025-01-27
+
+**Context:** The Tendril project uses a self-hosted Gitea instance (https://git.parkingmeter.info/Mycelium/tendril) rather than GitHub. All documentation, workflows, and references need to reflect this platform choice.
+
+**Decision:** Use Gitea terminology throughout the project. Note that Gitea Actions is compatible with GitHub Actions format, so workflows use the same YAML format and `.github/` directory structure.
+
+**Consequences:**
+- ✅ Consistent platform terminology
+- ✅ Accurate documentation for self-hosted setup
+- ✅ Clear guidance for LLMs working with Gitea
+- ⚠️ Need to note GitHub Actions compatibility where relevant
+
+---
+
+## ADR-001: Use `tendril/phases/` Directory Structure
+
+**Status:** Accepted  
+**Date:** 2025-01-27
+
+**Context:** Need to establish phase-based project management structure. The template uses `pairs/phases/` but we need to customize for Tendril project.
+
+**Decision:** Use `tendril/phases/` directory structure to match project name and maintain consistency.
+
+**Consequences:**
+- ✅ Matches project naming convention
+- ✅ Clear project-specific structure
+- ✅ Easy to identify Tendril-specific phases
+
+---
+
+## ADR-002: Implement Comprehensive Cursor Rules System
+
+**Status:** Accepted  
+**Date:** 2025-01-27
+
+**Context:** Need consistent AI agent behavior across the project. Cursor IDE supports rules system for automated documentation synchronization and validation.
+
+**Decision:** Implement comprehensive `.cursorrules` file with mandatory synchronization rules for phase documentation, KB system, and workflow maintenance.
+
+**Consequences:**
+- ✅ Automated documentation synchronization
+- ✅ Consistent AI agent behavior
+- ✅ Reduced manual maintenance
+- ⚠️ Requires discipline to follow rules
+
+---
+
+## ADR-003: Create Gitea-Specific Documentation
+
+**Status:** Accepted  
+**Date:** 2025-01-27
+
+**Context:** LLMs and developers need clear guidance on working with Gitea platform, especially since it's similar but not identical to GitHub.
+
+**Decision:** Create comprehensive Gitea documentation suite in `docs/GITEA/` covering basics, actions, workflows, API, and LLM-specific guidelines.
+
+**Consequences:**
+- ✅ Clear platform guidance for all contributors
+- ✅ Prevents confusion between Gitea and GitHub
+- ✅ Documents Gitea Actions compatibility
+- ✅ Provides LLM-specific guidelines
+
+---
+

tendril/phases/phase-00-foundation/tasks.md

@@ -0,0 +1,55 @@
+# Phase 0 – Tasks (Mirror of Gitea Issues)
+
+This document tracks all actionable items for **Phase 0: Foundation & Cursor Rules Setup**, mirroring corresponding Gitea issues and providing a low-friction view for progress tracking.
+
+---
+
+## 🏗️ Foundation Setup
+
+* [x] **P0-001:** Create `.cursorrules` file with comprehensive rules
+* [x] **P0-002:** Create directory structure (tendril/phases/, kb/, .github/, docs/)
+* [x] **P0-003:** Create `docs/AGENT-GUIDELINES.md` for AI agent behavior reference
+* [x] **P0-004:** Create Gitea documentation suite (`docs/GITEA/`)
+* [x] **P0-005:** Organize project setup guides (`kb/_guides/PROJECT-SETUP-GUIDE/`)
+
+---
+
+## 📝 Documentation
+
+* [x] **P0-006:** Create Gitea Basics documentation
+* [x] **P0-007:** Create Gitea Actions Guide
+* [x] **P0-008:** Create Gitea Workflows documentation
+* [x] **P0-009:** Create Gitea API Reference
+* [x] **P0-010:** Create LLM Gitea Guidelines
+* [x] **P0-011:** Update all GitHub references to Gitea
+
+---
+
+## 🔧 Configuration
+
+* [x] **P0-012:** Customize Cursor rules for Tendril project
+* [x] **P0-013:** Add Gitea Platform Context section to `.cursorrules`
+* [x] **P0-014:** Update workflow maintenance rules with Gitea Actions references
+* [x] **P0-015:** Verify all terminology uses "Gitea" (not "GitHub")
+
+---
+
+## ✅ Completion Criteria
+
+To mark Phase 0 as complete:
+
+* [x] All deliverables completed
+* [x] Documentation up to date
+* [x] All changes committed (commit `0a131a2`)
+* [x] Ready for next phase
+
+---
+
+**Linked Documents:**
+
+* Blueprint: [Phase 0 – Foundation & Cursor Rules Setup](./blueprint.md)
+
+---
+
+*Use this list during daily and weekly reviews. Update checkboxes as tasks are completed or issues are closed in Gitea.*
+

tendril/phases/phase-01-testing-validation/blueprint.md

@@ -0,0 +1,208 @@
+# Project Phase Document: Phase 1 - Testing & Validation
+
+**Project:** Tendril  
+**Phase:** Phase 1: Testing & Validation  
+**Project Manager:** TBD  
+**Technical Lead:** TBD  
+**Start Date:** TBD  
+**End Date:** TBD  
+**Version:** 1.0  
+**Status:** ⏳ Planned
+
+---
+
+## 1. Phase Overview
+
+### 1.1. Executive Summary
+
+Phase 1 focuses on comprehensive testing and validation of the Tendril extension across multiple platforms, Gitea versions, and deployment scenarios. This phase ensures the extension works reliably with various Gitea instances, validates binary discovery mechanisms, tests Docker mode across platforms, and verifies error handling and performance characteristics.
+
+This phase is critical for ensuring production readiness and identifying any platform-specific issues or edge cases before wider distribution.
+
+### 1.2. Phase Goals & Success Criteria
+
+**Business Goals:**
+- Ensure extension works with various Gitea instances
+- Validate cross-platform compatibility
+- Verify user experience and error messages
+
+**Technical Goals:**
+- Test with multiple Gitea versions
+- Validate binary discovery on Linux, macOS, Windows
+- Test Docker mode across all platforms
+- Performance testing with large repositories
+- Error message validation and improvement
+
+**Success Metrics (KPIs):**
+- ✅ Test results documented for all platforms
+- ✅ Platform compatibility matrix complete
+- ✅ Error messages validated and improved
+- ✅ Performance benchmarks established
+- ✅ All identified issues resolved
+
+**Definition of Done:**
+- [ ] Testing complete on Linux, macOS, Windows
+- [ ] Tested with multiple Gitea versions
+- [ ] Docker mode validated on all platforms
+- [ ] Error messages reviewed and improved
+- [ ] Performance testing completed
+- [ ] Test results documented
+- [ ] Platform compatibility matrix created
+- [ ] All issues resolved or documented
+
+---
+
+## 2. Scope & Deliverables
+
+### 2.1. In-Scope Items
+- Testing with actual Gitea instances (various versions)
+- Binary discovery testing on multiple systems
+- Docker mode testing on Linux, macOS, Windows
+- Self-hosted Gitea instance testing
+- Error message validation
+- Performance testing with large repositories
+
+### 2.2. Out-of-Scope Items
+- New feature development
+- Major architectural changes
+- KB system implementation (Phase 2)
+- Gitea Actions workflows (Phase 3)
+
+### 2.3. Phase Deliverables
+- [ ] Test results documentation
+- [ ] Platform compatibility matrix
+- [ ] Error message improvements
+- [ ] Performance benchmarks
+- [ ] Testing checklist/playbook
+
+---
+
+## 3. Technical Specifications
+
+### 3.1. System Architecture
+
+Testing will cover:
+- **Binary Mode**: Local binary execution across platforms
+- **Docker Mode**: Containerized execution across platforms
+- **Gitea Versions**: Multiple versions (1.20+, latest)
+- **Repository Sizes**: Small, medium, large repositories
+
+### 3.2. Technology Stack
+- **Testing Platforms**: Linux (x86_64), macOS (Intel & M-series), Windows
+- **Gitea Versions**: 1.20.6, 1.21.11, 1.22.6, 1.23.8, 1.24.7, 1.25.1, latest
+- **Docker**: Latest stable version
+- **Test Repositories**: Various sizes and configurations
+
+### 3.3. Coding Standards & Best Practices
+- Document all test scenarios
+- Record test results systematically
+- Document any platform-specific issues
+- Create reproducible test procedures
+
+### 3.4. Data Models & Schemas
+- Test results format: Platform, Gitea Version, Test Case, Result, Notes
+- Compatibility matrix: Platform × Gitea Version × Feature
+
+---
+
+## 4. Team & Resource Allocation
+
+| **Role** | **Name** | **Responsibilities** |
+| :--- | :--- | :--- |
+| Project Owner | TBD | Test planning oversight |
+| Technical Lead | TBD | Test execution and validation |
+
+### 4.2. Resource Requirements
+- Access to multiple platforms (Linux, macOS, Windows)
+- Multiple Gitea instances for testing
+- Docker installation on test platforms
+- Test repositories of various sizes
+
+---
+
+## 5. Timeline & Milestones
+
+| **Milestone** | **Target Date** | **Status** |
+| :--- | :--- | :--- |
+| Test plan created | TBD | ⏳ Planned |
+| Linux testing complete | TBD | ⏳ Planned |
+| macOS testing complete | TBD | ⏳ Planned |
+| Windows testing complete | TBD | ⏳ Planned |
+| Docker mode testing complete | TBD | ⏳ Planned |
+| Performance testing complete | TBD | ⏳ Planned |
+| Documentation complete | TBD | ⏳ Planned |
+
+---
+
+## 6. Risk Management
+
+| **Risk Description** | **Likelihood (1-5)** | **Impact (1-5)** | **Mitigation Strategy** | **Contingency Plan** |
+| :--- | :--- | :--- | :--- | :--- |
+| Platform-specific issues | 3 | 4 | Comprehensive testing matrix | Document issues and create workarounds |
+| Gitea version incompatibilities | 2 | 3 | Test with multiple versions | Document version requirements |
+| Performance issues with large repos | 2 | 3 | Performance testing early | Optimize or document limitations |
+
+---
+
+## 7. Communication & Reporting
+
+### 7.1. Meeting Cadence
+- **Daily:** As needed during testing
+- **Phase Retrospective:** Upon phase completion
+
+### 7.2. Reporting
+- Test results documented in tasks.md
+- Issues tracked in Gitea issues
+- Progress updated in changelog.md
+
+---
+
+## 8. Quality Assurance & Testing
+
+### 8.1. Testing Strategy
+- [ ] Unit testing for binary discovery
+- [ ] Integration testing with Gitea instances
+- [ ] Cross-platform compatibility testing
+- [ ] Docker mode testing
+- [ ] Error handling validation
+- [ ] Performance benchmarking
+
+### 8.2. Test Environments
+- **Development:** Local test instances
+- **Production:** Self-hosted Gitea instances
+- **Platforms:** Linux, macOS, Windows
+
+---
+
+## 9. Opportunities for Improvement & Lessons Learned
+
+### 9.1. Process Improvements
+- Will be populated as testing progresses
+
+### 9.2. Technology & Tool Suggestions
+- Will be populated as testing progresses
+
+### 9.3. Lessons Learned
+- Will be populated as testing progresses
+
+---
+
+## 10. Phase Sign-off
+
+### 10.1. Approval Criteria
+- [ ] All testing complete
+- [ ] Test results documented
+- [ ] All issues resolved or documented
+- [ ] Ready for next phase
+
+### 10.2. Approvers
+- **Project Owner:** TBD
+
+### 10.3. Sign-off Date
+**TBD** — Phase complete and ready for next phase
+
+---
+
+**Previous Phase:** [Phase 0 – Foundation & Cursor Rules Setup](./../phase-00-foundation/blueprint.md)  
+**Next Phase:** TBD
+

tendril/phases/phase-01-testing-validation/changelog.md

@@ -0,0 +1,6 @@
+# Phase 1 – Changelog
+
+*This changelog will be populated as Phase 1 progresses.*
+
+---
+

tendril/phases/phase-01-testing-validation/decisions.md

@@ -0,0 +1,10 @@
+# Phase 1 – Architectural Decisions (ADRs)
+
+This document will be populated with architectural decisions made during Phase 1: Testing & Validation.
+
+---
+
+*No decisions recorded yet. ADRs will be added as testing progresses and decisions are made.*
+
+---
+

tendril/phases/phase-01-testing-validation/tasks.md

@@ -0,0 +1,71 @@
+# Phase 1 – Tasks (Mirror of Gitea Issues)
+
+This document tracks all actionable items for **Phase 1: Testing & Validation**, mirroring corresponding Gitea issues and providing a low-friction view for progress tracking.
+
+---
+
+## 🧪 Testing & Validation
+
+* [ ] **P1-001:** Test with actual Gitea instances (various versions)
+* [ ] **P1-002:** Test binary discovery on multiple systems
+* [ ] **P1-003:** Test Docker mode on Linux
+* [ ] **P1-004:** Test Docker mode on macOS
+* [ ] **P1-005:** Test Docker mode on Windows
+* [ ] **P1-006:** Test with self-hosted Gitea instances
+* [ ] **P1-007:** Test with different token permissions
+* [ ] **P1-008:** Validate error messages are helpful
+* [ ] **P1-009:** Performance testing with large repositories
+
+---
+
+## 🖥️ Platform Testing
+
+* [ ] **P1-010:** Linux x86_64 testing (in progress - parkingmeter)
+* [ ] **P1-011:** macOS Intel testing
+* [ ] **P1-012:** macOS M-series testing (code ready, needs testing with actual M4 Mac)
+* [ ] **P1-013:** Windows testing (in progress - co-developer testing)
+
+---
+
+## 📊 Test Results & Documentation
+
+* [ ] **P1-014:** Document test results for all platforms
+* [ ] **P1-015:** Create platform compatibility matrix
+* [ ] **P1-016:** Document Gitea version compatibility
+* [ ] **P1-017:** Create performance benchmarks
+* [ ] **P1-018:** Document any platform-specific issues
+
+---
+
+## 🐛 Error Handling & UX
+
+* [ ] **P1-019:** Review and improve error messages
+* [ ] **P1-020:** Add context to error messages
+* [ ] **P1-021:** Validate error messages are helpful
+* [ ] **P1-022:** Test error scenarios (missing binary, wrong token, etc.)
+
+---
+
+## ✅ Completion Criteria
+
+To mark Phase 1 as complete:
+
+* [ ] All testing complete on Linux, macOS, Windows
+* [ ] Tested with multiple Gitea versions
+* [ ] Docker mode validated on all platforms
+* [ ] Error messages reviewed and improved
+* [ ] Performance testing completed
+* [ ] Test results documented
+* [ ] Platform compatibility matrix created
+* [ ] All issues resolved or documented
+
+---
+
+**Linked Documents:**
+
+* Blueprint: [Phase 1 – Testing & Validation](./blueprint.md)
+
+---
+
+*Use this list during daily and weekly reviews. Update checkboxes as tasks are completed or issues are closed in Gitea.*
+