diff --git a/README.md b/README.md
index ed000971a7..2f693895d0 100644
--- a/README.md
+++ b/README.md
@@ -1,213 +1,341 @@
-# Gitea
+# GitCaddy
-[](https://github.com/go-gitea/gitea/actions/workflows/release-nightly.yml?query=branch%3Amain "Release Nightly")
-[](https://discord.gg/Gitea "Join the Discord chat at https://discord.gg/Gitea")
-[](https://goreportcard.com/report/code.gitea.io/gitea "Go Report Card")
-[](https://pkg.go.dev/code.gitea.io/gitea "GoDoc")
-[](https://github.com/go-gitea/gitea/releases/latest "GitHub release")
-[](https://www.codetriage.com/go-gitea/gitea "Help Contribute to Open Source")
-[](https://opencollective.com/gitea "Become a backer/sponsor of gitea")
-[](https://opensource.org/licenses/MIT "License: MIT")
-[](https://gitpod.io/#https://github.com/go-gitea/gitea)
-[](https://translate.gitea.com "Crowdin")
+The AI-native Git platform. Self-hosted, fast, and designed for the age of AI-assisted development.
-[繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md)
+## What is GitCaddy?
-## Purpose
+GitCaddy transforms Git hosting into an AI-ready platform. While traditional Git servers treat AI tools as an afterthought, GitCaddy is built from the ground up with structured APIs, capability discovery, and intelligent context that AI assistants need to write correct code, generate valid CI/CD workflows, and understand your projects deeply.
-The goal of this project is to make the easiest, fastest, and most
-painless way of setting up a self-hosted Git service.
+**Key differentiators:**
-As Gitea is written in Go, it works across **all** the platforms and
-architectures that are supported by Go, including Linux, macOS, and
-Windows on x86, amd64, ARM and PowerPC architectures.
-This project has been
-[forked](https://blog.gitea.com/welcome-to-gitea/) from
-[Gogs](https://gogs.io) since November of 2016, but a lot has changed.
+- **V2 API** - Modern, AI-optimized endpoints with batch operations, streaming, and structured errors
+- **Runner Capability Discovery** - AI tools query runner capabilities before generating workflows
+- **Action Compatibility Database** - Curated compatibility matrix prevents workflow errors
+- **AI Context APIs** - Rich, structured repository and issue intelligence
+- **Workflow Validation** - Pre-flight checks for CI/CD workflows before commit
-For online demonstrations, you can visit [demo.gitea.com](https://demo.gitea.com).
+## Features
-For accessing free Gitea service (with a limited number of repositories), you can visit [gitea.com](https://gitea.com/user/login).
+### V2 API - Modern, AI-Optimized Interface
-To quickly deploy your own dedicated Gitea instance on Gitea Cloud, you can start a free trial at [cloud.gitea.com](https://cloud.gitea.com).
+A complete API redesign focused on AI tool consumption:
-## Documentation
+| Feature | Description |
+|---------|-------------|
+| **Batch Operations** | Fetch up to 100 files in a single request |
+| **Streaming** | NDJSON streams for progressive processing |
+| **Idempotency** | Built-in support for safe request retries |
+| **Structured Errors** | Machine-readable error codes, not just HTTP status |
+| **Request Tracking** | Every request gets a unique ID for debugging |
+| **Health Checks** | Kubernetes-compatible liveness/readiness probes |
+| **Operation Progress** | Server-Sent Events for long-running operations |
-You can find comprehensive documentation on our official [documentation website](https://docs.gitea.com/).
+```
+GET /api/v2/batch/files # Bulk file retrieval
+POST /api/v2/stream/files # NDJSON streaming
+GET /api/v2/operations/{id} # Operation status
+GET /api/v2/health/ready # Readiness probe
+```
-It includes installation, administration, usage, development, contributing guides, and more to help you get started and explore all features effectively.
+### AI Context APIs - Repository Intelligence
-If you have any suggestions or would like to contribute to it, you can visit the [documentation repository](https://gitea.com/gitea/docs)
+Purpose-built endpoints that give AI tools the context they need:
+
+**Repository Summary** (`/api/v2/ai/repo/summary`)
+```json
+{
+ "name": "my-project",
+ "primary_language": "Go",
+ "project_type": "application",
+ "build_system": "go modules",
+ "test_framework": "go test",
+ "suggested_entry_points": ["cmd/main.go", "internal/app/"],
+ "config_files": ["go.mod", "Makefile", ".gitea/workflows/"],
+ "language_stats": {"Go": 45000, "YAML": 2000}
+}
+```
+
+**Repository Navigation** (`/api/v2/ai/repo/navigation`)
+- Directory tree with depth control
+- Important paths ranked by priority (entry points, tests, docs)
+- File type distribution
+
+**Issue Context** (`/api/v2/ai/issue/context`)
+- Issue details with all comments
+- Related issues and code references
+- AI hints: category (bug/feature), complexity estimation, suggested files
+
+### Runner Capability Discovery
+
+Runners report their capabilities. AI tools query before generating workflows.
+
+**Endpoint:** `GET /api/v2/repos/{owner}/{repo}/actions/runners/capabilities`
+
+```json
+{
+ "runners": [
+ {
+ "id": 1,
+ "name": "ubuntu-runner",
+ "status": "online",
+ "labels": ["ubuntu-latest", "docker"],
+ "capabilities": {
+ "os": "linux",
+ "arch": "amd64",
+ "docker": true,
+ "docker_compose": true,
+ "shell": ["bash", "sh"],
+ "tools": {
+ "node": ["18.19.0", "20.10.0"],
+ "go": ["1.21.5", "1.22.0"],
+ "python": ["3.11.6", "3.12.0"]
+ },
+ "features": {
+ "cache": true,
+ "services": true
+ }
+ }
+ }
+ ],
+ "platform": {
+ "type": "gitea",
+ "version": "1.26.0",
+ "supported_actions": {
+ "actions/checkout": {"versions": ["v3", "v4"]},
+ "actions/setup-node": {"versions": ["v3", "v4"]},
+ "actions/upload-artifact": {"versions": ["v3"], "notes": "v4 not supported"}
+ },
+ "unsupported_features": [
+ "GitHub-hosted runners",
+ "OIDC token authentication"
+ ]
+ },
+ "workflow_hints": {
+ "preferred_checkout": "actions/checkout@v4",
+ "artifact_upload_alternative": "Use Gitea API for artifacts"
+ }
+}
+```
+
+### Workflow Validation
+
+Validate workflows before committing. Catch incompatibilities early.
+
+**Endpoint:** `POST /api/v2/repos/{owner}/{repo}/actions/workflows/validate`
+
+```json
+// Request
+{
+ "content": "name: Build\non: push\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/upload-artifact@v4"
+}
+
+// Response
+{
+ "valid": false,
+ "warnings": [
+ {
+ "line": 8,
+ "action": "actions/upload-artifact@v4",
+ "severity": "error",
+ "message": "actions/upload-artifact@v4 is not supported",
+ "suggestion": "Use actions/upload-artifact@v3"
+ }
+ ],
+ "runner_match": [
+ {
+ "job": "build",
+ "runs_on": ["ubuntu-latest"],
+ "matched_runners": ["ubuntu-runner-1"],
+ "capabilities_met": true
+ }
+ ]
+}
+```
+
+### Action Compatibility Database
+
+Built-in knowledge of GitHub Action compatibility:
+
+| Action | Compatible Versions | Notes |
+|--------|-------------------|-------|
+| `actions/checkout` | v2, v3, v4 | Fully compatible |
+| `actions/setup-node` | v2, v3, v4 | Fully compatible |
+| `actions/setup-go` | v3, v4, v5 | Fully compatible |
+| `actions/setup-python` | v4, v5 | Fully compatible |
+| `actions/cache` | v3, v4 | Fully compatible |
+| `actions/upload-artifact` | v2, v3 | v4 not supported |
+| `actions/download-artifact` | v2, v3 | v4 not supported |
+
+### Release Archive
+
+Archive old releases without deleting them:
+
+- Toggle archived status via UI or API
+- Filter releases by archived state
+- Archived releases hidden by default, toggle to show
+- Preserves release history for compliance
+
+```
+POST /api/v1/repos/{owner}/{repo}/releases/{id}/archive
+DELETE /api/v1/repos/{owner}/{repo}/releases/{id}/archive
+GET /api/v1/repos/{owner}/{repo}/releases?archived=false
+```
+
+## Installation
+
+### From Binary
+
+Download from [Releases](https://git.marketally.com/gitcaddy/gitea/releases):
+
+```bash
+# Linux (amd64)
+curl -L -o gitcaddy https://git.marketally.com/gitcaddy/gitea/releases/latest/download/gitea-linux-amd64
+chmod +x gitcaddy
+./gitcaddy web
+```
+
+### From Source
+
+```bash
+git clone https://git.marketally.com/gitcaddy/gitea.git
+cd gitea
+TAGS="bindata sqlite sqlite_unlock_notify" make build
+./gitea web
+```
+
+### Docker
+
+```bash
+docker run -d \
+ --name gitcaddy \
+ -p 3000:3000 \
+ -v ./data:/data \
+ gitcaddy/gitea:latest
+```
+
+## Configuration
+
+GitCaddy uses the same configuration as Gitea. Key settings for AI features:
+
+```ini
+[server]
+ROOT_URL = https://your-instance.com/
+
+[actions]
+ENABLED = true
+
+[api]
+; Enable V2 API (enabled by default)
+ENABLE_V2_API = true
+
+; Max files in batch request
+MAX_BATCH_SIZE = 100
+
+; Enable AI context endpoints
+ENABLE_AI_CONTEXT = true
+```
+
+## GitCaddy Runner
+
+For full capability reporting, use the [GitCaddy act_runner](https://git.marketally.com/gitcaddy/act_runner):
+
+```bash
+# Download
+curl -L -o act_runner https://git.marketally.com/gitcaddy/act_runner/releases/latest/download/act_runner-linux-amd64
+chmod +x act_runner
+
+# Register
+./act_runner register \
+ --instance https://your-instance.com \
+ --token YOUR_TOKEN \
+ --name my-runner
+
+# Run (automatically detects and reports capabilities)
+./act_runner daemon
+```
+
+The runner automatically detects:
+- OS and architecture
+- Docker/Podman availability
+- Installed tools (Node.js, Go, Python, Java, .NET, Rust)
+- Available shells
+- Docker Compose support
+
+## API Documentation
+
+Interactive API documentation available at:
+- `/api/v2/docs` - Scalar API explorer
+- `/api/v2/swagger.json` - OpenAPI specification
+
+## Architecture
+
+```
+ GitCaddy
+ |
+ +------------------------------+------------------------------+
+ | | |
+ V2 API Layer Actions Engine Web Interface
+ | | |
+ +----+----+ +----+----+ +----+----+
+ | | | | | |
+ Batch Streaming Runners Workflows Repos Releases
+ Files (NDJSON) Capability Validation (Archive)
+ | | Discovery |
+ | | | |
+ +----+----+--------------------+---------+
+ |
+ AI Context APIs
+ |
+ +----+----+----+
+ | | | |
+ Repo Issue Nav Summary
+```
+
+## Related Projects
+
+| Project | Description |
+|---------|-------------|
+| [gitcaddy/act_runner](https://git.marketally.com/gitcaddy/act_runner) | Runner with capability detection |
+| [gitcaddy/actions-proto-go](https://git.marketally.com/gitcaddy/actions-proto-go) | Protocol definitions |
## Building
-From the root of the source tree, run:
+Requirements:
+- Go 1.24+ (see `go.mod`)
+- Node.js 22.6+ (for frontend)
+- Make
- TAGS="bindata" make build
+```bash
+# Full build
+TAGS="bindata sqlite sqlite_unlock_notify" make build
-or if SQLite support is required:
+# Backend only
+make backend
- TAGS="bindata sqlite sqlite_unlock_notify" make build
+# Frontend only
+make frontend
-The `build` target is split into two sub-targets:
-
-- `make backend` which requires [Go Stable](https://go.dev/dl/), the required version is defined in [go.mod](/go.mod).
-- `make frontend` which requires [Node.js LTS](https://nodejs.org/en/download/) or greater and [pnpm](https://pnpm.io/installation).
-
-Internet connectivity is required to download the go and npm modules. When building from the official source tarballs which include pre-built frontend files, the `frontend` target will not be triggered, making it possible to build without Node.js.
-
-More info: https://docs.gitea.com/installation/install-from-source
-
-## Using
-
-After building, a binary file named `gitea` will be generated in the root of the source tree by default. To run it, use:
-
- ./gitea web
-
-> [!NOTE]
-> If you're interested in using our APIs, we have experimental support with [documentation](https://docs.gitea.com/api).
+# Run tests
+make test
+```
## Contributing
-Expected workflow is: Fork -> Patch -> Push -> Pull Request
-
-> [!NOTE]
->
-> 1. **YOU MUST READ THE [CONTRIBUTORS GUIDE](CONTRIBUTING.md) BEFORE STARTING TO WORK ON A PULL REQUEST.**
-> 2. If you have found a vulnerability in the project, please write privately to **security@gitea.io**. Thanks!
-
-## Translating
-
-[](https://translate.gitea.com)
-
-Translations are done through [Crowdin](https://translate.gitea.com). If you want to translate to a new language, ask one of the managers in the Crowdin project to add a new language there.
-
-You can also just create an issue for adding a language or ask on Discord on the #translation channel. If you need context or find some translation issues, you can leave a comment on the string or ask on Discord. For general translation questions there is a section in the docs. Currently a bit empty, but we hope to fill it as questions pop up.
-
-Get more information from [documentation](https://docs.gitea.com/contributing/localization).
-
-## Official and Third-Party Projects
-
-We provide an official [go-sdk](https://gitea.com/gitea/go-sdk), a CLI tool called [tea](https://gitea.com/gitea/tea) and an [action runner](https://gitea.com/gitea/act_runner) for Gitea Action.
-
-We maintain a list of Gitea-related projects at [gitea/awesome-gitea](https://gitea.com/gitea/awesome-gitea), where you can discover more third-party projects, including SDKs, plugins, themes, and more.
-
-## Communication
-
-[](https://discord.gg/Gitea "Join the Discord chat at https://discord.gg/Gitea")
-
-If you have questions that are not covered by the [documentation](https://docs.gitea.com/), you can get in contact with us on our [Discord server](https://discord.gg/Gitea) or create a post in the [discourse forum](https://forum.gitea.com/).
-
-## Authors
-
-- [Maintainers](https://github.com/orgs/go-gitea/people)
-- [Contributors](https://github.com/go-gitea/gitea/graphs/contributors)
-- [Translators](options/locale/TRANSLATORS)
-
-## Backers
-
-Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/gitea#backer)]
-
-
-
-## Sponsors
-
-Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/gitea#sponsor)]
-
-
-
-
-
-
-
-
-
-
-
-
-## FAQ
-
-**How do you pronounce Gitea?**
-
-Gitea is pronounced [/ɡɪ’ti:/](https://youtu.be/EM71-2uDAoY) as in "gi-tea" with a hard g.
-
-**Why is this not hosted on a Gitea instance?**
-
-We're [working on it](https://github.com/go-gitea/gitea/issues/1029).
-
-**Where can I find the security patches?**
-
-In the [release log](https://github.com/go-gitea/gitea/releases) or the [change log](https://github.com/go-gitea/gitea/blob/main/CHANGELOG.md), search for the keyword `SECURITY` to find the security patches.
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `make test`
+5. Submit a pull request
## License
-This project is licensed under the MIT License.
-See the [LICENSE](https://github.com/go-gitea/gitea/blob/main/LICENSE) file
-for the full license text.
+MIT License - see [LICENSE](LICENSE) for details.
-## Further information
+---
-
-Looking for an overview of the interface? Check it out!
+## Acknowledgments
-### Login/Register Page
+GitCaddy is a fork of [Gitea](https://gitea.io), the open-source self-hosted Git service. We thank the Gitea team and all contributors for building the foundation that makes GitCaddy possible.
-
-
-
-### User Dashboard
-
-
-
-
-
-
-### User Profile
-
-
-
-### Explore
-
-
-
-
-
-### Repository
-
-
-
-
-
-
-
-
-
-#### Repository Issue
-
-
-
-
-#### Repository Pull Requests
-
-
-
-
-
-
-#### Repository Actions
-
-
-
-
-#### Repository Activity
-
-
-
-
-
-
-### Organization
-
-
-
-
+- [Gitea Project](https://gitea.io)
+- [Gitea Contributors](https://github.com/go-gitea/gitea/graphs/contributors)