feat(phase-0): establish comprehensive documentation and automation system
Phase 0: Foundation & Cursor Rules Setup - Complete This commit establishes the foundation for a comprehensive documentation and project management system for Tendril, following best practices from the COMPLETE-SYSTEM-REPLICATION-GUIDE.md. ## What Was Created ### 1. Cursor Rules System (.cursorrules) - Comprehensive rules for AI agent behavior in Cursor IDE - Phase documentation synchronization rules (auto-update changelog, tasks, decisions) - KB (Knowledge Base) ingestion and routing rules - Gitea Actions workflow maintenance rules - README maintenance rules - File deletion protection rules - Customized for Tendril project with Gitea platform ### 2. Directory Structure - tendril/phases/ - Phase-based project management structure - kb/ - Knowledge Base system with 8 categories: * 01_projects/tendril/ - Project-specific notes * 02_systems/ - Infrastructure/tooling * 03_research/ - Informal research * 04_design/ - Product specs/UX * 05_decisions/ - Project-level ADRs * 06_glossary/ - Terms/acronyms * 07_playbooks/ - How-to guides * 08_archive/ - Superseded content * Special directories: _guides/, _templates/, _inbox/, _review_queue/, scripts/ - .github/workflows/ - Gitea Actions workflows (compatible with GitHub Actions) - docs/PROMPTS/ - LLM usage guides ### 3. Agent Guidelines (docs/AGENT-GUIDELINES.md) - Comprehensive guide for AI agents working on Tendril - Documents project structure, workflows, and conventions - Mandatory workflows and critical rules - Project-specific context (Rust/WASM, Zed extension) - Links to all documentation systems ### 4. Gitea Documentation (docs/GITEA/) Complete documentation suite for working with Gitea: - README.md - Overview and quick reference - Gitea-Basics.md - Core concepts, features, differences from GitHub - Gitea-Actions-Guide.md - CI/CD guide with compatibility notes - Gitea-Workflows.md - Common workflows and best practices - Gitea-API-Reference.md - API differences and usage - LLM-Gitea-Guidelines.md - LLM-specific guidelines and terminology ### 5. Phase Updates Documentation (docs/PHASE-UPDATES/) - COMPLETE-SYSTEM-REPLICATION-GUIDE.md - Complete replication guide - PHASE-0-GITEA-UPDATES.md - Documents Gitea-specific updates - README.md - Directory overview and navigation ## Why This Was Done 1. **Establish AI-Friendly Documentation System** - Enables consistent AI agent behavior across the project - Provides clear guidelines for documentation maintenance - Ensures automated synchronization of related documents 2. **Platform-Specific Adaptation (Gitea)** - Tendril uses self-hosted Gitea, not GitHub - Gitea Actions is compatible with GitHub Actions but needs proper documentation - Ensures all references use correct terminology (Gitea vs GitHub) 3. **Foundation for Phase-Based Management** - Sets up structure for phase documentation system - Prepares for KB system implementation - Establishes automation workflows foundation 4. **Knowledge Management** - KB system structure ready for capturing project knowledge - Templates and guides prepared for future use - Index generation system prepared ## How It Benefits the Project ### 1. Automated Documentation Synchronization - When phase blueprints are modified, related documents (changelog, tasks, decisions) are automatically checked and updated - Reduces manual synchronization errors - Ensures consistency across all phase documents ### 2. AI Agent Consistency - Cursor rules ensure all AI interactions follow the same patterns - Clear guidelines prevent inconsistent documentation - Automated checks ensure nothing is missed ### 3. Gitea Platform Understanding - Comprehensive Gitea documentation helps LLMs understand the platform - Correct terminology prevents confusion (Gitea vs GitHub) - Workflow compatibility clearly documented ### 4. Scalable Structure - Phase-based system supports long-term project management - KB system ready for knowledge capture and organization - Automation workflows prepared for CI/CD ### 5. Developer Experience - Clear documentation structure makes onboarding easier - Automated workflows reduce manual maintenance - Consistent patterns across all documentation ### 6. Future-Proof Foundation - Structure supports future phases (1-6) - KB system ready for knowledge capture - Automation system ready for workflow implementation ## Technical Details ### Gitea Actions Compatibility - Gitea Actions uses same YAML format as GitHub Actions - Same .github/workflows/ directory structure - Workflows are largely interchangeable - Documentation notes compatibility throughout ### File Organization - All documentation organized in docs/ directory - Phase updates tracked in docs/PHASE-UPDATES/ - Gitea-specific docs in docs/GITEA/ - Agent guidelines in docs/AGENT-GUIDELINES.md ### Cursor Rules Customization - Project name: Tendril - Phase directory: tendril/phases/ - KB project: tendril - Platform: Gitea (self-hosted) ## Next Steps Phase 0 is complete. Ready for: - Phase 1: Phase Documentation System setup - Phase 2: KB System implementation - Phase 3: Gitea Actions workflows - Phase 4: LLM Usage Guides - Phase 5: Documentation migration - Phase 6: Validation and testing ## Files Added - .cursorrules (root) - docs/AGENT-GUIDELINES.md - docs/GITEA/ (6 files) - docs/PHASE-UPDATES/ (3 files) - Directory structures for phases, KB, workflows, and prompts All files validated with no linter errors.
This commit is contained in:
243
docs/GITEA/Gitea-API-Reference.md
Normal file
243
docs/GITEA/Gitea-API-Reference.md
Normal file
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user