diff --git a/plans/2026-08-09-gitea-support.md b/plans/2026-08-09-gitea-support.md
new file mode 100644
index 0000000..3cddbff
--- /dev/null
+++ b/plans/2026-08-09-gitea-support.md
@@ -0,0 +1,2193 @@
+# Gitea Support Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add per-project support for Gitea repositories (in addition to GitHub) to the Projects Portfolio WordPress plugin, behind a `Repository_Provider` interface that preserves all existing GitHub behavior bit-for-bit.
+
+**Architecture:** Introduce a `Repository_Provider` interface with two adapters (`GitHub_Provider`, `Gitea_Provider`) and a `projects_portfolio_get_provider( $post_id )` factory. Adapters normalize to a GitHub-shaped data structure so templates and the REST API don't branch on provider. Existing GitHub code is repackaged into the GitHub adapter; new Gitea logic parallels it. Legacy `_projects_portfolio_github_url` meta is read with a lazy migration path so existing installs don't lose data.
+
+**Tech Stack:** PHP 7.4+ (WordPress), WordPress HTTP API (`wp_remote_get`), WordPress transients for caching, WP test suite + PHPUnit, Brain\Monkey for HTTP mocking.
+
+## Global Constraints
+
+- Text domain: `projects-wp`. All user-facing strings run through `esc_html__` / `esc_attr__` / `__` etc.
+- New post meta keys: `_projects_portfolio_provider` (`'github'`|`'gitea'`), `_projects_portfolio_repo_url`, `_projects_portfolio_gitea_base_url`. Legacy `_projects_portfolio_github_url` is read-only after this change.
+- New options: `projects_portfolio_default_gitea_base_url` (default `https://codeberg.org`), `projects_portfolio_gitea_api_token` (default `''`).
+- All `error_log()` calls in new code must use the prefix `Projects Portfolio:` so debug-log entries are grep-able.
+- Adapter code must **never** call `die()`. Return `null` on failure. (Legacy wrappers retain existing `die()` behavior.)
+- Repo data must conform to the normalized shape: `['owner' => ['avatar_url','login','html_url'], 'updated_at','language','license' => ['name'], 'stargazers_count','forks_count','open_issues_count']`.
+- Cache key pattern: `projects_portfolio_provider_data_{md5( $api_url )}` and `projects_portfolio_provider_release_{md5( $api_url )}`, lifetime `HOUR_IN_SECONDS`.
+- GitHub adapter preserves current behavior bit-for-bit (same URL rewrites, same headers, same fallbacks).
+- Gitea release endpoint returns an **array**; adapter takes element `[0]`.
+- Lazy migration: on save, if provider is unset, repo_url empty, and legacy `_projects_portfolio_github_url` is non-empty, copy legacy → `_projects_portfolio_repo_url` and set provider to `github`.
+- Version bump: plugin header `Version: 1.0.0` → `1.1.0` and `define( 'PROJECTS_PORTFOLIO_VERSION', time() );` → `define( 'PROJECTS_PORTFOLIO_VERSION', '1.1.0' );`.
+- Provider interface lives in `includes/providers/`. Adapter files use `class-*.php` and are loaded via `require_once`.
+
+## File Structure
+
+**Created:**
+- `includes/providers/interface-repository-provider.php` — `Repository_Provider` interface.
+- `includes/providers/class-github-provider.php` — GitHub adapter (repackaged from `helper-functions.php`).
+- `includes/providers/class-gitea-provider.php` — Gitea adapter.
+- `includes/providers/class-provider-factory.php` — `projects_portfolio_get_provider()`.
+- `tests/bootstrap.php` — loads WP test suite and the plugin.
+- `tests/test-github-provider.php`, `tests/test-gitea-provider.php`, `tests/test-provider-factory.php`, `tests/test-metabox.php`, `tests/test-settings.php`.
+- `composer.json` — dev-only PHPUnit + Brain\Monkey.
+- `phpunit.xml.dist` — PHPUnit config.
+- `.gitignore` test entries (no — keep one project .gitignore, dev-only paths covered there if needed).
+
+**Modified:**
+- `includes/helper-functions.php` — adds new provider-aware wrappers; existing GitHub wrappers retained with deprecation PHPDoc.
+- `admin/metabox.php` — replaces single-field "GitHub URL" with provider dropdown + repo URL + optional Gitea base URL.
+- `admin/admin-settings.php` — adds "Gitea Settings" section.
+- `templates/single-projects.php` — routes data fetches through the provider.
+- `admin/rest-api.php` — uses provider-aware wrappers in REST response.
+- `projects-portfolio.php` — `handle_download_redirect` uses provider; version bumped to 1.1.0.
+- `README.md` — documents new metabox fields, Gitea settings, "Connecting to a Gitea repo" subsection.
+
+---
+
+## Task 1: Scaffold providers directory, interface, and tests directory
+
+**Files:**
+- Create: `includes/providers/interface-repository-provider.php`
+- Create: `tests/bootstrap.php`
+- Create: `composer.json`
+- Create: `phpunit.xml.dist`
+- Modify: `.gitignore` (add `vendor/`, `phpunit.xml`)
+
+**Interfaces:**
+- Produces: `interface Repository_Provider` with methods `get_id(): string`, `get_label(): string`, `get_repo_data(): ?array`, `get_release_url(): ?string`, `get_latest_version(): string`, `get_repo_browse_url(): string`, `get_owner_data( string $owner_login ): ?array`. No consuming tasks yet.
+
+- [ ] **Step 1: Add dev paths to `.gitignore`**
+
+Append to `.gitignore` (after the existing lines):
+```
+vendor/
+phpunit.xml
+.phpunit.result.cache
+```
+
+- [ ] **Step 2: Create `composer.json`**
+
+```json
+{
+    "name": "keithsolomon/projects-portfolio",
+    "description": "WordPress plugin — dev-only test dependencies.",
+    "type": "wordpress-plugin",
+    "require": {
+        "php": ">=7.4"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.6",
+        "brain/monkey": "^2.6",
+        "yoast/phpunit-polyfills": "^2.0"
+    },
+    "config": {
+        "allow-plugins": {
+            "php-http/discovery": false
+        }
+    }
+}
+```
+
+- [ ] **Step 3: Create `phpunit.xml.dist`**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit
+    bootstrap="tests/bootstrap.php"
+    colors="true"
+    convertErrorsToExceptions="true"
+    convertNoticesToExceptions="true"
+    convertWarningsToExceptions="true">
+    <testsuites>
+        <testsuite name="projects-portfolio">
+            <directory suffix=".php">tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>
+```
+
+- [ ] **Step 4: Create `includes/providers/interface-repository-provider.php`**
+
+```php
+<?php
+// If this file is called directly, abort.
+if ( ! defined( 'WPINC' ) ) {
+    die;
+}
+
+/**
+ * Contract for a repository host adapter (GitHub, Gitea, ...).
+ *
+ * @since 1.1.0
+ */
+interface Repository_Provider {
+    public function get_id(): string;
+
+    public function get_label(): string;
+
+    /**
+     * Normalized repo metadata. Returns null on any failure.
+     *
+     * Shape:
+     *   [
+     *     'owner' => [ 'avatar_url' => string, 'login' => string, 'html_url' => string ],
+     *     'updated_at'         => string (ISO 8601),
+     *     'language'           => string,
+     *     'license'            => [ 'name' => string ],
+     *     'stargazers_count'   => int,
+     *     'forks_count'        => int,
+     *     'open_issues_count'  => int,
+     *   ]
+     */
+    public function get_repo_data(): ?array;
+
+    /** Direct URL to the latest release zip asset, or null. */
+    public function get_release_url(): ?string;
+
+    /** Tag name of the latest release, or 'Unknown'. */
+    public function get_latest_version(): string;
+
+    /** Public URL of the repo, for the 'View Repo' button. */
+    public function get_repo_browse_url(): string;
+
+    /**
+     * Owner profile data: [ 'avatar_url', 'login', 'html_url' ].
+     * Returns null on failure.
+     */
+    public function get_owner_data( string $owner_login ): ?array;
+}
+```
+
+- [ ] **Step 5: Create `tests/bootstrap.php`**
+
+```php
+<?php
+// Load Composer dev autoload (PHPUnit + Brain\Monkey + polyfills).
+$autoload = dirname( __DIR__ ) . '/vendor/autoload.php';
+if ( ! file_exists( $autoload ) ) {
+    fwrite( STDERR, "Run `composer install` before running tests.\n" );
+    exit( 1 );
+}
+require_once $autoload;
+
+// Brain\Monkey sets up minimal function stubs (apply_filters, plugin_dir_path, etc.).
+\Brain\Monkey\setUp();
+
+// Define WP constants the helpers rely on.
+if ( ! defined( 'HOUR_IN_SECONDS' ) ) {
+    define( 'HOUR_IN_SECONDS', 3600 );
+}
+if ( ! defined( 'WPINC' ) ) {
+    define( 'WPINC', 'wp-includes' );
+}
+if ( ! defined( 'ABSPATH' ) ) {
+    define( 'ABSPATH', __DIR__ . '/' );
+}
+
+// Provide minimal WordPress function stubs used by the providers under test.
+if ( ! function_exists( 'get_option' ) ) {
+    function get_option( $key, $default = false ) { return $default; }
+}
+if ( ! function_exists( 'get_transient' ) ) {
+    function get_transient( $key ) { return false; }
+}
+if ( ! function_exists( 'set_transient' ) ) {
+    function set_transient( $key, $value, $expiration ) { return true; }
+}
+if ( ! function_exists( 'delete_transient' ) ) {
+    function delete_transient( $key ) { return true; }
+}
+if ( ! function_exists( 'wp_remote_get' ) ) {
+    function wp_remote_get( $url, $args = [] ) { return new \WP_Error( 'no_http', 'no http' ); }
+}
+if ( ! function_exists( 'is_wp_error' ) ) {
+    function is_wp_error( $thing ) { return $thing instanceof \WP_Error; }
+}
+if ( ! function_exists( 'wp_remote_retrieve_response_code' ) ) {
+    function wp_remote_retrieve_response_code( $response ) {
+        if ( $response instanceof \WP_Error ) { return 0; }
+        return $response['response']['code'] ?? 0;
+    }
+}
+if ( ! function_exists( 'wp_remote_retrieve_body' ) ) {
+    function wp_remote_retrieve_body( $response ) {
+        if ( $response instanceof \WP_Error ) { return ''; }
+        return $response['body'] ?? '';
+    }
+}
+if ( ! function_exists( 'wp_remote_retrieve_header' ) ) {
+    function wp_remote_retrieve_header( $response, $header ) {
+        if ( $response instanceof \WP_Error ) { return ''; }
+        $headers = $response['headers'] ?? [];
+        $key = strtolower( $header );
+        return $headers[ $key ] ?? '';
+    }
+}
+if ( ! function_exists( 'error_log' ) ) {
+    function error_log( $message ) { /* swallow during tests */ }
+}
+
+// Minimal WP_Error stub if Brain\Monkey doesn't supply one.
+if ( ! class_exists( 'WP_Error' ) ) {
+    class WP_Error {
+        private $code;
+        private $message;
+        public function __construct( $code = '', $message = '' ) {
+            $this->code = $code;
+            $this->message = $message;
+        }
+        public function get_error_code() { return $this->code; }
+        public function get_error_message() { return $this->message; }
+    }
+}
+
+register_shutdown_function( function () {
+    \Brain\Monkey\tearDown();
+} );
+```
+
+- [ ] **Step 6: Run `composer install` to confirm autoload works**
+
+Run: `composer install --no-interaction --no-progress`
+Expected: installs `phpunit/phpunit`, `brain/monkey`, `yoast/phpunit-polyfills`. No errors.
+
+- [ ] **Step 7: Run the test suite with no tests**
+
+Run: `vendor/bin/phpunit`
+Expected: PASS with `OK (0 tests, 0 assertions)`.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add .gitignore composer.json phpunit.xml.dist includes/providers/interface-repository-provider.php tests/bootstrap.php
+git commit -m "Scaffold provider interface and test bootstrap"
+```
+
+---
+
+## Task 2: Build the GitHub provider adapter (repackaged from current code)
+
+**Files:**
+- Create: `includes/providers/class-github-provider.php`
+- Create: `tests/test-github-provider.php`
+
+**Interfaces:**
+- Consumes: `Repository_Provider` interface from Task 1.
+- Produces: `class GitHub_Provider implements Repository_Provider` with constructor `( string $repo_url, string $api_token )`. Used by factory in Task 4.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test-github-provider.php`:
+
+```php
+<?php
+/**
+ * @covers \GitHub_Provider
+ */
+class GitHub_Provider_Test extends \PHPUnit\Framework\TestCase {
+
+    protected function setUp(): void {
+        \Brain\Monkey\setUp();
+    }
+
+    protected function tearDown(): void {
+        \Brain\Monkey\tearDown();
+    }
+
+    private function make( string $token = '' ): GitHub_Provider {
+        return new GitHub_Provider( 'https://github.com/owner/repo', $token );
+    }
+
+    public function test_get_id_and_label(): void {
+        $p = $this->make();
+        $this->assertSame( 'github', $p->get_id() );
+        $this->assertSame( 'GitHub', $p->get_label() );
+    }
+
+    public function test_get_repo_data_normalizes_response(): void {
+        \Brain\Monkey\Functions\expect( 'wp_remote_get' )
+            ->once()
+            ->with( 'https://api.github.com/repos/owner/repo', \Brain\Monkey\Actions\anyArgs() )
+            ->andReturn( [
+                'response' => [ 'code' => 200 ],
+                'headers'  => [],
+                'body'     => json_encode( [
+                    'owner' => [
+                        'avatar_url' => 'https://avatars.example/owner.png',
+                        'login'      => 'owner',
+                        'html_url'   => 'https://github.com/owner',
+                    ],
+                    'updated_at'         => '2026-01-02T03:04:05Z',
+                    'language'           => 'PHP',
+                    'license'            => [ 'name' => 'MIT' ],
+                    'stargazers_count'   => 42,
+                    'forks_count'        => 7,
+                    'open_issues_count'  => 3,
+                ] ),
+            ] );
+
+        $data = $this->make()->get_repo_data();
+
+        $this->assertSame( 'owner', $data['owner']['login'] );
+        $this->assertSame( 42, $data['stargazers_count'] );
+        $this->assertSame( 'MIT', $data['license']['name'] );
+    }
+
+    public function test_release_url_prefers_zip_asset(): void {
+        $release_body = json_encode( [
+            'tag_name' => 'v1.2.3',
+            'assets'   => [
+                [ 'name' => 'project.tar.gz', 'browser_download_url' => 'https://example/x.tar.gz' ],
+                [ 'name' => 'project.zip',    'browser_download_url' => 'https://example/x.zip'    ],
+            ],
+        ] );
+
+        \Brain\Monkey\Functions\expect( 'wp_remote_get' )
+            ->once()
+            ->with( 'https://api.github.com/repos/owner/repo/releases/latest', \Brain\Monkey\Actions\anyArgs() )
+            ->andReturn( [
+                'response' => [ 'code' => 200 ],
+                'headers'  => [],
+                'body'     => $release_body,
+            ] );
+
+        $this->assertSame( 'https://example/x.zip', $this->make()->get_release_url() );
+        $this->assertSame( 'v1.2.3', $this->make()->get_latest_version() );
+    }
+
+    public function test_release_url_falls_back_to_zipball(): void {
+        $release_body = json_encode( [
+            'tag_name'   => 'v0.0.1',
+            'zipball_url' => 'https://api.github.com/repos/owner/repo/zipball/v0.0.1',
+            'assets'     => [],
+        ] );
+
+        \Brain\Monkey\Functions\expect( 'wp_remote_get' )
+            ->once()
+            ->andReturn( [
+                'response' => [ 'code' => 200 ],
+                'headers'  => [],
+                'body'     => $release_body,
+            ] );
+
+        $this->assertSame(
+            'https://api.github.com/repos/owner/repo/zipball/v0.0.1',
+            $this->make()->get_release_url()
+        );
+    }
+
+    public function test_repo_browse_url_returns_input(): void {
+        $this->assertSame(
+            'https://github.com/owner/repo',
+            $this->make()->get_repo_browse_url()
+        );
+    }
+
+    public function test_http_failure_returns_null(): void {
+        \Brain\Monkey\Functions\expect( 'wp_remote_get' )
+            ->once()
+            ->andReturn( new \WP_Error( 'http_error', 'boom' ) );
+
+        $this->assertNull( $this->make()->get_repo_data() );
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to confirm they fail**
+
+Run: `vendor/bin/phpunit --filter GitHub_Provider_Test`
+Expected: FAIL — `class GitHub_Provider not found`.
+
+- [ ] **Step 3: Implement `includes/providers/class-github-provider.php`**
+
+```php
+<?php
+// If this file is called directly, abort.
+if ( ! defined( 'WPINC' ) ) {
+    die;
+}
+
+/**
+ * GitHub adapter for the Repository_Provider interface.
+ *
+ * Preserves the GitHub URL/header/asset behavior from the original
+ * helper-functions.php verbatim.
+ *
+ * @since 1.1.0
+ */
+class GitHub_Provider implements Repository_Provider {
+
+    private string $repo_url;
+    private string $api_token;
+
+    public function __construct( string $repo_url, string $api_token = '' ) {
+        $this->repo_url  = rtrim( $repo_url, '/' );
+        $this->api_token = $api_token;
+    }
+
+    public function get_id(): string {
+        return 'github';
+    }
+
+    public function get_label(): string {
+        return 'GitHub';
+    }
+
+    public function get_repo_data(): ?array {
+        if ( empty( $this->repo_url ) ) {
+            error_log( 'Projects Portfolio: GitHub URL is empty.' );
+            return null;
+        }
+
+        $api_url = str_replace( 'https://github.com/', 'https://api.github.com/repos/', $this->repo_url );
+
+        $cache_key   = 'projects_portfolio_provider_data_' . md5( $api_url );
+        $cached_data = get_transient( $cache_key );
+        if ( $cached_data ) {
+            return $cached_data;
+        }
+
+        $headers = [ 'Accept' => 'application/vnd.github.v3+json' ];
+        if ( ! empty( $this->api_token ) ) {
+            $headers['Authorization'] = 'token ' . $this->api_token;
+        } else {
+            error_log( 'Projects Portfolio: GitHub API token is missing. Using unauthenticated requests.' );
+        }
+
+        $response = wp_remote_get( $api_url, [ 'headers' => $headers ] );
+
+        if ( is_wp_error( $response ) ) {
+            error_log( 'Projects Portfolio: GitHub API error: ' . $response->get_error_message() );
+            return null;
+        }
+
+        $code = wp_remote_retrieve_response_code( $response );
+        if ( 403 === $code ) {
+            $remaining = wp_remote_retrieve_header( $response, 'x-ratelimit-remaining' );
+            $reset     = wp_remote_retrieve_header( $response, 'x-ratelimit-reset' );
+            error_log( 'Projects Portfolio: GitHub API 403: Rate limit exceeded. Remaining: ' . $remaining . ' Reset at: ' . date( 'Y-m-d H:i:s', (int) $reset ) );
+            return null;
+        }
+        if ( 200 !== $code ) {
+            error_log( 'Projects Portfolio: GitHub API error: Received status ' . $code );
+            return null;
+        }
+
+        $data = json_decode( wp_remote_retrieve_body( $response ), true );
+        if ( empty( $data ) || ! is_array( $data ) ) {
+            error_log( 'Projects Portfolio: GitHub API error: Invalid data received.' );
+            return null;
+        }
+
+        set_transient( $cache_key, $data, HOUR_IN_SECONDS );
+        return $data;
+    }
+
+    public function get_release_url(): ?string {
+        $api_url = $this->release_api_url();
+        if ( null === $api_url ) {
+            return null;
+        }
+
+        $cache_key = 'projects_portfolio_provider_release_' . md5( $api_url );
+        $cached    = get_transient( $cache_key );
+        if ( $cached ) {
+            return $cached;
+        }
+
+        $headers = [ 'Accept' => 'application/vnd.github.v3+json' ];
+        if ( ! empty( $this->api_token ) ) {
+            $headers['Authorization'] = 'token ' . $this->api_token;
+        }
+
+        $response = wp_remote_get( $api_url, [ 'headers' => $headers ] );
+        if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
+            return null;
+        }
+
+        $data = json_decode( wp_remote_retrieve_body( $response ), true );
+        if ( ! is_array( $data ) ) {
+            return null;
+        }
+
+        if ( ! empty( $data['assets'] ) && is_array( $data['assets'] ) ) {
+            foreach ( $data['assets'] as $asset ) {
+                if ( isset( $asset['name'] ) && 'zip' === pathinfo( $asset['name'], PATHINFO_EXTENSION ) ) {
+                    $url = $asset['browser_download_url'] ?? null;
+                    if ( $url ) {
+                        set_transient( $cache_key, $url, HOUR_IN_SECONDS );
+                        return $url;
+                    }
+                }
+            }
+        }
+
+        $zipball = $data['zipball_url'] ?? null;
+        if ( $zipball ) {
+            set_transient( $cache_key, $zipball, HOUR_IN_SECONDS );
+        }
+        return $zipball;
+    }
+
+    public function get_latest_version(): string {
+        $api_url = $this->release_api_url();
+        if ( null === $api_url ) {
+            return 'Unknown';
+        }
+
+        $cache_key = 'projects_portfolio_provider_release_version_' . md5( $api_url );
+        $cached    = get_transient( $cache_key );
+        if ( $cached ) {
+            return $cached;
+        }
+
+        $response = wp_remote_get( $api_url );
+        if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
+            return 'Unknown';
+        }
+
+        $data = json_decode( wp_remote_retrieve_body( $response ), true );
+        $tag  = is_array( $data ) && isset( $data['tag_name'] ) ? (string) $data['tag_name'] : 'Unknown';
+
+        set_transient( $cache_key, $tag, HOUR_IN_SECONDS );
+        return $tag;
+    }
+
+    public function get_repo_browse_url(): string {
+        return $this->repo_url;
+    }
+
+    public function get_owner_data( string $owner_login ): ?array {
+        if ( empty( $owner_login ) ) {
+            return null;
+        }
+
+        $api_url = 'https://api.github.com/users/' . $owner_login;
+        $ctx = stream_context_create( [
+            'http' => [
+                'method' => 'GET',
+                'header' => "User-Agent: WORDPRESS\r\n",
+            ],
+        ] );
+        $body = @file_get_contents( $api_url, false, $ctx );
+
+        if ( false === $body ) {
+            error_log( 'Projects Portfolio: Error fetching data from GitHub API.' );
+            return null;
+        }
+
+        $data = json_decode( $body, true );
+        if ( JSON_ERROR_NONE !== json_last_error() || ! is_array( $data ) ) {
+            error_log( 'Projects Portfolio: Error decoding JSON data: ' . json_last_error_msg() );
+            return null;
+        }
+
+        return [
+            'avatar_url' => $data['avatar_url'] ?? '',
+            'login'      => $data['login']      ?? $owner_login,
+            'html_url'   => $data['html_url']   ?? ( 'https://github.com/' . $owner_login ),
+        ];
+    }
+
+    private function release_api_url(): ?string {
+        if ( empty( $this->repo_url ) ) {
+            return null;
+        }
+        return str_replace( 'https://github.com/', 'https://api.github.com/repos/', $this->repo_url ) . '/releases/latest';
+    }
+}
+```
+
+- [ ] **Step 4: Run tests and confirm they pass**
+
+Run: `vendor/bin/phpunit --filter GitHub_Provider_Test`
+Expected: PASS — all six tests green.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add includes/providers/class-github-provider.php tests/test-github-provider.php
+git commit -m "Add GitHub provider adapter with full test coverage"
+```
+
+---
+
+## Task 3: Build the Gitea provider adapter
+
+**Files:**
+- Create: `includes/providers/class-gitea-provider.php`
+- Create: `tests/test-gitea-provider.php`
+
+**Interfaces:**
+- Consumes: `Repository_Provider` interface from Task 1, Gitea response shape (different field names — see tests).
+- Produces: `class Gitea_Provider implements Repository_Provider` with constructor `( string $repo_url, string $base_url, string $api_token )`. Used by factory in Task 4.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test-gitea-provider.php`:
+
+```php
+<?php
+/**
+ * @covers \Gitea_Provider
+ */
+class Gitea_Provider_Test extends \PHPUnit\Framework\TestCase {
+
+    protected function setUp(): void {
+        \Brain\Monkey\setUp();
+    }
+
+    protected function tearDown(): void {
+        \Brain\Monkey\tearDown();
+    }
+
+    private function make( string $base = 'https://codeberg.org', string $token = '' ): Gitea_Provider {
+        return new Gitea_Provider( 'https://codeberg.org/owner/repo', $base, $token );
+    }
+
+    public function test_get_id_and_label(): void {
+        $p = $this->make();
+        $this->assertSame( 'gitea', $p->get_id() );
+        $this->assertSame( 'Gitea', $p->get_label() );
+    }
+
+    public function test_repo_data_normalizes_gitea_fields(): void {
+        \Brain\Monkey\Functions\expect( 'wp_remote_get' )
+            ->once()
+            ->with( 'https://codeberg.org/api/v1/repos/owner/repo', \Brain\Monkey\Actions\anyArgs() )
+            ->andReturn( [
+                'response' => [ 'code' => 200 ],
+                'headers'  => [],
+                'body'     => json_encode( [
+                    'owner' => [
+                        'avatar_url' => 'https://codeberg.org/avatars/owner',
+                        'login'      => 'owner',
+                        'html_url'   => 'https://codeberg.org/owner',
+                    ],
+                    'updated_at'        => '2026-02-03T04:05:06Z',
+                    'language'          => 'PHP',
+                    'license'           => [ 'name' => 'MIT' ],
+                    'stars_count'        => 100,
+                    'forks_count'       => 10,
+                    'open_issues_count' => 5,
+                ] ),
+            ] );
+
+        $data = $this->make()->get_repo_data();
+
+        $this->assertSame( 100, $data['stargazers_count'] );
+        $this->assertSame( 10,  $data['forks_count'] );
+        $this->assertSame( 5,   $data['open_issues_count'] );
+        $this->assertSame( 'MIT', $data['license']['name'] );
+        $this->assertSame( 'owner', $data['owner']['login'] );
+    }
+
+    public function test_repo_data_handles_string_license(): void {
+        \Brain\Monkey\Functions\expect( 'wp_remote_get' )
+            ->once()
+            ->andReturn( [
+                'response' => [ 'code' => 200 ],
+                'headers'  => [],
+                'body'     => json_encode( [
+                    'owner'             => [],
+                    'stars_count'       => 0,
+                    'forks_count'       => 0,
+                    'open_issues_count' => 0,
+                    'license'           => 'Apache-2.0',
+                ] ),
+            ] );
+
+        $data = $this->make()->get_repo_data();
+        $this->assertSame( 'Apache-2.0', $data['license']['name'] );
+    }
+
+    public function test_repo_data_handles_null_license(): void {
+        \Brain\Monkey\Functions\expect( 'wp_remote_get' )
+            ->once()
+            ->andReturn( [
+                'response' => [ 'code' => 200 ],
+                'headers'  => [],
+                'body'     => json_encode( [
+                    'owner'             => [],
+                    'stars_count'       => 0,
+                    'forks_count'       => 0,
+                    'open_issues_count' => 0,
+                    'license'           => null,
+                ] ),
+            ] );
+
+        $data = $this->make()->get_repo_data();
+        $this->assertSame( 'None', $data['license']['name'] );
+    }
+
+    public function test_release_url_picks_zip_asset_from_first_release(): void {
+        $body = json_encode( [
+            [
+                'tag_name' => 'v2.0.0',
+                'assets'   => [
+                    [ 'name' => 'source.tar.gz', 'browser_download_url' => 'https://example/x.tar.gz' ],
+                    [ 'name' => 'release.zip',   'browser_download_url' => 'https://example/release.zip' ],
+                ],
+            ],
+        ] );
+
+        \Brain\Monkey\Functions\expect( 'wp_remote_get' )
+            ->once()
+            ->andReturn( [
+                'response' => [ 'code' => 200 ],
+                'headers'  => [],
+                'body'     => $body,
+            ] );
+
+        $this->assertSame( 'https://example/release.zip', $this->make()->get_release_url() );
+        $this->assertSame( 'v2.0.0', $this->make()->get_latest_version() );
+    }
+
+    public function test_release_url_falls_back_to_archive_url(): void {
+        $body = json_encode( [
+            [ 'tag_name' => 'v0.1.0', 'assets' => [] ],
+        ] );
+
+        \Brain\Monkey\Functions\expect( 'wp_remote_get' )
+            ->once()
+            ->andReturn( [
+                'response' => [ 'code' => 200 ],
+                'headers'  => [],
+                'body'     => $body,
+            ] );
+
+        $this->assertSame(
+            'https://codeberg.org/owner/repo/archive/refs/tags/v0.1.0.zip',
+            $this->make()->get_release_url()
+        );
+    }
+
+    public function test_release_url_empty_array_returns_null(): void {
+        \Brain\Monkey\Functions\expect( 'wp_remote_get' )
+            ->once()
+            ->andReturn( [
+                'response' => [ 'code' => 200 ],
+                'headers'  => [],
+                'body'     => '[]',
+            ] );
+
+        $this->assertNull( $this->make()->get_release_url() );
+    }
+
+    public function test_repo_browse_url_is_built_from_base(): void {
+        $this->assertSame(
+            'https://codeberg.org/owner/repo',
+            $this->make()->get_repo_browse_url()
+        );
+    }
+
+    public function test_http_failure_returns_null(): void {
+        \Brain\Monkey\Functions\expect( 'wp_remote_get' )
+            ->once()
+            ->andReturn( new \WP_Error( 'http_error', 'boom' ) );
+
+        $this->assertNull( $this->make()->get_repo_data() );
+    }
+
+    public function test_self_hosted_base_url_is_used(): void {
+        $provider = new Gitea_Provider(
+            'https://git.example.org/owner/repo',
+            'https://git.example.org',
+            ''
+        );
+        $this->assertSame(
+            'https://git.example.org/owner/repo',
+            $provider->get_repo_browse_url()
+        );
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to confirm they fail**
+
+Run: `vendor/bin/phpunit --filter Gitea_Provider_Test`
+Expected: FAIL — `class Gitea_Provider not found`.
+
+- [ ] **Step 3: Implement `includes/providers/class-gitea-provider.php`**
+
+```php
+<?php
+// If this file is called directly, abort.
+if ( ! defined( 'WPINC' ) ) {
+    die;
+}
+
+/**
+ * Gitea adapter for the Repository_Provider interface.
+ *
+ * Endpoint base: {base_url}/api/v1
+ *  - repo:        {base_url}/api/v1/repos/{owner}/{repo}
+ *  - release:     {base_url}/api/v1/repos/{owner}/{repo}/releases/latest (returns array)
+ *  - user:        {base_url}/api/v1/users/{login}
+ *  - archive:     {base_url}/{owner}/{repo}/archive/refs/tags/{tag}.zip
+ *
+ * @since 1.1.0
+ */
+class Gitea_Provider implements Repository_Provider {
+
+    private string $repo_url;
+    private string $base_url;
+    private string $api_token;
+
+    public function __construct( string $repo_url, string $base_url, string $api_token = '' ) {
+        $this->repo_url  = $repo_url;
+        $this->base_url  = rtrim( $base_url, '/' );
+        $this->api_token = $api_token;
+    }
+
+    public function get_id(): string {
+        return 'gitea';
+    }
+
+    public function get_label(): string {
+        return 'Gitea';
+    }
+
+    public function get_repo_data(): ?array {
+        $api_url = $this->base_url . '/api/v1/repos/' . $this->owner_repo_path();
+        if ( empty( $api_url ) ) {
+            error_log( 'Projects Portfolio: Gitea repo URL is empty.' );
+            return null;
+        }
+
+        $cache_key   = 'projects_portfolio_provider_data_' . md5( $api_url );
+        $cached_data = get_transient( $cache_key );
+        if ( $cached_data ) {
+            return $cached_data;
+        }
+
+        $headers = [ 'Accept' => 'application/json' ];
+        if ( ! empty( $this->api_token ) ) {
+            $headers['Authorization'] = 'token ' . $this->api_token;
+        } else {
+            error_log( 'Projects Portfolio: Gitea API token is missing. Using unauthenticated requests.' );
+        }
+
+        $response = wp_remote_get( $api_url, [ 'headers' => $headers ] );
+        if ( is_wp_error( $response ) ) {
+            error_log( 'Projects Portfolio: Gitea API error: ' . $response->get_error_message() );
+            return null;
+        }
+
+        $code = wp_remote_retrieve_response_code( $response );
+        if ( 200 !== $code ) {
+            error_log( 'Projects Portfolio: Gitea API error: Received status ' . $code );
+            return null;
+        }
+
+        $raw = json_decode( wp_remote_retrieve_body( $response ), true );
+        if ( empty( $raw ) || ! is_array( $raw ) ) {
+            error_log( 'Projects Portfolio: Gitea API error: Invalid data received.' );
+            return null;
+        }
+
+        $owner = $raw['owner'] ?? [];
+        $owner_login = $owner['login'] ?? $this->owner_login_from_path();
+
+        $data = [
+            'owner' => [
+                'avatar_url' => $owner['avatar_url'] ?? '',
+                'login'      => $owner_login,
+                'html_url'   => $owner['html_url'] ?? ( $this->base_url . '/' . $owner_login ),
+            ],
+            'updated_at'        => $raw['updated_at']        ?? '',
+            'language'          => $raw['language']          ?? '',
+            'license'           => $this->normalize_license( $raw['license'] ?? null ),
+            'stargazers_count'  => (int) ( $raw['stars_count']        ?? 0 ),
+            'forks_count'       => (int) ( $raw['forks_count']        ?? 0 ),
+            'open_issues_count' => (int) ( $raw['open_issues_count']  ?? 0 ),
+        ];
+
+        set_transient( $cache_key, $data, HOUR_IN_SECONDS );
+        return $data;
+    }
+
+    public function get_release_url(): ?string {
+        $release = $this->fetch_latest_release();
+        if ( null === $release ) {
+            return null;
+        }
+
+        $assets = $release['assets'] ?? [];
+        if ( is_array( $assets ) ) {
+            foreach ( $assets as $asset ) {
+                if ( isset( $asset['name'] ) && 'zip' === pathinfo( $asset['name'], PATHINFO_EXTENSION ) ) {
+                    $url = $asset['browser_download_url'] ?? null;
+                    if ( $url ) {
+                        return $url;
+                    }
+                }
+            }
+        }
+
+        $tag = $release['tag_name'] ?? '';
+        if ( '' === $tag ) {
+            return null;
+        }
+
+        return $this->base_url . '/' . $this->owner_repo_path() . '/archive/refs/tags/' . $tag . '.zip';
+    }
+
+    public function get_latest_version(): string {
+        $release = $this->fetch_latest_release();
+        if ( null === $release ) {
+            return 'Unknown';
+        }
+        return isset( $release['tag_name'] ) ? (string) $release['tag_name'] : 'Unknown';
+    }
+
+    public function get_repo_browse_url(): string {
+        return $this->base_url . '/' . $this->owner_repo_path();
+    }
+
+    public function get_owner_data( string $owner_login ): ?array {
+        if ( empty( $owner_login ) ) {
+            return null;
+        }
+
+        $api_url  = $this->base_url . '/api/v1/users/' . rawurlencode( $owner_login );
+        $response = wp_remote_get( $api_url, [ 'headers' => $this->auth_headers() ] );
+
+        if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
+            return null;
+        }
+
+        $data = json_decode( wp_remote_retrieve_body( $response ), true );
+        if ( ! is_array( $data ) ) {
+            return null;
+        }
+
+        return [
+            'avatar_url' => $data['avatar_url'] ?? '',
+            'login'      => $data['login']      ?? $owner_login,
+            'html_url'   => $data['html_url']   ?? ( $this->base_url . '/' . $owner_login ),
+        ];
+    }
+
+    /**
+     * Returns the first release object or null on failure / empty response.
+     * Gitea's /releases/latest returns an array.
+     */
+    private function fetch_latest_release(): ?array {
+        $api_url = $this->base_url . '/api/v1/repos/' . $this->owner_repo_path() . '/releases/latest';
+        $cache_key = 'projects_portfolio_provider_release_' . md5( $api_url );
+
+        $cached = get_transient( $cache_key );
+        if ( $cached ) {
+            return $cached;
+        }
+
+        $response = wp_remote_get( $api_url, [ 'headers' => $this->auth_headers() ] );
+        if ( is_wp_error( $response ) ) {
+            error_log( 'Projects Portfolio: Gitea API error: ' . $response->get_error_message() );
+            return null;
+        }
+
+        $code = wp_remote_retrieve_response_code( $response );
+        if ( 200 !== $code ) {
+            error_log( 'Projects Portfolio: Gitea releases/latest returned status ' . $code );
+            return null;
+        }
+
+        $body = json_decode( wp_remote_retrieve_body( $response ), true );
+        if ( ! is_array( $body ) || empty( $body ) ) {
+            return null;
+        }
+
+        $release = $body[0];
+        set_transient( $cache_key, $release, HOUR_IN_SECONDS );
+        return $release;
+    }
+
+    private function auth_headers(): array {
+        $headers = [ 'Accept' => 'application/json' ];
+        if ( ! empty( $this->api_token ) ) {
+            $headers['Authorization'] = 'token ' . $this->api_token;
+        }
+        return $headers;
+    }
+
+    private function owner_repo_path(): string {
+        // Strip the base URL prefix if present, return "owner/repo".
+        $path = $this->repo_url;
+        if ( '' !== $this->base_url && 0 === strpos( $path, $this->base_url ) ) {
+            $path = substr( $path, strlen( $this->base_url ) );
+        }
+        $path = ltrim( $path, '/' );
+        // Drop trailing slashes and any "/archive/...", "/releases/...", etc.
+        $path = preg_replace( '#/(archive|releases|tree|blob|issues|pulls|src|commits|wiki)(/.*)?$#', '', $path );
+        return trim( $path, '/' );
+    }
+
+    private function owner_login_from_path(): string {
+        $parts = explode( '/', $this->owner_repo_path() );
+        return $parts[0] ?? '';
+    }
+
+    private function normalize_license( $license ): array {
+        if ( is_array( $license ) ) {
+            $name = $license['name'] ?? '';
+            return [ 'name' => '' !== $name ? $name : 'None' ];
+        }
+        if ( is_string( $license ) && '' !== $license ) {
+            return [ 'name' => $license ];
+        }
+        return [ 'name' => 'None' ];
+    }
+}
+```
+
+- [ ] **Step 4: Run tests and confirm they pass**
+
+Run: `vendor/bin/phpunit --filter Gitea_Provider_Test`
+Expected: PASS — all ten tests green.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add includes/providers/class-gitea-provider.php tests/test-gitea-provider.php
+git commit -m "Add Gitea provider adapter with normalization and tests"
+```
+
+---
+
+## Task 4: Build the provider factory
+
+**Files:**
+- Create: `includes/providers/class-provider-factory.php`
+- Create: `tests/test-provider-factory.php`
+
+**Interfaces:**
+- Consumes: `GitHub_Provider` from Task 2, `Gitea_Provider` from Task 3, post meta keys (see below).
+- Produces: function `projects_portfolio_get_provider( int $post_id ): Repository_Provider`. Used by helper-functions.php (Task 5) and direct calls in single-projects.php / rest-api.php / handle_download_redirect.
+
+Post meta contract:
+- `_projects_portfolio_provider` — `'github'` | `'gitea'`. Defaults to `'github'` when missing.
+- `_projects_portfolio_repo_url` — canonical. Falls back to legacy `_projects_portfolio_github_url`.
+- `_projects_portfolio_gitea_base_url` — optional per-project override.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test-provider-factory.php`:
+
+```php
+<?php
+/**
+ * @covers \projects_portfolio_get_provider
+ */
+class Provider_Factory_Test extends \PHPUnit\Framework\TestCase {
+
+    protected function setUp(): void {
+        \Brain\Monkey\setUp();
+    }
+
+    protected function tearDown(): void {
+        \Brain\Monkey\tearDown();
+    }
+
+    private function stub_meta( array $provider_meta, array $options = [] ): void {
+        \Brain\Monkey\Functions\stubs( [
+            'get_post_meta' => function ( $post_id, $key, $single = false ) use ( $provider_meta ) {
+                return $provider_meta[ $key ] ?? '';
+            },
+            'get_option' => function ( $key, $default = '' ) use ( $options ) {
+                return $options[ $key ] ?? $default;
+            },
+        ] );
+    }
+
+    public function test_defaults_to_github_when_provider_meta_missing(): void {
+        $this->stub_meta( [
+            '_projects_portfolio_github_url' => 'https://github.com/owner/repo',
+        ] );
+
+        $provider = projects_portfolio_get_provider( 42 );
+        $this->assertSame( 'github', $provider->get_id() );
+        $this->assertSame( 'https://github.com/owner/repo', $provider->get_repo_browse_url() );
+    }
+
+    public function test_uses_repo_url_when_provider_explicit(): void {
+        $this->stub_meta( [
+            '_projects_portfolio_provider'  => 'gitea',
+            '_projects_portfolio_repo_url'  => 'https://codeberg.org/owner/repo',
+        ], [
+            'projects_portfolio_default_gitea_base_url' => 'https://codeberg.org',
+            'projects_portfolio_gitea_api_token'        => 'gitea-token',
+        ] );
+
+        $provider = projects_portfolio_get_provider( 7 );
+        $this->assertSame( 'gitea', $provider->get_id() );
+    }
+
+    public function test_per_project_gitea_base_overrides_global(): void {
+        $this->stub_meta( [
+            '_projects_portfolio_provider'         => 'gitea',
+            '_projects_portfolio_repo_url'         => 'https://git.example.org/owner/repo',
+            '_projects_portfolio_gitea_base_url'   => 'https://git.example.org',
+        ], [
+            'projects_portfolio_default_gitea_base_url' => 'https://codeberg.org',
+        ] );
+
+        $provider = projects_portfolio_get_provider( 7 );
+        $this->assertSame( 'https://git.example.org/owner/repo', $provider->get_repo_browse_url() );
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to confirm they fail**
+
+Run: `vendor/bin/phpunit --filter Provider_Factory_Test`
+Expected: FAIL — function `projects_portfolio_get_provider` does not exist.
+
+- [ ] **Step 3: Implement `includes/providers/class-provider-factory.php`**
+
+```php
+<?php
+// If this file is called directly, abort.
+if ( ! defined( 'WPINC' ) ) {
+    die;
+}
+
+/**
+ * Provider factory: selects the right adapter for a project post.
+ *
+ * @since 1.1.0
+ *
+ * @param int $post_id
+ * @return Repository_Provider
+ */
+function projects_portfolio_get_provider( int $post_id ): Repository_Provider {
+    $provider_meta = (string) get_post_meta( $post_id, '_projects_portfolio_provider', true );
+    $provider_id   = '' !== $provider_meta ? $provider_meta : 'github';
+
+    $repo_url = (string) get_post_meta( $post_id, '_projects_portfolio_repo_url', true );
+    if ( '' === $repo_url ) {
+        // Lazy fallback to legacy key.
+        $repo_url = (string) get_post_meta( $post_id, '_projects_portfolio_github_url', true );
+    }
+
+    if ( 'gitea' === $provider_id ) {
+        $base_url = (string) get_post_meta( $post_id, '_projects_portfolio_gitea_base_url', true );
+        if ( '' === $base_url ) {
+            $base_url = (string) get_option( 'projects_portfolio_default_gitea_base_url', 'https://codeberg.org' );
+        }
+        $token = (string) get_option( 'projects_portfolio_gitea_api_token', '' );
+        return new Gitea_Provider( $repo_url, $base_url, $token );
+    }
+
+    $token = (string) get_option( 'projects_portfolio_github_api_token', '' );
+    return new GitHub_Provider( $repo_url, $token );
+}
+```
+
+- [ ] **Step 4: Run tests and confirm they pass**
+
+Run: `vendor/bin/phpunit --filter Provider_Factory_Test`
+Expected: PASS — three tests green.
+
+- [ ] **Step 5: Run full test suite**
+
+Run: `vendor/bin/phpunit`
+Expected: All earlier tests + new factory tests pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add includes/providers/class-provider-factory.php tests/test-provider-factory.php
+git commit -m "Add provider factory with meta + option wiring"
+```
+
+---
+
+## Task 5: Add provider-aware wrappers to helper-functions.php
+
+**Files:**
+- Modify: `includes/helper-functions.php` — add new wrappers at the top of the file (after the existing `projects_portfolio_settings()`); mark legacy wrappers with `_deprecated_function()`.
+
+**Interfaces:**
+- Consumes: `projects_portfolio_get_provider()` from Task 4.
+- Produces: public functions used by `single-projects.php` (Task 9), `rest-api.php` (Task 10), and `projects-portfolio.php` (Task 8).
+
+- [ ] **Step 1: Add new wrappers at the top of `helper-functions.php`**
+
+Insert immediately after the existing `projects_portfolio_settings()` function (i.e. before the `projects_portfolio_github_owner()` function), keeping the existing `if ( ! defined( 'WPINC' ) ) { die; }` guard at the top.
+
+```php
+/**
+ * Fetch normalized repository data for a project.
+ *
+ * @since  1.1.0
+ * @param  int    $post_id
+ * @return array|null
+ */
+function projects_portfolio_get_repo_data( int $post_id ): ?array {
+    return projects_portfolio_get_provider( $post_id )->get_repo_data();
+}
+
+/**
+ * Resolve the latest release ZIP download URL for a project.
+ *
+ * @since  1.1.0
+ * @param  int $post_id
+ * @return string|null
+ */
+function projects_portfolio_get_release_url( int $post_id ): ?string {
+    return projects_portfolio_get_provider( $post_id )->get_release_url();
+}
+
+/**
+ * Fetch the latest tag name for a project.
+ *
+ * @since  1.1.0
+ * @param  int    $post_id
+ * @return string
+ */
+function projects_portfolio_get_version( int $post_id ): string {
+    return projects_portfolio_get_provider( $post_id )->get_latest_version();
+}
+
+/**
+ * Fetch the repo owner profile data for a project.
+ *
+ * @since  1.1.0
+ * @param  int    $post_id
+ * @return array|null
+ */
+function projects_portfolio_get_owner( int $post_id ): ?array {
+    $provider = projects_portfolio_get_provider( $post_id );
+    $repo     = $provider->get_repo_data();
+    $login    = $repo['owner']['login'] ?? '';
+    if ( '' === $login ) {
+        return null;
+    }
+    return $provider->get_owner_data( $login );
+}
+
+/**
+ * Public browse URL for the project's repo.
+ *
+ * @since  1.1.0
+ * @param  int    $post_id
+ * @return string
+ */
+function projects_portfolio_get_repo_browse_url( int $post_id ): string {
+    return projects_portfolio_get_provider( $post_id )->get_repo_browse_url();
+}
+```
+
+- [ ] **Step 2: Add deprecation notices to legacy wrappers**
+
+Wrap each of the four legacy function bodies (`projects_portfolio_get_github_data`, `projects_portfolio_get_github_release_url`, `projects_portfolio_get_version_from_github`, `projects_portfolio_github_owner`) so the first executable statement calls `_deprecated_function()`.
+
+For each function, add this line immediately after the opening `{`:
+
+```php
+_deprecated_function( __FUNCTION__, '1.1.0', 'projects_portfolio_get_repo_data( $post_id )' );
+```
+
+(Use the matching replacement name for `get_release_url` → `projects_portfolio_get_release_url( $post_id )`, `get_version` → `projects_portfolio_get_version( $post_id )`, `get_owner` → `projects_portfolio_get_owner( $post_id )`.)
+
+- [ ] **Step 3: Run the full test suite to confirm no regressions**
+
+Run: `vendor/bin/phpunit`
+Expected: All tests pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add includes/helper-functions.php
+git commit -m "Add provider-aware helpers; mark legacy wrappers deprecated"
+```
+
+---
+
+## Task 6: Update project settings to expose default Gitea base URL + token
+
+**Files:**
+- Modify: `admin/admin-settings.php` — add a new "Gitea Settings" section between General and Templates.
+
+**Interfaces:**
+- Produces: option keys `projects_portfolio_default_gitea_base_url`, `projects_portfolio_gitea_api_token`. Read by the factory (Task 4) and the `projects_portfolio_settings()` aggregator.
+
+- [ ] **Step 1: Add the new section to `projects_portfolio_render_settings_page()`**
+
+Insert directly after the existing "General Settings" `<table>` (before the `<h2>...Templates Settings</h2>` heading):
+
+```php
+<h2><?php esc_html_e( 'Gitea Settings', 'projects-wp' ); ?></h2>
+<table class="form-table">
+    <tr>
+        <th scope="row">
+            <label for="projects_portfolio_default_gitea_base_url"><?php esc_html_e( 'Default Gitea Base URL', 'projects-wp' ); ?></label>
+        </th>
+        <td>
+            <input type="url" id="projects_portfolio_default_gitea_base_url" name="projects_portfolio_default_gitea_base_url" value="<?php echo esc_attr( $default_gitea_base_url ); ?>" class="regular-text" placeholder="https://codeberg.org" />
+            <p class="description"><?php esc_html_e( 'Used when a Gitea project has no per-project base URL override.', 'projects-wp' ); ?></p>
+        </td>
+    </tr>
+    <tr>
+        <th scope="row">
+            <label for="projects_portfolio_gitea_api_token"><?php esc_html_e( 'Gitea API Token', 'projects-wp' ); ?></label>
+        </th>
+        <td>
+            <input type="password" id="projects_portfolio_gitea_api_token" name="projects_portfolio_gitea_api_token" value="<?php echo esc_attr( $gitea_api_token ); ?>" class="regular-text" />
+        </td>
+    </tr>
+</table>
+```
+
+- [ ] **Step 2: Load the option values at the top of the render function**
+
+Replace the existing local variable block in `projects_portfolio_render_settings_page()`:
+
+```php
+$api_token       = get_option( 'projects_portfolio_github_api_token', '' );
+$share_telemetry = get_option( 'projects_portfolio_share_telemetry', '0' );
+```
+
+With:
+
+```php
+$api_token                = get_option( 'projects_portfolio_github_api_token', '' );
+$gitea_api_token          = get_option( 'projects_portfolio_gitea_api_token', '' );
+$default_gitea_base_url   = get_option( 'projects_portfolio_default_gitea_base_url', 'https://codeberg.org' );
+$share_telemetry          = get_option( 'projects_portfolio_share_telemetry', '0' );
+```
+
+- [ ] **Step 3: Persist the new options in `projects_portfolio_save_settings()`**
+
+Add immediately after the existing `update_option( 'projects_portfolio_github_api_token', … )` line:
+
+```php
+update_option( 'projects_portfolio_gitea_api_token', sanitize_text_field( $_POST['projects_portfolio_gitea_api_token'] ?? '' ) );
+update_option( 'projects_portfolio_default_gitea_base_url', esc_url_raw( $_POST['projects_portfolio_default_gitea_base_url'] ?? 'https://codeberg.org' ) );
+```
+
+- [ ] **Step 4: Run the test suite**
+
+Run: `vendor/bin/phpunit`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add admin/admin-settings.php
+git commit -m "Add Gitea base URL + token fields to settings page"
+```
+
+---
+
+## Task 7: Extend settings aggregator + write settings tests
+
+**Files:**
+- Modify: `includes/helper-functions.php` — add the new option keys to `projects_portfolio_settings()`.
+- Create: `tests/test-settings.php` — covers new option reads.
+
+**Interfaces:**
+- Produces: `projects_portfolio_settings()` array now contains `'default_gitea_base_url'` and `'gitea_api_token'` keys.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test-settings.php`:
+
+```php
+<?php
+/**
+ * @covers \projects_portfolio_settings
+ */
+class Settings_Test extends \PHPUnit\Framework\TestCase {
+
+    protected function setUp(): void {
+        \Brain\Monkey\setUp();
+    }
+
+    protected function tearDown(): void {
+        \Brain\Monkey\tearDown();
+    }
+
+    public function test_settings_aggregator_includes_gitea_keys(): void {
+        \Brain\Monkey\Functions\stubs( [
+            'get_option' => function ( $key, $default = '' ) {
+                $values = [
+                    'projects_portfolio_default_gitea_base_url' => 'https://git.example.org',
+                    'projects_portfolio_gitea_api_token'        => 'secret',
+                ];
+                return $values[ $key ] ?? $default;
+            },
+        ] );
+
+        $settings = projects_portfolio_settings();
+        $this->assertSame( 'https://git.example.org', $settings['default_gitea_base_url'] );
+        $this->assertSame( 'secret', $settings['gitea_api_token'] );
+    }
+}
+```
+
+- [ ] **Step 2: Run tests and confirm failure**
+
+Run: `vendor/bin/phpunit --filter Settings_Test`
+Expected: FAIL — settings array missing the new keys.
+
+- [ ] **Step 3: Update `projects_portfolio_settings()` in `helper-functions.php`**
+
+Replace the existing `$settings = [ ... ]` block with the version that adds the two keys at the top level (sibling to `'github_api_token'`):
+
+```php
+$settings = [
+    'github_api_token'        => get_option( 'projects_portfolio_github_api_token', '' ),
+    'gitea_api_token'         => get_option( 'projects_portfolio_gitea_api_token', '' ),
+    'default_gitea_base_url'  => get_option( 'projects_portfolio_default_gitea_base_url', 'https://codeberg.org' ),
+    'share_telemetry'         => get_option( 'projects_portfolio_share_telemetry', '0' ),
+    'templates' => [
+        'version'           => get_option( 'projects_portfolio_templates_version', '0' ),
+        'last_updated'      => get_option( 'projects_portfolio_templates_last_updated', '0' ),
+        'license'           => get_option( 'projects_portfolio_templates_license', '0' ),
+        'language'          => get_option( 'projects_portfolio_templates_language', '0' ),
+        'downloads'         => get_option( 'projects_portfolio_templates_downloads', '0' ),
+        'forks'             => get_option( 'projects_portfolio_templates_forks', '0' ),
+        'stargazers_count'  => get_option( 'projects_portfolio_templates_stargazers_count', '0' ),
+        'open_issues_count' => get_option( 'projects_portfolio_templates_open_issues_count', '0' ),
+        'github_owner'      => get_option( 'projects_portfolio_templates_github_owner', '0' ),
+    ],
+    'archives' => [
+        'archive_title'   => get_option( 'projects_portfolio_archives_archive_title', '0' ),
+        'project_title'   => get_option( 'projects_portfolio_archives_project_title', '0' ),
+        'project_excerpt' => get_option( 'projects_portfolio_archives_project_excerpt', '0' ),
+        'project_buttons' => get_option( 'projects_portfolio_archives_project_buttons', '0' ),
+    ],
+];
+```
+
+- [ ] **Step 4: Run tests and confirm pass**
+
+Run: `vendor/bin/phpunit --filter Settings_Test`
+Expected: PASS.
+
+- [ ] **Step 5: Run the full suite**
+
+Run: `vendor/bin/phpunit`
+Expected: All tests pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add includes/helper-functions.php tests/test-settings.php
+git commit -m "Surface Gitea settings via projects_portfolio_settings() and test"
+```
+
+---
+
+## Task 8: Update the metabox (provider dropdown + repo URL + Gitea base URL)
+
+**Files:**
+- Modify: `admin/metabox.php` — replace single-field GitHub URL metabox with a "Repository" metabox containing provider dropdown, repo URL, optional Gitea base URL.
+- Create: `tests/test-metabox.php`
+
+**Interfaces:**
+- Produces: post meta keys `_projects_portfolio_provider`, `_projects_portfolio_repo_url`, `_projects_portfolio_gitea_base_url` on save. Lazy migration from `_projects_portfolio_github_url`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test-metabox.php`:
+
+```php
+<?php
+/**
+ * @covers \projects_portfolio_save_meta_box
+ */
+class Metabox_Test extends \PHPUnit\Framework\TestCase {
+
+    protected function setUp(): void {
+        \Brain\Monkey\setUp();
+    }
+
+    protected function tearDown(): void {
+        \Brain\Monkey\tearDown();
+    }
+
+    /** @var array<string,string> */
+    private array $saved = [];
+
+    protected function setUpSaveStubs(): void {
+        $this->saved = [];
+        \Brain\Monkey\Functions\stubs( [
+            'update_post_meta' => function ( $post_id, $key, $value ) {
+                $this->saved[ $key ] = $value;
+                return true;
+            },
+            'wp_verify_nonce' => function () { return true; },
+            'wp_nonce_field' => function () { /* noop */ },
+        ] );
+    }
+
+    public function test_save_persists_provider_and_repo_url(): void {
+        $this->setUpSaveStubs();
+        $_POST['projects_portfolio_meta_box_nonce']   = 'nonce';
+        $_POST['projects_portfolio_provider']         = 'gitea';
+        $_POST['projects_portfolio_repo_url']         = 'https://codeberg.org/owner/repo';
+        $_POST['projects_portfolio_gitea_base_url']   = 'https://codeberg.org';
+
+        projects_portfolio_save_meta_box( 42 );
+
+        $this->assertSame( 'gitea', $this->saved['_projects_portfolio_provider'] );
+        $this->assertSame( 'https://codeberg.org/owner/repo', $this->saved['_projects_portfolio_repo_url'] );
+        $this->assertSame( 'https://codeberg.org', $this->saved['_projects_portfolio_gitea_base_url'] );
+    }
+
+    public function test_lazy_migration_from_legacy_url(): void {
+        $existing = [
+            '_projects_portfolio_provider' => '',
+            '_projects_portfolio_repo_url' => '',
+            '_projects_portfolio_github_url' => 'https://github.com/owner/repo',
+        ];
+        \Brain\Monkey\Functions\stubs( [
+            'get_post_meta' => function ( $post_id, $key, $single = false ) use ( &$existing ) {
+                return $existing[ $key ] ?? '';
+            },
+            'update_post_meta' => function ( $post_id, $key, $value ) use ( &$existing ) {
+                $existing[ $key ] = $value;
+                return true;
+            },
+            'wp_verify_nonce' => function () { return true; },
+            'wp_nonce_field' => function () { /* noop */ },
+        ] );
+
+        // No $_POST provider/repo_url. Lazy migration should fire.
+        $_POST['projects_portfolio_meta_box_nonce'] = 'nonce';
+
+        projects_portfolio_save_meta_box( 1 );
+
+        $this->assertSame( 'github', $existing['_projects_portfolio_provider'] );
+        $this->assertSame( 'https://github.com/owner/repo', $existing['_projects_portfolio_repo_url'] );
+    }
+}
+```
+
+- [ ] **Step 2: Run tests and confirm failure**
+
+Run: `vendor/bin/phpunit --filter Metabox_Test`
+Expected: FAIL — tests fail because the legacy implementation doesn't persist new keys.
+
+- [ ] **Step 3: Replace `admin/metabox.php` contents**
+
+Replace the entire file with:
+
+```php
+<?php
+
+// If this file is called directly, abort.
+if ( ! defined( 'WPINC' ) ) {
+    die;
+}
+
+/**
+ * Add Repository meta box (provider-aware).
+ *
+ * @since  1.0.0
+ * @return void
+ */
+function projects_portfolio_add_meta_boxes() {
+    add_meta_box(
+        'projects_portfolio_repo',
+        esc_html__( 'Repository', 'projects-wp' ),
+        'projects_portfolio_render_meta_box',
+        'projects',
+        'side'
+    );
+}
+add_action( 'add_meta_boxes', 'projects_portfolio_add_meta_boxes' );
+
+/**
+ * Render the Repository meta box.
+ *
+ * @param WP_Post $post
+ *
+ * @since  1.0.0
+ * @return void
+ */
+function projects_portfolio_render_meta_box( $post ) {
+    wp_nonce_field( 'projects_portfolio_save_meta_box', 'projects_portfolio_meta_box_nonce' );
+
+    $provider      = get_post_meta( $post->ID, '_projects_portfolio_provider', true );
+    if ( '' === $provider ) {
+        $provider = 'github';
+    }
+    $repo_url      = get_post_meta( $post->ID, '_projects_portfolio_repo_url', true );
+    if ( '' === $repo_url ) {
+        $repo_url = get_post_meta( $post->ID, '_projects_portfolio_github_url', true );
+    }
+    $gitea_base_url = get_post_meta( $post->ID, '_projects_portfolio_gitea_base_url', true );
+    ?>
+    <p>
+        <label for="projects_portfolio_provider"><?php esc_html_e( 'Provider', 'projects-wp' ); ?></label>
+        <select id="projects_portfolio_provider" name="projects_portfolio_provider" style="width: 100%;">
+            <option value="github" <?php selected( $provider, 'github' ); ?>><?php esc_html_e( 'GitHub', 'projects-wp' ); ?></option>
+            <option value="gitea" <?php selected( $provider, 'gitea' ); ?>><?php esc_html_e( 'Gitea', 'projects-wp' ); ?></option>
+        </select>
+    </p>
+    <p>
+        <label for="projects_portfolio_repo_url"><?php esc_html_e( 'Repository URL', 'projects-wp' ); ?></label>
+        <input type="url" id="projects_portfolio_repo_url" name="projects_portfolio_repo_url" value="<?php echo esc_attr( $repo_url ); ?>" style="width: 100%;" placeholder="https://github.com/owner/repo" />
+    </p>
+    <p class="projects-portfolio-gitea-only" <?php echo 'gitea' !== $provider ? 'style="display:none;"' : ''; ?>>
+        <label for="projects_portfolio_gitea_base_url"><?php esc_html_e( 'Gitea Base URL (optional override)', 'projects-wp' ); ?></label>
+        <input type="url" id="projects_portfolio_gitea_base_url" name="projects_portfolio_gitea_base_url" value="<?php echo esc_attr( $gitea_base_url ); ?>" style="width: 100%;" placeholder="https://codeberg.org" />
+        <span class="description"><?php esc_html_e( 'Leave blank to use the default from Settings.', 'projects-wp' ); ?></span>
+    </p>
+    <script>
+    (function(){
+        var sel = document.getElementById('projects_portfolio_provider');
+        if (!sel) return;
+        var gitea = document.querySelector('.projects-portfolio-gitea-only');
+        function toggle(){
+            if (!gitea) return;
+            gitea.style.display = sel.value === 'gitea' ? '' : 'none';
+        }
+        sel.addEventListener('change', toggle);
+        toggle();
+    })();
+    </script>
+    <?php
+}
+
+/**
+ * Save the Repository meta box.
+ *
+ * Performs a lazy migration from legacy `_projects_portfolio_github_url`.
+ *
+ * @param int $post_id
+ *
+ * @since  1.0.0
+ * @return void
+ */
+function projects_portfolio_save_meta_box( $post_id ) {
+    if ( ! isset( $_POST['projects_portfolio_meta_box_nonce'] ) || ! wp_verify_nonce( $_POST['projects_portfolio_meta_box_nonce'], 'projects_portfolio_save_meta_box' ) ) {
+        return;
+    }
+    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
+        return;
+    }
+
+    $existing_provider = get_post_meta( $post_id, '_projects_portfolio_provider', true );
+    $existing_repo_url = get_post_meta( $post_id, '_projects_portfolio_repo_url', true );
+    $legacy_github    = get_post_meta( $post_id, '_projects_portfolio_github_url', true );
+
+    // Lazy migration: legacy URL present, no explicit choice.
+    if ( '' === $existing_provider && '' === $existing_repo_url && '' !== $legacy_github ) {
+        update_post_meta( $post_id, '_projects_portfolio_provider', 'github' );
+        update_post_meta( $post_id, '_projects_portfolio_repo_url', $legacy_github );
+    }
+
+    if ( isset( $_POST['projects_portfolio_provider'] ) ) {
+        $provider = ( 'gitea' === $_POST['projects_portfolio_provider'] ) ? 'gitea' : 'github';
+        update_post_meta( $post_id, '_projects_portfolio_provider', $provider );
+    }
+
+    if ( isset( $_POST['projects_portfolio_repo_url'] ) ) {
+        $repo_url = esc_url_raw( wp_unslash( $_POST['projects_portfolio_repo_url'] ) );
+        update_post_meta( $post_id, '_projects_portfolio_repo_url', $repo_url );
+        // Maintain the legacy key for backward-compat reads (only when this is a GitHub project).
+        $provider_now = get_post_meta( $post_id, '_projects_portfolio_provider', true );
+        if ( 'github' === $provider_now ) {
+            update_post_meta( $post_id, '_projects_portfolio_github_url', $repo_url );
+        }
+    }
+
+    if ( isset( $_POST['projects_portfolio_gitea_base_url'] ) ) {
+        update_post_meta( $post_id, '_projects_portfolio_gitea_base_url', esc_url_raw( wp_unslash( $_POST['projects_portfolio_gitea_base_url'] ) ) );
+    }
+}
+add_action( 'save_post', 'projects_portfolio_save_meta_box' );
+```
+
+- [ ] **Step 4: Run the metabox tests**
+
+Run: `vendor/bin/phpunit --filter Metabox_Test`
+Expected: PASS.
+
+- [ ] **Step 5: Run the full suite**
+
+Run: `vendor/bin/phpunit`
+Expected: All tests pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add admin/metabox.php tests/test-metabox.php
+git commit -m "Add provider dropdown and per-project Gitea base URL to metabox"
+```
+
+---
+
+## Task 9: Update single-projects.php template to use provider
+
+**Files:**
+- Modify: `templates/single-projects.php` — replace GitHub-specific fetches with provider-aware wrappers; rename button to "View Repo"; use new helper names.
+
+**Interfaces:**
+- Consumes: `projects_portfolio_get_repo_data()`, `projects_portfolio_get_version()`, `projects_portfolio_get_owner()`, `projects_portfolio_get_repo_browse_url()` from Task 5.
+
+- [ ] **Step 1: Replace the data-fetch block at the top of `templates/single-projects.php`**
+
+Replace this entire block (the lines from `$settings       = …` through `// Format last updated date.`):
+
+```php
+$settings       = projects_portfolio_settings();
+$project_id     = get_the_ID();
+$download_count = (int) get_post_meta( $project_id, '_projects_portfolio_download_count', true );
+$github_url     = get_post_meta( $project_id, '_projects_portfolio_github_url', true );
+$version        = 'Unknown';
+$github_data    = projects_portfolio_get_github_data( $github_url );
+
+// Extract specific GitHub data.
+$owner_avatar = $github_data['owner']['avatar_url'] ?? '';
+$owner_name   = $github_data['owner']['login'] ?? '';
+$owner_url    = $github_data['owner']['html_url'] ?? '';
+$last_updated = $github_data['updated_at'] ?? '';
+$language     = $github_data['language'] ?? '';
+$license      = $github_data['license']['name'] ?? 'None';
+
+$owner = projects_portfolio_github_owner( $owner_name );
+
+// Fetch the version number from the GitHub API if the URL is set.
+if ( $github_url ) {
+    // Retrieve the GitHub API token from the plugin settings.
+    $github_token = get_option( 'projects_portfolio_github_api_token', '' );
+
+    // Prepare the API URL.
+    $api_url = str_replace( 'https://github.com/', 'https://api.github.com/repos/', rtrim( $github_url, '/' ) ) . '/releases/latest';
+
+    // Check if the response is cached.
+    $transient_key = 'github_api_response_' . md5( $api_url );
+    $response      = get_transient( $transient_key );
+
+    if ( false === $response ) {
+        // Prepare the request arguments.
+        $args = [];
+        if ( ! empty( $github_token ) ) {
+            $args['headers'] = [
+                'Authorization' => 'token ' . $github_token,
+            ];
+        }
+
+        // Make the API request.
+        $response = wp_remote_get( $api_url, $args );
+
+        // Cache the response for 1 hour if the request is successful.
+        if ( ! is_wp_error( $response ) && 200 === wp_remote_retrieve_response_code( $response ) ) {
+            set_transient( $transient_key, $response, HOUR_IN_SECONDS );
+        }
+    }
+
+    // Handle the response.
+    if ( is_wp_error( $response ) ) {
+        error_log( 'GitHub API error: ' . $response->get_error_message() );
+    } else {
+        $response_code = wp_remote_retrieve_response_code( $response );
+        $response_body = wp_remote_retrieve_body( $response );
+        error_log( 'GitHub API response code: ' . $response_code );
+        error_log( 'GitHub API response body: ' . $response_body );
+
+        if ( $response_code === 200 ) {
+            $data = json_decode( $response_body, true );
+
+            // Check if tag_name exists in the response.
+            if ( isset( $data['tag_name'] ) ) {
+                $version = esc_html( $data['tag_name'] );
+            }
+        } else {
+            error_log( "GitHub API error: HTTP $response_code for URL $api_url" );
+        }
+    }
+}
+
+// Format last updated date.
+if ( $last_updated ) {
+    $last_updated = date_i18n( get_option( 'date_format' ), strtotime( $last_updated ) );
+}
+```
+
+With:
+
+```php
+$settings       = projects_portfolio_settings();
+$project_id     = get_the_ID();
+$download_count = (int) get_post_meta( $project_id, '_projects_portfolio_download_count', true );
+
+$repo_url = get_post_meta( $project_id, '_projects_portfolio_repo_url', true );
+if ( '' === $repo_url ) {
+    $repo_url = get_post_meta( $project_id, '_projects_portfolio_github_url', true );
+}
+
+$repo_data = projects_portfolio_get_repo_data( $project_id );
+$version   = projects_portfolio_get_version( $project_id );
+$owner     = projects_portfolio_get_owner( $project_id );
+
+$owner_avatar = $repo_data['owner']['avatar_url'] ?? '';
+$owner_name   = $repo_data['owner']['login']      ?? '';
+$owner_url    = $repo_data['owner']['html_url']    ?? '';
+$last_updated = $repo_data['updated_at']           ?? '';
+$language     = $repo_data['language']             ?? '';
+$license      = $repo_data['license']['name']      ?? 'None';
+$browse_url   = $repo_url ? projects_portfolio_get_repo_browse_url( $project_id ) : '';
+
+if ( $last_updated ) {
+    $last_updated = date_i18n( get_option( 'date_format' ), strtotime( $last_updated ) );
+}
+```
+
+- [ ] **Step 2: Replace references to `$github_data` and `$github_url` in the template body**
+
+- In the meta `<table>` block, replace every `$github_data[…]` with `$repo_data[…]` (e.g. `$github_data['stargazers_count']` → `$repo_data['stargazers_count']`).
+- In the "View on GitHub" anchor, change the label from `<?php esc_html_e( 'View on GitHub', 'projects-wp' ); ?>` to `<?php esc_html_e( 'View Repo', 'projects-wp' ); ?>` and the `href` from `<?php echo esc_url( $github_url ); ?>` to `<?php echo esc_url( $browse_url ); ?>`.
+- In the conditional `<?php if ( $github_url ) : ?>` guard, replace with `<?php if ( $repo_url ) : ?>`.
+- In the "No repository linked" fallback message, change `esc_html__( 'GitHub Repository:', 'projects-wp' )` to `esc_html__( 'Repository:', 'projects-wp' )`.
+
+- [ ] **Step 3: Run the full test suite**
+
+Run: `vendor/bin/phpunit`
+Expected: All tests pass. (The template isn't unit-tested; this step confirms no helper regressions.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add templates/single-projects.php
+git commit -m "Route single-projects template through provider interface"
+```
+
+---
+
+## Task 10: Update REST API response to use provider
+
+**Files:**
+- Modify: `admin/rest-api.php` — replace GitHub-specific calls with provider-aware helpers.
+
+- [ ] **Step 1: Replace the GitHub-specific fetches in `projects_portfolio_get_projects_data()`**
+
+Find and replace:
+
+- `$github_url  = get_post_meta( $project_id, '_projects_portfolio_github_url', true );` →
+  `$repo_url  = get_post_meta( $project_id, '_projects_portfolio_repo_url', true ); if ( '' === $repo_url ) { $repo_url = get_post_meta( $project_id, '_projects_portfolio_github_url', true ); }`
+- `$github_data = projects_portfolio_get_github_data( $github_url );` →
+  `$repo_data = projects_portfolio_get_repo_data( $project_id );`
+- All occurrences of `$github_data[…]` → `$repo_data[…]` in the response array.
+- `'github_url'     => $github_url,` → keep the existing field name `'github_url'` but assign `$repo_url` to it.
+- `'version'        => projects_portfolio_get_version_from_github( $github_url ),` → `'version'        => projects_portfolio_get_version( $project_id ),`.
+
+Keep the response field name `'github_url'` for backward compatibility, but populate it with the canonical `$repo_url` value (which may point at any provider). Add a sibling `'provider' => get_post_meta( $post_id, '_projects_portfolio_provider', true ) ?: 'github'` so consumers can detect the provider without parsing the URL.
+
+This preserves the existing REST response shape (spec §12: "Response shape is unchanged.") while exposing the minimum needed info for consumers to detect Gitea.
+
+- [ ] **Step 2: Update `projects_portfolio_get_popular_projects()`**
+
+Find and replace:
+
+- `'github_url'     => get_post_meta( get_the_ID(), '_projects_portfolio_github_url', true ),` →
+  `'github_url'     => ( $url = get_post_meta( get_the_ID(), '_projects_portfolio_repo_url', true ) ?: get_post_meta( get_the_ID(), '_projects_portfolio_github_url', true ) ),`
+
+- [ ] **Step 3: Run the full suite**
+
+Run: `vendor/bin/phpunit`
+Expected: All tests pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add admin/rest-api.php
+git commit -m "Route REST API responses through provider interface"
+```
+
+---
+
+## Task 11: Update download redirect to use provider
+
+**Files:**
+- Modify: `projects-portfolio.php` — `projects_portfolio_handle_download_redirect()` uses the provider.
+
+- [ ] **Step 1: Replace the redirect logic**
+
+Find and replace:
+
+```php
+function projects_portfolio_handle_download_redirect() {
+    $project_id = get_query_var( 'project_download_id' );
+
+    if ( $project_id ) {
+        $github_url   = get_post_meta( $project_id, '_projects_portfolio_github_url', true );
+        $download_url = projects_portfolio_get_github_release_url( $github_url );
+
+        if ( $download_url ) {
+            // Increment download count.
+            $download_count = (int) get_post_meta( $project_id, '_projects_portfolio_download_count', true );
+            ++$download_count;
+            update_post_meta( $project_id, '_projects_portfolio_download_count', $download_count );
+
+            // Redirect to the GitHub ZIP file.
+            wp_safe_redirect( esc_url_raw( $download_url ) );
+            exit;
+        } else {
+            wp_die(
+                esc_html__( 'Invalid download URL. Please check the GitHub repository.', 'projects-wp' ),
+                esc_html__( 'Download Error', 'projects-wp' ),
+                array( 'response' => 404 )
+            );
+        }
+    }
+}
+```
+
+With:
+
+```php
+function projects_portfolio_handle_download_redirect() {
+    $project_id = get_query_var( 'project_download_id' );
+
+    if ( $project_id ) {
+        $download_url = projects_portfolio_get_release_url( (int) $project_id );
+
+        if ( $download_url ) {
+            // Increment download count.
+            $download_count = (int) get_post_meta( $project_id, '_projects_portfolio_download_count', true );
+            ++$download_count;
+            update_post_meta( $project_id, '_projects_portfolio_download_count', $download_count );
+
+            // Redirect to the release ZIP on the project's host.
+            wp_safe_redirect( esc_url_raw( $download_url ) );
+            exit;
+        } else {
+            wp_die(
+                esc_html__( 'Invalid download URL. Please check the repository URL.', 'projects-wp' ),
+                esc_html__( 'Download Error', 'projects-wp' ),
+                array( 'response' => 404 )
+            );
+        }
+    }
+}
+```
+
+- [ ] **Step 2: Run the test suite**
+
+Run: `vendor/bin/phpunit`
+Expected: All tests pass.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add projects-portfolio.php
+git commit -m "Route download redirect through provider interface"
+```
+
+---
+
+## Task 12: Wire provider includes from the main plugin file + bump version
+
+**Files:**
+- Modify: `projects-portfolio.php` — `require` the new provider files at the top of the "Add the required files" block; bump version constant and plugin header.
+
+- [ ] **Step 1: Add the provider requires**
+
+In `projects-portfolio.php`, replace the existing `require` block:
+
+```php
+// Add the required files.
+require 'admin/admin-settings.php';
+require 'admin/cpt-taxonomy.php';
+require 'admin/metabox.php';
+require 'includes/helper-functions.php';
+```
+
+With:
+
+```php
+// Add the required files.
+require 'admin/admin-settings.php';
+require 'admin/cpt-taxonomy.php';
+require 'admin/metabox.php';
+require 'includes/helper-functions.php';
+require 'includes/providers/interface-repository-provider.php';
+require 'includes/providers/class-github-provider.php';
+require 'includes/providers/class-gitea-provider.php';
+require 'includes/providers/class-provider-factory.php';
+```
+
+- [ ] **Step 2: Bump the version constant**
+
+Replace:
+```php
+define( 'PROJECTS_PORTFOLIO_VERSION', time() );
+```
+With:
+```php
+define( 'PROJECTS_PORTFOLIO_VERSION', '1.1.0' );
+```
+
+- [ ] **Step 3: Bump the plugin header**
+
+In the file header comment, change:
+```
+ * Version:     1.0.0
+```
+to:
+```
+ * Version:     1.1.0
+```
+
+- [ ] **Step 4: Run the full test suite**
+
+Run: `vendor/bin/phpunit`
+Expected: All tests pass.
+
+- [ ] **Step 5: Smoke-test the bootstrap manually**
+
+Run: `php -r "define('WPINC','wp-includes'); require 'includes/providers/interface-repository-provider.php'; require 'includes/providers/class-github-provider.php'; require 'includes/providers/class-gitea-provider.php'; require 'includes/providers/class-provider-factory.php'; echo 'OK'; echo PHP_EOL;"`
+
+Expected output ends with `OK`.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add projects-portfolio.php
+git commit -m "Wire provider includes and bump version to 1.1.0"
+```
+
+---
+
+## Task 13: Update README
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Update the "Add a New Project" usage section**
+
+Find the existing "Add a New Project" subsection in `README.md`. Replace the line:
+```
+4. In the sidebar, paste the GitHub Repository URL (e.g., `https://github.com/username/repo`).
+```
+With:
+```
+4. In the sidebar, choose **Provider** (GitHub or Gitea) and paste the **Repository URL** (e.g., `https://github.com/username/repo` or `https://codeberg.org/username/repo`).
+5. For Gitea projects, optionally set a **Gitea Base URL** to override the global default.
+```
+
+- [ ] **Step 2: Update the "Settings Overview" — General Settings**
+
+Replace:
+```
+- **GitHub API Token** – Recommended for authenticated requests (avoids GitHub rate limits).
+- **Telemetry** – Toggle to help improve the plugin.
+```
+With:
+```
+- **GitHub API Token** – Recommended for authenticated requests (avoids GitHub rate limits).
+- **Default Gitea Base URL** – Used when a Gitea project doesn't specify one. Defaults to `https://codeberg.org`.
+- **Gitea API Token** – Recommended for authenticated Gitea requests.
+- **Telemetry** – Toggle to help improve the plugin.
+```
+
+- [ ] **Step 3: Add a "Connecting to a Gitea repo" subsection**
+
+Insert directly after the existing "Connect Your GitHub Repo" section:
+
+```
+## Connect Your Gitea Repo
+
+To connect a project to a Gitea instance (self-hosted or public):
+
+1. Set **Provider** to **Gitea** in the project editor.
+2. Paste the full repository URL into **Repository URL** (e.g., `https://codeberg.org/username/repo`).
+3. Optionally override the Gitea base URL for this project (leave blank to use the global default).
+4. Make sure the repo has a release with a `.zip` asset, or any tag — the plugin will fall back to the source archive URL.
+
+### Optional: Add a Gitea API Token
+
+To avoid rate limits or improve reliability:
+
+1. In your Gitea instance, go to **Settings → Applications** and generate a token.
+2. Paste it into the plugin settings screen under **Gitea API Token**.
+```
+
+- [ ] **Step 4: Update the "Enable Download Link" section**
+
+Replace:
+```
+This URL fetches the latest `.zip` release from GitHub and increments the download count.
+```
+With:
+```
+This URL fetches the latest `.zip` release from the project's host (GitHub or Gitea) and increments the download count.
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add README.md
+git commit -m "Document Gitea support in README"
+```
+
+---
+
+## Task 14: Regenerate the translation template
+
+**Files:**
+- Modify: `languages/projects-wp.pot`, `languages/projects-for-wordpress-es_MX.po`, `languages/projects-wp-fr_FR.po` (and any `.l10n.php` siblings).
+
+- [ ] **Step 1: Check whether the plugin uses WP-CLI for POT generation**
+
+Run: `grep -r "wp i18n" . --include="*.json" --include="*.sh" --include="*.md" 2>/dev/null || true`
+
+If no WP-CLI scaffold exists, the `.pot` is hand-maintained. In that case, regenerate it manually using POEdit, `xgettext`, or by hand-adding the new strings listed in spec §16. Then update the `.po` and `.l10n.php` files to mirror the new template.
+
+- [ ] **Step 2: Verify the new strings are present in `projects-wp.pot`**
+
+Run: `grep -E 'msgid "(Repository|Provider|Gitea Base URL \(optional override\)|View Repo|Invalid download URL\. Please check the repository URL\.|Default Gitea Base URL|Gitea API Token|Gitea Settings)"' languages/projects-wp.pot`
+
+Expected: every string from spec §16 appears at least once as a `msgid` in the POT.
+
+- [ ] **Step 3: Commit any changes**
+
+```bash
+git add languages/
+git commit -m "Regenerate translation template for Gitea strings"
+```
+
+---
+
+## Task 15: Final smoke test and full test run
+
+**Files:** none (verification only).
+
+- [ ] **Step 1: Run the full PHPUnit suite**
+
+Run: `vendor/bin/phpunit`
+Expected: All tests pass with no failures.
+
+- [ ] **Step 2: Manual smoke test checklist** (verify in a real WordPress install)
+
+- [ ] Fresh install with a GitHub project — output matches the previous plugin exactly (same fields, same labels).
+- [ ] A Gitea project on `codeberg.org` — version, stars, license, owner avatar all render.
+- [ ] A self-hosted Gitea project with a custom base URL — data renders correctly.
+- [ ] A project with no repo URL — download endpoint shows the wp_die gracefully; templates omit provider-only rows.
+- [ ] Existing project with only the legacy `_projects_portfolio_github_url` meta — first save migrates to the new keys and continues to work.
+
+- [ ] **Step 3: Final commit if anything changed**
+
+```bash
+git status
+# If clean, skip. Otherwise:
+git add -A
+git commit -m "Final smoke-test fixes"
+```
+
+- [ ] **Step 4: Tag the release**
+
+```bash
+git tag -a v1.1.0 -m "v1.1.0 — Gitea support"
+```
\ No newline at end of file