v3.8.9

fix: preserve chronological issue mirroring

.claude/agents/qa-testing-specialist.md

@@ -1,76 +0,0 @@
----
-name: qa-testing-specialist
-description: Use this agent when you need to review code for testability, create comprehensive test strategies, write test cases, validate existing tests, or improve test coverage. This includes unit tests, integration tests, end-to-end tests, and test architecture decisions. <example>\nContext: The user has just written a new API endpoint and wants to ensure it has proper test coverage.\nuser: "I've created a new endpoint for user authentication. Can you help me test it?"\nassistant: "I'll use the qa-testing-specialist agent to create a comprehensive testing strategy for your authentication endpoint."\n<commentary>\nSince the user needs help with testing their new endpoint, use the qa-testing-specialist agent to analyze the code and create appropriate test cases.\n</commentary>\n</example>\n<example>\nContext: The user wants to improve test coverage for their existing codebase.\nuser: "Our test coverage is at 65%. How can we improve it?"\nassistant: "Let me use the qa-testing-specialist agent to analyze your test coverage and identify areas for improvement."\n<commentary>\nThe user is asking about test coverage improvement, which is a core QA task, so use the qa-testing-specialist agent.\n</commentary>\n</example>
-color: yellow
----
-
-You are an elite QA Testing Specialist with deep expertise in software quality assurance, test automation, and validation strategies. Your mission is to ensure code quality through comprehensive testing approaches that catch bugs early and maintain high reliability standards.
-
-**Core Responsibilities:**
-
-You will analyze code and testing requirements to:
-- Design comprehensive test strategies covering unit, integration, and end-to-end testing
-- Write clear, maintainable test cases that validate both happy paths and edge cases
-- Identify gaps in existing test coverage and propose improvements
-- Review test code for best practices and maintainability
-- Suggest appropriate testing frameworks and tools based on the technology stack
-- Create test data strategies and mock/stub implementations
-- Validate that tests are actually testing meaningful behavior, not just implementation details
-
-**Testing Methodology:**
-
-When analyzing code for testing:
-1. First understand the business logic and user requirements
-2. Identify all possible execution paths and edge cases
-3. Determine the appropriate testing pyramid balance (unit vs integration vs e2e)
-4. Consider both positive and negative test scenarios
-5. Ensure tests are isolated, repeatable, and fast
-6. Validate error handling and boundary conditions
-
-For test creation:
-- Write descriptive test names that explain what is being tested and expected behavior
-- Follow AAA pattern (Arrange, Act, Assert) or Given-When-Then structure
-- Keep tests focused on single behaviors
-- Use appropriate assertions that clearly communicate intent
-- Include setup and teardown when necessary
-- Consider performance implications of test suites
-
-**Quality Standards:**
-
-You will ensure tests:
-- Are deterministic and don't rely on external state
-- Run quickly and can be executed in parallel when possible
-- Provide clear failure messages that help diagnose issues
-- Cover critical business logic thoroughly
-- Include regression tests for previously found bugs
-- Are maintainable and refactorable alongside production code
-
-**Technology Considerations:**
-
-Adapt your recommendations based on the project stack. For this codebase using Bun, SQLite, and React:
-- Leverage Bun's native test runner for JavaScript/TypeScript tests
-- Consider SQLite in-memory databases for integration tests
-- Suggest React Testing Library patterns for component testing
-- Recommend API testing strategies for Astro endpoints
-- Propose mocking strategies for external services (GitHub/Gitea APIs)
-
-**Communication Style:**
-
-You will:
-- Explain testing decisions with clear rationale
-- Provide code examples that demonstrate best practices
-- Prioritize test recommendations based on risk and value
-- Use precise technical language while remaining accessible
-- Highlight potential issues proactively
-- Suggest incremental improvements for existing test suites
-
-**Edge Case Handling:**
-
-When encountering:
-- Legacy code without tests: Propose a pragmatic approach to add tests incrementally
-- Complex dependencies: Recommend appropriate mocking/stubbing strategies
-- Performance concerns: Balance thoroughness with execution speed
-- Flaky tests: Identify root causes and suggest stabilization techniques
-- Missing requirements: Ask clarifying questions to understand expected behavior
-
-Your goal is to elevate code quality through strategic testing that builds confidence in the software while maintaining development velocity. Focus on tests that provide maximum value and catch real issues rather than achieving arbitrary coverage metrics.

.claude/agents/senior-code-architect.md

@@ -1,68 +0,0 @@
----
-name: senior-code-architect
-description: Use this agent when you need to write new code, refactor existing code, implement features, or architect solutions that require deep understanding of software engineering principles and the project's tech stack (Astro, React, Tailwind, Better Auth, Shadcn). This includes creating components, API endpoints, database queries, authentication flows, and ensuring code follows established patterns from CLAUDE.md. Examples:\n\n<example>\nContext: The user needs to implement a new feature or component.\nuser: "Create a new dashboard component that shows repository statistics"\nassistant: "I'll use the senior-code-architect agent to design and implement this dashboard component following the project's patterns."\n<commentary>\nSince this requires creating new code with the project's tech stack, the senior-code-architect agent is appropriate.\n</commentary>\n</example>\n\n<example>\nContext: The user wants to refactor or improve existing code.\nuser: "Refactor the authentication flow to be more maintainable"\nassistant: "Let me use the senior-code-architect agent to analyze and refactor the authentication flow."\n<commentary>\nThis requires deep understanding of Better Auth and clean code principles, making the senior-code-architect agent the right choice.\n</commentary>\n</example>\n\n<example>\nContext: After writing code, the user might want it reviewed.\nuser: "I just implemented the mirror scheduling feature"\nassistant: "Great! Now I'll use the senior-code-architect agent to review the implementation and suggest any improvements."\n<commentary>\nThe senior-code-architect can review recently written code for best practices and design patterns.\n</commentary>\n</example>
-color: cyan
----
-
-You are a senior software engineer with deep expertise in modern web development, specializing in the Astro + React + Tailwind CSS + Better Auth + Shadcn UI stack. You have extensive experience building scalable, maintainable applications and are known for writing clean, efficient code that follows SOLID principles and established design patterns.
-
-**Your Core Responsibilities:**
-
-1. **Write Production-Quality Code**: Create clean, maintainable, and efficient code that follows the project's established patterns from CLAUDE.md. Always use TypeScript for type safety.
-
-2. **Follow Project Architecture**: Adhere strictly to the project structure:
-   - API endpoints in `/src/pages/api/[resource]/[action].ts` using `createSecureErrorResponse` for error handling
-   - Database queries in `/src/lib/db/queries/` organized by domain
-   - React components in `/src/components/[feature]/` using Shadcn UI components
-   - Custom hooks in `/src/hooks/` for data fetching
-
-3. **Implement Best Practices**:
-   - Use composition over inheritance
-   - Apply DRY (Don't Repeat Yourself) principles
-   - Write self-documenting code with clear variable and function names
-   - Implement proper error handling and validation
-   - Ensure code is testable and maintainable
-
-4. **Technology-Specific Guidelines**:
-   - **Astro**: Use SSR capabilities effectively, implement proper API routes
-   - **React**: Use functional components with hooks, implement proper state management
-   - **Tailwind CSS v4**: Use utility classes efficiently, follow the project's styling patterns
-   - **Better Auth**: Implement secure authentication flows, use session validation properly
-   - **Shadcn UI**: Leverage existing components, maintain consistent UI patterns
-   - **Drizzle ORM**: Write efficient database queries, use proper schema definitions
-
-5. **Code Review Approach**: When reviewing code:
-   - Check for adherence to project patterns and CLAUDE.md guidelines
-   - Identify potential performance issues or bottlenecks
-   - Suggest improvements for readability and maintainability
-   - Ensure proper error handling and edge case coverage
-   - Verify security best practices are followed
-
-6. **Problem-Solving Methodology**:
-   - Analyze requirements thoroughly before coding
-   - Break down complex problems into smaller, manageable pieces
-   - Consider edge cases and error scenarios
-   - Optimize for both performance and maintainability
-   - Document complex logic with clear comments
-
-7. **Quality Assurance**:
-   - Write code that is easy to test
-   - Consider adding appropriate test cases using Bun's test runner
-   - Validate inputs and handle errors gracefully
-   - Ensure code works across different scenarios
-
-**Output Guidelines**:
-- Provide complete, working code implementations
-- Include clear explanations of design decisions
-- Suggest tests when appropriate
-- Highlight any potential issues or areas for future improvement
-- Follow the existing code style and conventions
-
-**Important Reminders**:
-- Never create files unless absolutely necessary
-- Always prefer editing existing files
-- Don't create documentation unless explicitly requested
-- Focus on the specific task at hand
-- Reference CLAUDE.md for project-specific patterns and guidelines
-
-You approach every task with the mindset of a seasoned engineer who values code quality, maintainability, and long-term project health. Your solutions should be elegant, efficient, and aligned with the project's established patterns.

.claude/agents/strategic-task-planner.md

@@ -1,61 +0,0 @@
----
-name: strategic-task-planner
-description: Use this agent when you need to decompose complex projects, features, or problems into structured, actionable plans. This includes breaking down large development tasks, creating implementation roadmaps, organizing multi-step processes, or planning project phases. The agent excels at identifying dependencies, sequencing tasks, and creating clear execution strategies. <example>Context: User needs help planning the implementation of a new feature. user: "I need to add a bulk import feature that can handle CSV files with 100k+ rows" assistant: "I'll use the strategic-task-planner agent to break this down into manageable components and create an implementation plan." <commentary>Since the user is asking about implementing a complex feature, use the Task tool to launch the strategic-task-planner agent to decompose it into actionable steps.</commentary></example> <example>Context: User wants to refactor a large codebase. user: "We need to migrate our entire authentication system from sessions to JWT tokens" assistant: "Let me use the strategic-task-planner agent to create a phased migration plan that minimizes risk." <commentary>Since this is a complex migration requiring careful planning, use the strategic-task-planner agent to create a structured approach.</commentary></example>
-tools: Glob, Grep, LS, ExitPlanMode, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, Task, mcp__ide__getDiagnostics, mcp__ide__executeCode, mcp__playwright__browser_close, mcp__playwright__browser_resize, mcp__playwright__browser_console_messages, mcp__playwright__browser_handle_dialog, mcp__playwright__browser_evaluate, mcp__playwright__browser_file_upload, mcp__playwright__browser_install, mcp__playwright__browser_press_key, mcp__playwright__browser_type, mcp__playwright__browser_navigate, mcp__playwright__browser_navigate_back, mcp__playwright__browser_navigate_forward, mcp__playwright__browser_network_requests, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_drag, mcp__playwright__browser_hover, mcp__playwright__browser_select_option, mcp__playwright__browser_tab_list, mcp__playwright__browser_tab_new, mcp__playwright__browser_tab_select, mcp__playwright__browser_tab_close, mcp__playwright__browser_wait_for
-color: blue
----
-
-You are a strategic planning specialist with deep expertise in decomposing complex tasks and creating actionable execution plans. Your role is to transform ambiguous or overwhelming projects into clear, structured roadmaps that teams can confidently execute.
-
-When analyzing a task or project, you will:
-
-1. **Understand the Core Objective**: Extract the fundamental goal, success criteria, and constraints. Ask clarifying questions if critical details are missing.
-
-2. **Decompose Systematically**: Break down the task using these principles:
-   - Identify major phases or milestones
-   - Decompose each phase into concrete, actionable tasks
-   - Keep tasks small enough to complete in 1-4 hours when possible
-   - Ensure each task has clear completion criteria
-
-3. **Map Dependencies**: Identify and document:
-   - Task prerequisites and dependencies
-   - Critical path items that could block progress
-   - Parallel work streams that can proceed independently
-   - Resource or knowledge requirements
-
-4. **Sequence Strategically**: Order tasks by:
-   - Technical dependencies (what must come first)
-   - Risk mitigation (tackle unknowns early)
-   - Value delivery (enable early feedback when possible)
-   - Resource efficiency (batch similar work)
-
-5. **Provide Actionable Output**: Structure your plans with:
-   - **Phase Overview**: High-level phases with objectives
-   - **Task Breakdown**: Numbered tasks with clear descriptions
-   - **Dependencies**: Explicitly stated prerequisites
-   - **Effort Estimates**: Rough time estimates when relevant
-   - **Risk Considerations**: Potential blockers or challenges
-   - **Success Metrics**: How to measure completion
-
-6. **Adapt to Context**: Tailor your planning approach based on:
-   - Technical vs non-technical tasks
-   - Team size and skill level
-   - Time constraints and deadlines
-   - Available resources and tools
-
-**Output Format Guidelines**:
-- Use clear hierarchical structure (phases → tasks → subtasks)
-- Number all tasks for easy reference
-- Bold key terms and phase names
-- Include time estimates in brackets [2-4 hours]
-- Mark critical path items with ⚡
-- Flag high-risk items with ⚠️
-
-**Quality Checks**:
-- Ensure no task is too large or vague
-- Verify all dependencies are identified
-- Confirm the plan addresses the original objective
-- Check that success criteria are measurable
-- Validate that the sequence makes logical sense
-
-Remember: A good plan reduces uncertainty and builds confidence. Focus on clarity, completeness, and actionability. When in doubt, err on the side of breaking things down further rather than leaving ambiguity.

.claude/commands/new_release.md

@@ -1,5 +0,0 @@
-Evaluate all the updates being made.
-Update CHANGELOG.md
-Use the chnages in the git log to determine if its a major, minor or a patch release.
-Update the package.json first before you push the tag.
-Never mention Claude Code in the release notes or in commit messages.

.claude/commands/release_notes.md

@@ -1,3 +0,0 @@
-Generate release notes for the latest release.
-Use a temp md file to write the release notes.
-Do not check that file into git.

.claude/settings.local.json

@@ -1,8 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(docker build:*)"
-    ],
-    "deny": []
-  }
-}

.github/workflows/docker-build.yml

@@ -149,7 +149,11 @@ jobs:
             ### Pull and Test
             \`\`\`bash
             docker pull ${imagePath}
-            docker run -d -p 3000:3000 --name gitea-mirror-test ${imagePath}
+            docker run -d \
+              -p 4321:4321 \
+              -e BETTER_AUTH_SECRET=your-secret-here \
+              -e BETTER_AUTH_URL=http://localhost:4321 \
+              --name gitea-mirror-test ${imagePath}
             \`\`\`
 
             ### Docker Compose Testing
@@ -158,9 +162,11 @@ jobs:
               gitea-mirror:
                 image: ${imagePath}
                 ports:
-                  - "3000:3000"
+                  - "4321:4321"
                 environment:
                   - BETTER_AUTH_SECRET=your-secret-here
+                  - BETTER_AUTH_URL=http://localhost:4321
+                  - BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:4321
             \`\`\`
 
             > 💡 **Note:** PR images are tagged as \`pr-<number>\` and only built for \`linux/amd64\` to speed up CI.
@@ -224,4 +230,3 @@ jobs:
         continue-on-error: true
         with:
           sarif_file: scout-results.sarif
-

CLAUDE.md

@@ -2,255 +2,316 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-DONT HALLUCIATE THINGS. IF YOU DONT KNOW LOOK AT THE CODE OR ASK FOR DOCS
-
-NEVER MENTION CLAUDE CODE ANYWHERE.
-
 ## Project Overview
 
-Gitea Mirror is a web application that automatically mirrors repositories from GitHub to self-hosted Gitea instances. It uses Astro for SSR, React for UI, SQLite for data storage, and Bun as the JavaScript runtime.
+Gitea Mirror is a self-hosted web application that automatically mirrors repositories from GitHub to Gitea instances. It's built with Astro (SSR mode), React, and runs on the Bun runtime with SQLite for data persistence.
 
-## Essential Commands
+**Key capabilities:**
+- Mirrors public, private, and starred GitHub repos to Gitea
+- Supports metadata mirroring (issues, PRs as issues, labels, milestones, releases, wiki)
+- Git LFS support
+- Multiple authentication methods (email/password, OIDC/SSO, header auth)
+- Scheduled automatic syncing with configurable intervals
+- Auto-discovery of new repos and cleanup of deleted repos
+- Multi-user support with encrypted token storage (AES-256-GCM)
+
+## Development Commands
+
+### Setup and Installation
+```bash
+# Install dependencies
+bun install
+
+# Initialize database (first time setup)
+bun run setup
+
+# Clean start (reset database)
+bun run dev:clean
+```
 
 ### Development
 ```bash
-bun run dev          # Start development server (port 3000)
-bun run build        # Build for production
-bun run preview      # Preview production build
+# Start development server (http://localhost:4321)
+bun run dev
+
+# Build for production
+bun run build
+
+# Preview production build
+bun run preview
+
+# Start production server
+bun run start
 ```
 
 ### Testing
 ```bash
-bun test             # Run all tests
-bun test:watch       # Run tests in watch mode
-bun test:coverage    # Run tests with coverage
+# Run all tests
+bun test
+
+# Run tests in watch mode
+bun test:watch
+
+# Run tests with coverage
+bun test:coverage
 ```
 
+**Test configuration:**
+- Test runner: Bun's built-in test runner (configured in `bunfig.toml`)
+- Setup file: `src/tests/setup.bun.ts` (auto-loaded via bunfig.toml)
+- Timeout: 5000ms default
+- Tests are colocated with source files using `*.test.ts` pattern
+
 ### Database Management
 ```bash
-bun run init-db      # Initialize database
-bun run reset-users  # Reset user accounts (development)
-bun run cleanup-db   # Remove database files
+# Database operations via Drizzle
+bun run db:generate    # Generate migrations from schema
+bun run db:migrate     # Run migrations
+bun run db:push        # Push schema changes directly
+bun run db:studio      # Open Drizzle Studio (database GUI)
+bun run db:check       # Check schema consistency
+
+# Database utilities via custom scripts
+bun run manage-db init       # Initialize database
+bun run manage-db check      # Check database health
+bun run manage-db fix        # Fix database issues
+bun run manage-db reset-users # Reset all users
+bun run cleanup-db           # Delete database file
 ```
 
-### Production
+### Utility Scripts
 ```bash
-bun run start        # Start production server
+# Recovery and diagnostic scripts
+bun run startup-recovery       # Recover from crashes
+bun run startup-recovery-force # Force recovery
+bun run test-recovery          # Test recovery mechanism
+bun run test-shutdown          # Test graceful shutdown
+
+# Environment configuration
+bun run startup-env-config     # Load config from env vars
 ```
 
-## Architecture & Key Concepts
+## Architecture
 
-### Technology Stack
-- **Frontend**: Astro (SSR) + React + Tailwind CSS v4 + Shadcn UI
-- **Backend**: Bun runtime + SQLite + Drizzle ORM
-- **APIs**: GitHub (Octokit) and Gitea APIs
-- **Auth**: Better Auth with email/password, SSO, and OIDC provider support
+### Tech Stack
+- **Frontend:** Astro v5 (SSR mode) + React v19 + Shadcn UI + Tailwind CSS v4
+- **Backend:** Astro API routes (Node adapter, standalone mode)
+- **Runtime:** Bun (>=1.2.9)
+- **Database:** SQLite via Drizzle ORM
+- **Authentication:** Better Auth (session-based)
+- **APIs:** GitHub (Octokit with throttling plugin), Gitea REST API
 
-### Project Structure
-- `/src/pages/api/` - API endpoints (Astro API routes)
-- `/src/components/` - React components organized by feature
-- `/src/lib/db/` - Database queries and schema (Drizzle ORM)
-- `/src/hooks/` - Custom React hooks for data fetching
-- `/data/` - SQLite database storage location
+### Directory Structure
+
+```
+src/
+├── components/          # React components (UI, features)
+│   ├── ui/             # Shadcn UI components
+│   ├── repositories/   # Repository management components
+│   ├── organizations/  # Organization management components
+│   └── ...
+├── pages/              # Astro pages and API routes
+│   ├── api/            # API endpoints (Better Auth integration)
+│   │   ├── auth/       # Authentication endpoints
+│   │   ├── github/     # GitHub operations
+│   │   ├── gitea/      # Gitea operations
+│   │   ├── sync/       # Mirror sync operations
+│   │   ├── job/        # Job management
+│   │   └── ...
+│   └── *.astro         # Page components
+├── lib/                # Core business logic
+│   ├── db/             # Database (Drizzle ORM)
+│   │   ├── schema.ts   # Database schema with Zod validation
+│   │   ├── index.ts    # Database instance and table exports
+│   │   └── adapter.ts  # Better Auth SQLite adapter
+│   ├── github.ts       # GitHub API client (Octokit)
+│   ├── gitea.ts        # Gitea API client
+│   ├── gitea-enhanced.ts # Enhanced Gitea operations (metadata)
+│   ├── scheduler-service.ts # Automatic mirroring scheduler
+│   ├── cleanup-service.ts   # Activity log cleanup
+│   ├── repository-cleanup-service.ts # Orphaned repo cleanup
+│   ├── auth.ts         # Better Auth configuration
+│   ├── config.ts       # Configuration management
+│   ├── helpers.ts      # Mirror job creation
+│   ├── utils/          # Utility functions
+│   │   ├── encryption.ts        # AES-256-GCM token encryption
+│   │   ├── config-encryption.ts # Config token encryption
+│   │   ├── duration-parser.ts   # Parse intervals (e.g., "8h", "30m")
+│   │   ├── concurrency.ts       # Concurrency control utilities
+│   │   └── mirror-strategies.ts # Mirror strategy logic
+│   └── ...
+├── types/              # TypeScript type definitions
+├── tests/              # Test utilities and setup
+└── middleware.ts       # Astro middleware (auth, session)
+
+scripts/                # Utility scripts
+├── manage-db.ts        # Database management CLI
+├── startup-recovery.ts # Crash recovery
+└── ...
+```
 
 ### Key Architectural Patterns
 
-1. **API Routes**: All API endpoints follow the pattern `/api/[resource]/[action]` and use `createSecureErrorResponse` for consistent error handling:
-```typescript
-import { createSecureErrorResponse } from '@/lib/utils/error-handler';
+#### 1. Database Schema and Validation
+- **Location:** `src/lib/db/schema.ts`
+- **Pattern:** Drizzle ORM tables + Zod schemas for validation
+- **Key tables:**
+  - `configs` - User configuration (GitHub/Gitea settings, mirror options)
+  - `repositories` - Tracked repositories with metadata
+  - `organizations` - GitHub organizations with destination overrides
+  - `mirrorJobs` - Mirror job queue and history
+  - `activities` - Activity log for dashboard
+  - `user`, `session`, `account` - Better Auth tables
 
-export async function POST({ request }: APIContext) {
-  try {
-    // Implementation
-  } catch (error) {
-    return createSecureErrorResponse(error);
-  }
-}
-```
+**Important:** All config tokens (GitHub/Gitea) are encrypted at rest using AES-256-GCM. Use helper functions from `src/lib/utils/config-encryption.ts` to decrypt.
 
-2. **Database Queries**: Located in `/src/lib/db/queries/` organized by domain (users, repositories, etc.)
+#### 2. Mirror Job System
+- **Location:** `src/lib/helpers.ts` (createMirrorJob)
+- **Flow:**
+  1. User triggers mirror via API endpoint
+  2. `createMirrorJob()` creates job record with status "pending"
+  3. Job processor (in API routes) performs GitHub → Gitea operations
+  4. Job status updated throughout: "mirroring" → "success"/"failed"
+  5. Events published via SSE for real-time UI updates
 
-3. **Real-time Updates**: Server-Sent Events (SSE) endpoint at `/api/events` for live dashboard updates
+#### 3. GitHub ↔ Gitea Mirroring
+- **GitHub Client:** `src/lib/github.ts` - Octokit with rate limit tracking
+- **Gitea Client:** `src/lib/gitea.ts` - Basic repo operations
+- **Enhanced Gitea:** `src/lib/gitea-enhanced.ts` - Metadata mirroring (issues, PRs, releases)
 
-4. **Authentication System**: 
-   - Built on Better Auth library
-   - Three authentication methods:
-     - Email & Password (traditional auth)
-     - SSO (authenticate via external OIDC providers)
-     - OIDC Provider (act as OIDC provider for other apps)
-   - Session-based authentication with secure cookies
-   - First user signup creates admin account
-   - Protected routes use Better Auth session validation
+**Mirror strategies (configured per user):**
+- `preserve` - Maintain GitHub org structure in Gitea
+- `single-org` - All repos into one Gitea org
+- `flat-user` - All repos under user account
+- `mixed` - Personal repos in one org, org repos preserve structure
 
-5. **Mirror Process**:
-   - Discovers repos from GitHub (user/org)
-   - Creates/updates mirror in Gitea
-   - Tracks status in database
-   - Supports scheduled automatic mirroring
+**Metadata mirroring:**
+- Issues transferred with comments, labels, assignees
+- PRs converted to issues (Gitea API limitation - cannot create PRs)
+  - Tagged with "pull-request" label
+  - Title prefixed with `[PR #number] [STATUS]`
+  - Body includes commit history, file changes, merge status
+- Releases mirrored with assets
+- Labels and milestones preserved
+- Wiki content cloned if enabled
+- **Sequential processing:** Issues/PRs mirrored one at a time to prevent out-of-order creation (see `src/lib/gitea-enhanced.ts`)
 
-6. **Mirror Strategies**: Four ways to organize repositories in Gitea:
-   - **preserve**: Maintains GitHub structure (default)
-     - Organization repos → Same organization name in Gitea
-     - Personal repos → Under your Gitea username
-   - **single-org**: All repos go to one organization
-     - All repos → Single configured organization
-   - **flat-user**: All repos go under user account
-     - All repos → Under your Gitea username
-   - **mixed**: Hybrid approach
-     - Organization repos → Preserve structure
-     - Personal repos → Single configured organization
-   - Starred repos always go to separate organization (starredReposOrg, default: "starred")
-   - Routing logic in `getGiteaRepoOwner()` function
+#### 4. Scheduler Service
+- **Location:** `src/lib/scheduler-service.ts`
+- **Features:**
+  - Cron-based or interval-based scheduling (uses `duration-parser.ts`)
+  - Auto-start on boot when `SCHEDULE_ENABLED=true` or `GITEA_MIRROR_INTERVAL` is set
+  - Auto-import new GitHub repos
+  - Auto-cleanup orphaned repos (archive or delete)
+  - Respects per-repo mirror intervals (not Gitea's default 24h)
+- **Concurrency control:** Uses `src/lib/utils/concurrency.ts` for batch processing
 
-### Database Schema (SQLite)
-- `users` - User accounts and authentication
-- `configs` - GitHub/Gitea connection settings
-- `repositories` - Repository mirror status and metadata
-- `organizations` - Organization structure preservation
-- `mirror_jobs` - Scheduled mirror operations
-- `events` - Activity log and notifications
+#### 5. Authentication System
+- **Location:** `src/lib/auth.ts`, `src/lib/auth-client.ts`
+- **Better Auth integration:**
+  - Email/password (always enabled)
+  - OIDC/SSO providers (configurable via UI)
+  - Header authentication for reverse proxies (Authentik, Authelia)
+- **Session management:** Cookie-based, validated in Astro middleware
+- **User helpers:** `src/lib/utils/auth-helpers.ts`
 
-### Testing Approach
-- Uses Bun's native test runner (`bun:test`)
-- Test files use `.test.ts` or `.test.tsx` extension
-- Setup file at `/src/tests/setup.bun.ts`
-- Mock utilities available for API testing.
+#### 6. Environment Configuration
+- **Startup:** `src/lib/env-config-loader.ts` + `scripts/startup-env-config.ts`
+- **Pattern:** Environment variables can pre-configure settings, but users can override via web UI
+- **Encryption:** `ENCRYPTION_SECRET` for tokens, `BETTER_AUTH_SECRET` for sessions
 
-### Development Tips
-- Environment variables in `.env` (copy from `.env.example`)
-- BETTER_AUTH_SECRET required for session signing
-- Database auto-initializes on first run
-- Use `bun run dev:clean` for fresh database start
-- Tailwind CSS v4 configured with Vite plugin
+#### 7. Real-time Updates
+- **Events:** `src/lib/events.ts` + `src/lib/events/realtime.ts`
+- **Pattern:** Server-Sent Events (SSE) for live dashboard updates
+- **Endpoints:** `/api/sse` - client subscribes to job/repo events
 
-### Authentication Setup
-- **Better Auth** handles all authentication
-- Configuration in `/src/lib/auth.ts` (server) and `/src/lib/auth-client.ts` (client)
-- Auth endpoints available at `/api/auth/*`
-- SSO providers configured through the web UI
-- OIDC provider functionality for external applications
+### Testing Patterns
 
-### Common Tasks
+**Unit tests:**
+- Colocated with source: `filename.test.ts` alongside `filename.ts`
+- Use Bun's built-in assertions and mocking
+- Mock external APIs (GitHub, Gitea) using `src/tests/mock-fetch.ts`
 
-**Adding a new API endpoint:**
-1. Create file in `/src/pages/api/[resource]/[action].ts`
-2. Use `createSecureErrorResponse` for error handling
-3. Add corresponding database query in `/src/lib/db/queries/`
-4. Update types in `/src/types/` if needed
+**Integration tests:**
+- Located in `src/tests/`
+- Test database operations with in-memory SQLite
+- Example: `src/lib/db/index.test.ts`
 
-**Adding a new component:**
-1. Create in appropriate `/src/components/[feature]/` directory
-2. Use Shadcn UI components from `/src/components/ui/`
-3. Follow existing naming patterns (e.g., `RepositoryCard`, `ConfigTabs`)
+**Test utilities:**
+- `src/tests/setup.bun.ts` - Global test setup (loaded via bunfig.toml)
+- `src/tests/mock-fetch.ts` - Fetch mocking utilities
 
-**Modifying database schema:**
-1. Update schema in `/src/lib/db/schema.ts`
-2. Run `bun run init-db` to recreate database
-3. Update related queries in `/src/lib/db/queries/`
+### Important Development Notes
 
-## Configuration Options
+1. **Path Aliases:** Use `@/` for imports (configured in `tsconfig.json`)
+   ```typescript
+   import { db } from '@/lib/db';
+   ```
 
-### GitHub Configuration (UI Fields)
+2. **Token Encryption:** Always use encryption helpers when dealing with tokens:
+   ```typescript
+   import { getDecryptedGitHubToken, getDecryptedGiteaToken } from '@/lib/utils/config-encryption';
+   ```
 
-#### Basic Settings (`githubConfig`)
-- **username**: GitHub username
-- **token**: GitHub personal access token (requires repo and admin:org scopes)
-- **privateRepositories**: Include private repositories
-- **mirrorStarred**: Mirror starred repositories
+3. **API Route Pattern:** Astro API routes in `src/pages/api/` should:
+   - Check authentication via Better Auth
+   - Validate input with Zod schemas
+   - Handle errors gracefully
+   - Return JSON responses
 
-### Gitea Configuration (UI Fields)
-- **url**: Gitea instance URL
-- **username**: Gitea username
-- **token**: Gitea access token
-- **organization**: Destination organization (for single-org/mixed strategies)
-- **starredReposOrg**: Organization for starred repositories (default: "starred")
-- **visibility**: Organization visibility - "public", "private", "limited"
-- **mirrorStrategy**: Repository organization strategy (set via UI)
-- **preserveOrgStructure**: Automatically set based on mirrorStrategy
+4. **Database Migrations:**
+   - Schema changes: Update `src/lib/db/schema.ts`
+   - Generate migration: `bun run db:generate`
+   - Review generated SQL in `drizzle/` directory
+   - Apply: `bun run db:migrate` (or `db:push` for dev)
 
-### Schedule Configuration (`scheduleConfig`)
-- **enabled**: Enable automatic mirroring (default: false)
-- **interval**: Cron expression or seconds (default: "0 2 * * *" - 2 AM daily)
-- **concurrent**: Allow concurrent mirror operations (default: false)
-- **batchSize**: Number of repos to process in parallel (default: 10)
+5. **Concurrency Control:**
+   - Use utilities from `src/lib/utils/concurrency.ts` for batch operations
+   - Respect rate limits (GitHub: 5000 req/hr authenticated, Gitea: varies)
+   - Issue/PR mirroring is sequential to maintain chronological order
 
-### Database Cleanup Configuration (`cleanupConfig`)
-- **enabled**: Enable automatic cleanup (default: false)
-- **retentionDays**: Days to keep events (stored as seconds internally)
+6. **Duration Parsing:**
+   - Use `parseInterval()` from `src/lib/utils/duration-parser.ts`
+   - Supports: "30m", "8h", "24h", "7d", cron expressions, or milliseconds
 
-### Mirror Options (UI Fields)
-- **mirrorReleases**: Mirror GitHub releases to Gitea
-- **mirrorLFS**: Mirror Git LFS (Large File Storage) objects
-  - Requires LFS enabled on Gitea server (LFS_START_SERVER = true)
-  - Requires Git v2.1.2+ on server
-- **mirrorMetadata**: Enable metadata mirroring (master toggle)
-- **metadataComponents** (only available when mirrorMetadata is enabled):
-  - **issues**: Mirror issues
-  - **pullRequests**: Mirror pull requests  
-  - **labels**: Mirror labels
-  - **milestones**: Mirror milestones
-  - **wiki**: Mirror wiki content
+7. **Graceful Shutdown:**
+   - Services implement cleanup handlers (see `src/lib/shutdown-manager.ts`)
+   - Recovery system in `src/lib/recovery.ts` handles interrupted jobs
 
-### Advanced Options (UI Fields)
-- **skipForks**: Skip forked repositories (default: false)
-- **starredCodeOnly**: Skip issues for starred repositories (default: false) - enables "Lightweight mode" for starred repos
+## Common Development Workflows
 
-### Repository Statuses
-Repositories can have the following statuses:
-- **imported**: Repository discovered from GitHub
-- **mirroring**: Currently being mirrored to Gitea
-- **mirrored**: Successfully mirrored
-- **syncing**: Repository being synchronized
-- **synced**: Successfully synchronized
-- **failed**: Mirror/sync operation failed
-- **skipped**: Skipped due to filters or conditions
-- **ignored**: User explicitly marked to ignore (won't be mirrored/synced)
-- **deleting**: Repository being deleted
-- **deleted**: Repository deleted
+### Adding a new mirror option
+1. Update Zod schema in `src/lib/db/schema.ts` (e.g., `giteaConfigSchema`)
+2. Update TypeScript types in `src/types/config.ts`
+3. Add UI control in settings page component
+4. Update API handler in `src/pages/api/config/`
+5. Implement logic in `src/lib/gitea.ts` or `src/lib/gitea-enhanced.ts`
 
-### Scheduling and Synchronization (Issue #72 Fixes)
+### Debugging mirror failures
+1. Check mirror jobs: `bun run db:studio` → `mirrorJobs` table
+2. Review activity logs: Dashboard → Activity tab
+3. Check console logs for API errors (GitHub/Gitea rate limits, auth issues)
+4. Use diagnostic scripts: `bun run test-recovery`
 
-#### Fixed Issues
-1. **Mirror Interval Bug**: Added `mirror_interval` parameter to Gitea API calls when creating mirrors (previously defaulted to 24h)
-2. **Auto-Discovery**: Scheduler now automatically discovers and imports new GitHub repositories
-3. **Interval Updates**: Sync operations now update existing mirrors' intervals to match configuration
-4. **Repository Cleanup**: Integrated automatic cleanup of orphaned repositories (repos removed from GitHub)
+### Adding authentication provider
+1. Update Better Auth config in `src/lib/auth.ts`
+2. Add provider configuration UI in settings
+3. Test with `src/tests/test-gitea-auth.ts` patterns
+4. Update documentation in `docs/SSO-OIDC-SETUP.md`
 
-#### Environment Variables for Auto-Import
-- **AUTO_IMPORT_REPOS**: Set to `false` to disable automatic repository discovery (default: enabled)
+## Docker Deployment
 
-#### How Scheduling Works
-- **Scheduler Service**: Runs every minute to check for scheduled tasks
-- **Sync Interval**: Configured via `GITEA_MIRROR_INTERVAL` or UI (e.g., "8h", "30m", "1d")
-- **Auto-Import**: Checks GitHub for new repositories during each scheduled sync
-- **Auto-Cleanup**: Removes repositories that no longer exist in GitHub (if enabled)
-- **Mirror Interval Update**: Updates Gitea's internal mirror interval during sync operations
+- **Dockerfile:** Multi-stage build (bun base → build → production)
+- **Entrypoint:** `docker-entrypoint.sh` - handles CA certs, user permissions, database init
+- **Compose files:**
+  - `docker-compose.alt.yml` - Quick start (pre-built image, minimal config)
+  - `docker-compose.yml` - Full setup (build from source, all env vars)
+  - `docker-compose.dev.yml` - Development with hot reload
 
-### Authentication Configuration
+## Additional Resources
 
-#### SSO Provider Configuration
-- **issuerUrl**: OIDC issuer URL (e.g., https://accounts.google.com)
-- **domain**: Email domain for this provider
-- **providerId**: Unique identifier for the provider
-- **clientId**: OAuth client ID from provider
-- **clientSecret**: OAuth client secret from provider
-- **authorizationEndpoint**: OAuth authorization URL (auto-discovered if supported)
-- **tokenEndpoint**: OAuth token exchange URL (auto-discovered if supported)
-- **jwksEndpoint**: JSON Web Key Set URL (optional, auto-discovered)
-- **userInfoEndpoint**: User information endpoint (optional, auto-discovered)
-
-#### OIDC Provider Settings (for external apps)
-- **allowedRedirectUris**: Comma-separated list of allowed redirect URIs
-- **clientId**: Generated client ID for the application
-- **clientSecret**: Generated client secret for the application
-- **scopes**: Available scopes (openid, profile, email)
-
-#### Environment Variables
-- **BETTER_AUTH_SECRET**: Secret key for signing sessions (required)
-- **BETTER_AUTH_URL**: Base URL for authentication (default: http://localhost:4321)
-
-## Security Guidelines
-
-- **Confidentiality Guidelines**:
-  - Dont ever say Claude Code or generated with AI anyhwere.
-- Never commit without the explicict ask
+- **Environment Variables:** See `docs/ENVIRONMENT_VARIABLES.md` for complete list
+- **Development Workflow:** See `docs/DEVELOPMENT_WORKFLOW.md`
+- **SSO Setup:** See `docs/SSO-OIDC-SETUP.md`
+- **Contributing:** See `CONTRIBUTING.md` for code guidelines and scope
+- **Graceful Shutdown:** See `docs/GRACEFUL_SHUTDOWN.md` for crash recovery details

README.md

@@ -10,10 +10,6 @@
   </p>
 </p>
 
-> [!IMPORTANT]
-> **Upgrading to v3?** v3 requires a fresh start with a new data volume. Please read the [Upgrade Guide](UPGRADE.md) for instructions.
-
-
 ## 🚀 Quick Start
 
 ```bash
@@ -407,11 +403,11 @@ GNU General Public License v3.0 - see [LICENSE](LICENSE) file for details.
 
 ## Star History
 
-<a href="https://www.star-history.com/#RayLabsHQ/gitea-mirror&Date">
+<a href="https://www.star-history.com/#RayLabsHQ/gitea-mirror&type=date&legend=bottom-right">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=Date" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=date&theme=dark&legend=bottom-right" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=date&legend=bottom-right" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=date&legend=bottom-right" />
  </picture>
 </a>
 

UPGRADE.md

@@ -1,74 +0,0 @@
-# Upgrade Guide
-
-## Upgrading to v3.0
-
-> **⚠️ IMPORTANT**: v3.0 requires a fresh start. There is no automated migration from v2.x to v3.0.
-
-### Why No Migration?
-
-v3.0 introduces fundamental changes to the application architecture:
-- **Authentication**: Switched from JWT to Better Auth
-- **Database**: Now uses Drizzle ORM with proper migrations
-- **Security**: All tokens are now encrypted
-- **Features**: Added SSO support and OIDC provider functionality
-
-Due to these extensive changes, we recommend starting fresh with v3.0 for the best experience.
-
-### Upgrade Steps
-
-1. **Stop your v2.x container**
-   ```bash
-   docker stop gitea-mirror
-   docker rm gitea-mirror
-   ```
-
-2. **Backup your v2.x data (optional)**
-   ```bash
-   # If you want to keep your v2 data for reference
-   docker run --rm -v gitea-mirror-data:/data -v $(pwd):/backup alpine tar czf /backup/gitea-mirror-v2-backup.tar.gz -C /data .
-   ```
-
-3. **Create a new volume for v3**
-   ```bash
-   docker volume create gitea-mirror-v3-data
-   ```
-
-4. **Run v3 with the new volume**
-   ```bash
-   docker run -d \
-     --name gitea-mirror \
-     -p 4321:4321 \
-     -v gitea-mirror-v3-data:/app/data \
-     -e BETTER_AUTH_SECRET=your-secret-key \
-     -e ENCRYPTION_SECRET=your-encryption-key \
-     arunavo4/gitea-mirror:latest
-   ```
-
-5. **Set up your configuration again**
-   - Navigate to http://localhost:4321
-   - Create a new admin account
-   - Re-enter your GitHub and Gitea credentials
-   - Configure your mirror settings
-
-### What Happens to My Existing Mirrors?
-
-Your existing mirrors in Gitea are **not affected**. The application will:
-- Recognize existing repositories when you re-import
-- Skip creating duplicates
-- Resume normal mirror operations
-
-### Environment Variable Changes
-
-v3.0 uses different environment variables:
-
-| v2.x | v3.0 | Notes |
-|------|------|-------|
-| `JWT_SECRET` | `BETTER_AUTH_SECRET` | Required for session management |
-| - | `ENCRYPTION_SECRET` | New - required for token encryption |
-
-### Need Help?
-
-If you have questions about upgrading:
-1. Check the [README](README.md) for v3 setup instructions
-2. Review your v2 configuration before upgrading
-3. Open an issue if you encounter problems

bun.lock

@@ -8,7 +8,7 @@
         "@astrojs/mdx": "4.3.7",
         "@astrojs/node": "9.5.0",
         "@astrojs/react": "^4.4.0",
-        "@better-auth/sso": "^1.3.28",
+        "@better-auth/sso": "1.4.0-beta.12",
         "@octokit/plugin-throttling": "^11.0.2",
         "@octokit/rest": "^22.0.0",
         "@radix-ui/react-accordion": "^1.2.12",
@@ -36,7 +36,8 @@
         "@types/react-dom": "^19.2.2",
         "astro": "^5.14.8",
         "bcryptjs": "^3.0.2",
-        "better-auth": "^1.3.28",
+        "better-auth": "1.4.0-beta.12",
+        "buffer": "^6.0.3",
         "canvas-confetti": "^1.9.3",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
@@ -149,11 +150,11 @@
 
     "@babel/types": ["@babel/types@7.28.4", "", { "dependencies": { "@babel/helper-string-parser": "^7.27.1", "@babel/helper-validator-identifier": "^7.27.1" } }, "sha512-bkFqkLhh3pMBUQQkpVgWDWq/lqzc2678eUyDlTBhRqhCHFguYYGM0Efga7tYk4TogG/3x0EEl66/OQ+WGbWB/Q=="],
 
-    "@better-auth/core": ["@better-auth/core@1.3.28", "", { "dependencies": { "zod": "^4.1.5" }, "peerDependencies": { "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.18", "better-call": "1.0.19", "better-sqlite3": "^12.4.1", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1" } }, "sha512-iZOGKlXaNEIEj0Q3z7+REE94I89YUJ0sel/1pvm1qqdHkm59G+ToTysHtyTcLYby3+UtAeJRKyFAY0nwJH0H7A=="],
+    "@better-auth/core": ["@better-auth/core@1.4.0-beta.12", "", { "dependencies": { "zod": "^4.1.5" }, "peerDependencies": { "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.18", "better-call": "1.0.24", "better-sqlite3": "^12.4.1", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1" } }, "sha512-2GisAGuSVZS4gtnwP5Owk3RyC6GevZe9zcODTrtbwRCvBTrHUmu0j6bcklK9uNG8DaWDmzCK1+VGA5qIHzg5Pw=="],
 
-    "@better-auth/sso": ["@better-auth/sso@1.3.28", "", { "dependencies": { "@better-fetch/fetch": "1.1.18", "fast-xml-parser": "^5.2.5", "jose": "^6.1.0", "oauth2-mock-server": "^7.2.1", "samlify": "^2.10.1", "zod": "^4.1.5" }, "peerDependencies": { "better-auth": "1.3.28" } }, "sha512-BeuQFB/tWKR3Nx89fiD6e0Ei5VoKmman0VDBkoOIu+P3PGdSSzvbmBUTZi8aao+tAPoD6/Z5gje+oiQBDAnp4w=="],
+    "@better-auth/sso": ["@better-auth/sso@1.4.0-beta.12", "", { "dependencies": { "@better-fetch/fetch": "1.1.18", "fast-xml-parser": "^5.2.5", "jose": "^6.1.0", "oauth2-mock-server": "^7.2.1", "samlify": "^2.10.1", "zod": "^4.1.5" }, "peerDependencies": { "better-auth": "1.4.0-beta.12" } }, "sha512-iuRuy59J3yXQihZJ34rqYClWyuVjSkxuBkdFblccKbOhNy7pmRO1lfmBMpyeth3ET5Cp0PDVV/z1XBbDcQp0LA=="],
 
-    "@better-auth/telemetry": ["@better-auth/telemetry@1.3.28", "", { "dependencies": { "@better-auth/core": "1.3.28", "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.18" } }, "sha512-qZtV82IFuyQZc2c37VkiDgO/qfqPnJuWIyeC/iFK1AA5N8RSuC2+CVIH1sNDytPXUAthbYeOzcOCW2YEkgz1Ow=="],
+    "@better-auth/telemetry": ["@better-auth/telemetry@1.4.0-beta.12", "", { "dependencies": { "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.18" }, "peerDependencies": { "@better-auth/core": "1.4.0-beta.12" } }, "sha512-pQ5HITRGXMHQPcPCDnz0xlxFqqxvpD4kQMvY6cdt1vDsPVePHAj9R3S318XEfaw3NAgtw3af/wCN6eBt2u4Kew=="],
 
     "@better-auth/utils": ["@better-auth/utils@0.3.0", "", {}, "sha512-W+Adw6ZA6mgvnSnhOki270rwJ42t4XzSK6YWGF//BbVXL6SwCLWfyzBc1lN2m/4RM28KubdBKQ4X5VMoLRNPQw=="],
 
@@ -697,9 +698,9 @@
 
     "before-after-hook": ["before-after-hook@4.0.0", "", {}, "sha512-q6tR3RPqIB1pMiTRMFcZwuG5T8vwp+vUvEG0vuI6B+Rikh5BfPp2fQ82c925FOs+b0lcFQ8CFrL+KbilfZFhOQ=="],
 
-    "better-auth": ["better-auth@1.3.28", "", { "dependencies": { "@better-auth/core": "1.3.28", "@better-auth/telemetry": "1.3.28", "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.18", "@noble/ciphers": "^2.0.0", "@noble/hashes": "^2.0.0", "@simplewebauthn/browser": "^13.1.2", "@simplewebauthn/server": "^13.1.2", "better-call": "1.0.19", "defu": "^6.1.4", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1", "zod": "^4.1.5" } }, "sha512-fSaeRsTSkzCSSKREFsm7z7TsTMC8ghGrwCN+mumxCZiyc8Fh/UThUwURlTJmsR0YVB0DMR8ejQH+c38WhdQslQ=="],
+    "better-auth": ["better-auth@1.4.0-beta.12", "", { "dependencies": { "@better-auth/core": "1.4.0-beta.12", "@better-auth/telemetry": "1.4.0-beta.12", "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.18", "@noble/ciphers": "^2.0.0", "@noble/hashes": "^2.0.0", "@simplewebauthn/browser": "^13.1.2", "@simplewebauthn/server": "^13.1.2", "better-call": "1.0.24", "defu": "^6.1.4", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1", "zod": "^4.1.5" } }, "sha512-IvrSBmQkHgOinDh6JyJCoKwbMPmHpkmt98/0hBU9Nc0s7Y7u72AOx1Z35J2dRQxxX4SzvFQ9pHqlV6wPnm72Ww=="],
 
-    "better-call": ["better-call@1.0.19", "", { "dependencies": { "@better-auth/utils": "^0.3.0", "@better-fetch/fetch": "^1.1.4", "rou3": "^0.5.1", "set-cookie-parser": "^2.7.1", "uncrypto": "^0.1.3" } }, "sha512-sI3GcA1SCVa3H+CDHl8W8qzhlrckwXOTKhqq3OOPXjgn5aTOMIqGY34zLY/pHA6tRRMjTUC3lz5Mi7EbDA24Kw=="],
+    "better-call": ["better-call@1.0.24", "", { "dependencies": { "@better-auth/utils": "^0.3.0", "@better-fetch/fetch": "^1.1.4", "rou3": "^0.5.1", "set-cookie-parser": "^2.7.1", "uncrypto": "^0.1.3" } }, "sha512-iGqL29cstPp4xLD2MjKL1EmyAqQHjYS+cBMt4W27rPs3vf+kuqkVPA0NYaf7JciBOzVsJdNj4cbZWXC5TardWQ=="],
 
     "better-sqlite3": ["better-sqlite3@12.4.1", "", { "dependencies": { "bindings": "^1.5.0", "prebuild-install": "^7.1.1" } }, "sha512-3yVdyZhklTiNrtg+4WqHpJpFDd+WHTg2oM7UcR80GqL05AOV0xEJzc6qNvFYoEtE+hRp1n9MpN6/+4yhlGkDXQ=="],
 
@@ -719,7 +720,7 @@
 
     "browserslist": ["browserslist@4.24.5", "", { "dependencies": { "caniuse-lite": "^1.0.30001716", "electron-to-chromium": "^1.5.149", "node-releases": "^2.0.19", "update-browserslist-db": "^1.1.3" }, "bin": { "browserslist": "cli.js" } }, "sha512-FDToo4Wo82hIdgc1CQ+NQD0hEhmpPjrZ3hiUgwgOG6IuTdlpr8jdjyG24P6cNP1yJpTLzS5OcGgSw0xmDU1/Tw=="],
 
-    "buffer": ["buffer@5.7.1", "", { "dependencies": { "base64-js": "^1.3.1", "ieee754": "^1.1.13" } }, "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ=="],
+    "buffer": ["buffer@6.0.3", "", { "dependencies": { "base64-js": "^1.3.1", "ieee754": "^1.2.1" } }, "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA=="],
 
     "buffer-equal-constant-time": ["buffer-equal-constant-time@1.0.1", "", {}, "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA=="],
 
@@ -1925,6 +1926,8 @@
 
     "basic-auth/safe-buffer": ["safe-buffer@5.1.2", "", {}, "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="],
 
+    "bl/buffer": ["buffer@5.7.1", "", { "dependencies": { "base64-js": "^1.3.1", "ieee754": "^1.1.13" } }, "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ=="],
+
     "body-parser/debug": ["debug@2.6.9", "", { "dependencies": { "ms": "2.0.0" } }, "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA=="],
 
     "body-parser/iconv-lite": ["iconv-lite@0.4.24", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3" } }, "sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA=="],

docker-compose.alt.yml

@@ -26,6 +26,10 @@ services:
       - HOST=0.0.0.0
       - PORT=4321
       - PUBLIC_BETTER_AUTH_URL=${PUBLIC_BETTER_AUTH_URL:-http://localhost:4321}
+      # Optional concurrency controls (defaults match in-app defaults)
+      # If you want perfect ordering of issues and PRs, set these at 1
+      - MIRROR_ISSUE_CONCURRENCY=${MIRROR_ISSUE_CONCURRENCY:-3}
+      - MIRROR_PULL_REQUEST_CONCURRENCY=${MIRROR_PULL_REQUEST_CONCURRENCY:-5}
       
     healthcheck:
       test: ["CMD", "wget", "--no-verbose", "--tries=3", "--spider", "http://localhost:4321/api/health"]

docker-compose.yml

@@ -47,6 +47,8 @@ services:
       - PRESERVE_ORG_STRUCTURE=${PRESERVE_ORG_STRUCTURE:-false}
       - ONLY_MIRROR_ORGS=${ONLY_MIRROR_ORGS:-false}
       - SKIP_STARRED_ISSUES=${SKIP_STARRED_ISSUES:-false}
+      - MIRROR_ISSUE_CONCURRENCY=${MIRROR_ISSUE_CONCURRENCY:-3}
+      - MIRROR_PULL_REQUEST_CONCURRENCY=${MIRROR_PULL_REQUEST_CONCURRENCY:-5}
       - GITEA_URL=${GITEA_URL:-}
       - GITEA_TOKEN=${GITEA_TOKEN:-}
       - GITEA_USERNAME=${GITEA_USERNAME:-}

docs/BETTER_AUTH_MIGRATION.md

@@ -1,175 +0,0 @@
-# Better Auth Migration Guide
-
-This document describes the migration from the legacy authentication system to Better Auth.
-
-## Overview
-
-Gitea Mirror has been migrated to use Better Auth, a modern authentication library that provides:
-- Built-in support for email/password authentication
-- Session management with secure cookies
-- Database adapter with Drizzle ORM
-- Ready for OAuth2, OIDC, and SSO integrations
-- Type-safe authentication throughout the application
-
-## Key Changes
-
-### 1. Database Schema
-
-New tables added:
-- `sessions` - User session management
-- `accounts` - Authentication providers (credentials, OAuth, etc.)
-- `verification_tokens` - Email verification and password reset tokens
-
-Modified tables:
-- `users` - Added `emailVerified` field
-
-### 2. Authentication Flow
-
-**Login:**
-- Users now log in with email instead of username
-- Endpoint: `/api/auth/sign-in/email`
-- Session cookies are automatically managed
-
-**Registration:**
-- Users register with username, email, and password
-- Username is stored as an additional field
-- Endpoint: `/api/auth/sign-up/email`
-
-### 3. API Routes
-
-All auth routes are now handled by Better Auth's catch-all handler:
-- `/api/auth/[...all].ts` handles all authentication endpoints
-
-Legacy routes have been backed up to `/src/pages/api/auth/legacy-backup/`
-
-### 4. Session Management
-
-Sessions are now managed by Better Auth:
-- Middleware automatically populates `context.locals.user` and `context.locals.session`
-- Use `useAuth()` hook in React components for client-side auth
-- Sessions expire after 30 days by default
-
-## Future OIDC/SSO Configuration
-
-The project is now ready for OIDC and SSO integrations. To enable:
-
-### 1. Enable SSO Plugin
-
-```typescript
-// src/lib/auth.ts
-import { sso } from "better-auth/plugins/sso";
-
-export const auth = betterAuth({
-  // ... existing config
-  plugins: [
-    sso({
-      provisionUser: async (data) => {
-        // Custom user provisioning logic
-        return data;
-      },
-    }),
-  ],
-});
-```
-
-### 2. Register OIDC Providers
-
-```typescript
-// Example: Register an OIDC provider
-await authClient.sso.register({
-  issuer: "https://idp.example.com",
-  domain: "example.com",
-  clientId: "your-client-id",
-  clientSecret: "your-client-secret",
-  providerId: "example-provider",
-});
-```
-
-### 3. Enable OIDC Provider Mode
-
-To make Gitea Mirror act as an OIDC provider:
-
-```typescript
-// src/lib/auth.ts
-import { oidcProvider } from "better-auth/plugins/oidc";
-
-export const auth = betterAuth({
-  // ... existing config
-  plugins: [
-    oidcProvider({
-      loginPage: "/signin",
-      consentPage: "/oauth/consent",
-      metadata: {
-        issuer: process.env.BETTER_AUTH_URL || "http://localhost:3000",
-      },
-    }),
-  ],
-});
-```
-
-### 4. Database Migration for SSO
-
-When enabling SSO/OIDC, run migrations to add required tables:
-
-```bash
-# Generate the schema
-bun drizzle-kit generate
-
-# Apply the migration
-bun drizzle-kit migrate
-```
-
-New tables that will be added:
-- `sso_providers` - SSO provider configurations
-- `oauth_applications` - OAuth2 client applications
-- `oauth_access_tokens` - OAuth2 access tokens
-- `oauth_consents` - User consent records
-
-## Environment Variables
-
-Required environment variables:
-
-```env
-# Better Auth configuration
-BETTER_AUTH_SECRET=your-secret-key
-BETTER_AUTH_URL=http://localhost:3000
-
-# Legacy (kept for compatibility)
-JWT_SECRET=your-secret-key
-```
-
-## Migration Script
-
-To migrate existing users to Better Auth:
-
-```bash
-bun run migrate:better-auth
-```
-
-This script:
-1. Creates credential accounts for existing users
-2. Moves password hashes to the accounts table
-3. Preserves user creation dates
-
-## Troubleshooting
-
-### Login Issues
-- Ensure users log in with email, not username
-- Check that BETTER_AUTH_SECRET is set
-- Verify database migrations have been applied
-
-### Session Issues
-- Clear browser cookies if experiencing session problems
-- Check middleware is properly configured
-- Ensure auth routes are accessible at `/api/auth/*`
-
-### Development Tips
-- Use `bun db:studio` to inspect database tables
-- Check `/api/auth/session` to verify current session
-- Enable debug logging in Better Auth for troubleshooting
-
-## Resources
-
-- [Better Auth Documentation](https://better-auth.com)
-- [Better Auth Astro Integration](https://better-auth.com/docs/integrations/astro)
-- [Better Auth Plugins](https://better-auth.com/docs/plugins)

docs/BUILD_GUIDE.md

@@ -1,206 +0,0 @@
-# Build Guide
-
-This guide covers building the open-source version of Gitea Mirror.
-
-## Prerequisites
-
-- **Bun** >= 1.2.9 (primary runtime)
-- **Node.js** >= 20 (for compatibility)
-- **Git**
-
-## Quick Start
-
-```bash
-# Clone repository
-git clone https://github.com/yourusername/gitea-mirror.git
-cd gitea-mirror
-
-# Install dependencies
-bun install
-
-# Initialize database
-bun run init-db
-
-# Build for production
-bun run build
-
-# Start the application
-bun run start
-```
-
-## Build Commands
-
-| Command | Description |
-|---------|-------------|
-| `bun run build` | Production build |
-| `bun run dev` | Development server |
-| `bun run preview` | Preview production build |
-| `bun test` | Run tests |
-| `bun run cleanup-db` | Remove database files |
-
-## Build Output
-
-The build creates:
-- `dist/` - Production-ready server files
-- `.astro/` - Build cache (git-ignored)
-- `data/` - SQLite database location
-
-## Development Build
-
-For active development with hot reload:
-
-```bash
-bun run dev
-```
-
-Access the application at http://localhost:4321
-
-## Production Build
-
-```bash
-# Build
-bun run build
-
-# Test the build
-bun run preview
-
-# Run in production
-bun run start
-```
-
-## Docker Build
-
-```dockerfile
-# Build Docker image
-docker build -t gitea-mirror:latest .
-
-# Run container
-docker run -p 3000:3000 gitea-mirror:latest
-```
-
-## Environment Variables
-
-Create a `.env` file:
-
-```env
-# Database
-DATABASE_PATH=./data/gitea-mirror.db
-
-# Authentication
-JWT_SECRET=your-secret-here
-
-# GitHub Configuration
-GITHUB_TOKEN=ghp_...
-GITHUB_WEBHOOK_SECRET=...
-GITHUB_EXCLUDED_ORGS=org1,org2,org3  # Optional: Comma-separated list of organizations to exclude from sync
-
-# Gitea Configuration
-GITEA_URL=https://your-gitea.com
-GITEA_TOKEN=...
-```
-
-## Common Build Issues
-
-### Missing Dependencies
-
-```bash
-# Solution
-bun install
-```
-
-### Database Not Initialized
-
-```bash
-# Solution
-bun run init-db
-```
-
-### Port Already in Use
-
-```bash
-# Change port
-PORT=3001 bun run dev
-```
-
-### Build Cache Issues
-
-```bash
-# Clear cache
-rm -rf .astro/ dist/
-bun run build
-```
-
-## Build Optimization
-
-### Development Speed
-
-- Use `bun run dev` for hot reload
-- Skip type checking during rapid development
-- Keep `.astro/` cache between builds
-
-### Production Optimization
-
-- Minification enabled automatically
-- Tree shaking removes unused code
-- Image optimization with Sharp
-
-## Validation
-
-After building, verify:
-
-```bash
-# Check build output
-ls -la dist/
-
-# Test server starts
-bun run start
-
-# Check health endpoint
-curl http://localhost:3000/api/health
-```
-
-## CI/CD Build
-
-Example GitHub Actions workflow:
-
-```yaml
-name: Build and Test
-on: [push, pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install
-      - run: bun run build
-      - run: bun test
-```
-
-## Troubleshooting
-
-### Build Fails
-
-1. Check Bun version: `bun --version`
-2. Clear dependencies: `rm -rf node_modules && bun install`
-3. Check for syntax errors: `bunx tsc --noEmit`
-
-### Runtime Errors
-
-1. Check environment variables
-2. Verify database exists
-3. Check file permissions
-
-## Performance
-
-Expected build times:
-- Clean build: ~5-10 seconds
-- Incremental build: ~2-5 seconds
-- Development startup: ~1-2 seconds
-
-## Next Steps
-
-- Configure with [Configuration Guide](./CONFIGURATION.md)
-- Deploy with [Deployment Guide](./DEPLOYMENT.md)
-- Set up authentication with [SSO Guide](./SSO-OIDC-SETUP.md)

docs/CA_CERTIFICATES.md

@@ -1 +0,0 @@
-../certs/README.md

docs/DEVELOPMENT_WORKFLOW.md

@@ -16,27 +16,22 @@ This guide covers the development workflow for the open-source Gitea Mirror.
 
 1. **Clone the repository**:
 ```bash
-git clone https://github.com/yourusername/gitea-mirror.git
+git clone https://github.com/RayLabsHQ/gitea-mirror.git
 cd gitea-mirror
 ```
 
-2. **Install dependencies**:
+2. **Install dependencies and seed the SQLite database**:
 ```bash
-bun install
+bun run setup
 ```
 
-3. **Initialize database**:
-```bash
-bun run init-db
-```
-
-4. **Configure environment**:
+3. **Configure environment (optional)**:
 ```bash
 cp .env.example .env
 # Edit .env with your settings
 ```
 
-5. **Start development server**:
+4. **Start the development server**:
 ```bash
 bun run dev
 ```
@@ -45,29 +40,33 @@ bun run dev
 
 | Command | Description |
 |---------|-------------|
-| `bun run dev` | Start development server with hot reload |
-| `bun run build` | Build for production |
-| `bun run preview` | Preview production build |
-| `bun test` | Run all tests |
+| `bun run dev` | Start the Bun + Astro dev server with hot reload |
+| `bun run build` | Build the production bundle |
+| `bun run preview` | Preview the production build locally |
+| `bun test` | Run the Bun test suite |
 | `bun test:watch` | Run tests in watch mode |
-| `bun run db:studio` | Open database GUI |
+| `bun run db:studio` | Launch Drizzle Kit Studio |
 
 ## Project Structure
 
 ```
 gitea-mirror/
-├── src/
-│   ├── components/      # React components
-│   ├── pages/          # Astro pages & API routes
-│   ├── lib/            # Core logic
-│   │   ├── db/         # Database queries
-│   │   ├── utils/      # Helper functions
-│   │   └── modules/    # Module system
-│   ├── hooks/          # React hooks
-│   └── types/          # TypeScript types
-├── public/             # Static assets
-├── scripts/            # Utility scripts
-└── tests/              # Test files
+├── src/                     # Application UI, API routes, and services
+│   ├── components/          # React components rendered inside Astro pages
+│   ├── pages/               # Astro pages and API routes (e.g., /api/*)
+│   ├── lib/                 # Core logic: GitHub/Gitea clients, scheduler, recovery, db helpers
+│   │   ├── db/              # Drizzle adapter + schema
+│   │   ├── modules/         # Module wiring (jobs, integrations)
+│   │   └── utils/           # Shared utilities
+│   ├── hooks/               # React hooks
+│   ├── content/             # In-app documentation and templated content
+│   ├── layouts/             # Shared layout components
+│   ├── styles/              # Tailwind CSS entrypoints
+│   └── types/               # TypeScript types
+├── scripts/                 # Bun scripts for DB management and maintenance
+├── www/                     # Marketing site (Astro + MDX use cases)
+├── public/                  # Static assets served by Vite/Astro
+└── tests/                   # Dedicated integration/unit test helpers
 ```
 
 ## Feature Development
@@ -80,10 +79,10 @@ git checkout -b feature/my-feature
 ```
 
 2. **Plan your changes**:
-- UI components in `/src/components/`
-- API endpoints in `/src/pages/api/`
-- Database queries in `/src/lib/db/queries/`
-- Types in `/src/types/`
+- UI components live in `src/components/`
+- API endpoints live in `src/pages/api/`
+- Database logic is under `src/lib/db/` (schema + adapter)
+- Shared types are in `src/types/`
 
 3. **Implement the feature**:
 
@@ -120,7 +119,7 @@ describe('My Feature', () => {
 
 5. **Update documentation**:
 - Add JSDoc comments
-- Update README if needed
+- Update README/docs if needed
 - Document API changes
 
 ## Database Development

docs/ENVIRONMENT_VARIABLES.md

@@ -141,6 +141,10 @@ Control what content gets mirrored from GitHub to Gitea.
 | `MIRROR_PULL_REQUESTS` | Mirror pull requests (requires MIRROR_METADATA=true) | `false` | `true`, `false` |
 | `MIRROR_LABELS` | Mirror labels (requires MIRROR_METADATA=true) | `false` | `true`, `false` |
 | `MIRROR_MILESTONES` | Mirror milestones (requires MIRROR_METADATA=true) | `false` | `true`, `false` |
+| `MIRROR_ISSUE_CONCURRENCY` | Number of issues processed in parallel. Set above `1` to speed up mirroring at the risk of out-of-order creation. | `3` | Integer ≥ 1 |
+| `MIRROR_PULL_REQUEST_CONCURRENCY` | Number of pull requests processed in parallel. Values above `1` may cause ordering differences. | `5` | Integer ≥ 1 |
+
+> **Ordering vs Throughput:** Metadata now mirrors sequentially by default to preserve chronology. Increase the concurrency variables only if you can tolerate minor out-of-order entries.
 
 ## Automation Configuration
 

docs/EXTENDING.md

@@ -1,77 +0,0 @@
-# Extending Gitea Mirror
-
-Gitea Mirror is designed with extensibility in mind through a module system.
-
-## Module System
-
-The application provides a module interface that allows extending functionality:
-
-```typescript
-export interface Module {
-  name: string;
-  version: string;
-  init(app: AppContext): Promise<void>;
-  cleanup?(): Promise<void>;
-}
-```
-
-## Creating Custom Modules
-
-You can create custom modules to add features:
-
-```typescript
-// my-module.ts
-export class MyModule implements Module {
-  name = 'my-module';
-  version = '1.0.0';
-
-  async init(app: AppContext) {
-    // Add your functionality
-    app.addRoute('/api/my-endpoint', this.handler);
-  }
-
-  async handler(context) {
-    return new Response('Hello from my module!');
-  }
-}
-```
-
-## Module Context
-
-Modules receive an `AppContext` with:
-- Database access
-- Event system
-- Route registration
-- Configuration
-
-## Private Extensions
-
-If you're developing private extensions:
-
-1. Create a separate package/repository
-2. Implement the module interface
-3. Use Bun's linking feature for development:
-   ```bash
-   # In your extension
-   bun link
-   
-   # In gitea-mirror
-   bun link your-extension
-   ```
-
-## Best Practices
-
-- Keep modules focused on a single feature
-- Use TypeScript for type safety
-- Handle errors gracefully
-- Clean up resources in `cleanup()`
-- Document your module's API
-
-## Community Modules
-
-Share your modules with the community:
-- Create a GitHub repository
-- Tag it with `gitea-mirror-module`
-- Submit a PR to list it in our docs
-
-For more details on the module system, see the source code in `/src/lib/modules/`.

docs/README.md

@@ -1,118 +1,39 @@
 # Gitea Mirror Documentation
 
-Welcome to the Gitea Mirror documentation. This guide covers everything you need to know about developing, building, and deploying the open-source version of Gitea Mirror.
+This folder contains engineering and operations references for the open-source Gitea Mirror project. Each guide focuses on the parts of the system that still require bespoke explanation beyond the in-app help and the main `README.md`.
 
-## Documentation Overview
+## Available Guides
 
-### Getting Started
+### Core workflow
+- **[DEVELOPMENT_WORKFLOW.md](./DEVELOPMENT_WORKFLOW.md)** – Set up a local environment, run scripts, and understand the repo layout (app + marketing site).
+- **[ENVIRONMENT_VARIABLES.md](./ENVIRONMENT_VARIABLES.md)** – Complete reference for every configuration flag supported by the app and Docker images.
 
-- **[Development Workflow](./DEVELOPMENT_WORKFLOW.md)** - Set up your development environment and start contributing
-- **[Build Guide](./BUILD_GUIDE.md)** - Build Gitea Mirror from source
-- **[Configuration Guide](./CONFIGURATION.md)** - Configure all available options
+### Reliability & recovery
+- **[GRACEFUL_SHUTDOWN.md](./GRACEFUL_SHUTDOWN.md)** – How signal handling, shutdown coordination, and job persistence work in v3.
+- **[RECOVERY_IMPROVEMENTS.md](./RECOVERY_IMPROVEMENTS.md)** – Deep dive into the startup recovery workflow and supporting scripts.
 
-### Deployment
+### Authentication
+- **[SSO-OIDC-SETUP.md](./SSO-OIDC-SETUP.md)** – Configure OIDC/SSO providers through the admin UI.
+- **[SSO_TESTING.md](./SSO_TESTING.md)** – Recipes for local and staging SSO testing (Google, Keycloak, mock providers).
 
-- **[Deployment Guide](./DEPLOYMENT.md)** - Deploy to production environments
-- **[Docker Guide](./DOCKER.md)** - Container-based deployment
-- **[Reverse Proxy Setup](./REVERSE_PROXY.md)** - Configure with nginx/Caddy
+If you are looking for customer-facing playbooks, see the MDX use cases under `www/src/pages/use-cases/`.
 
-### Features
+## Quick start for local development
 
-- **[SSO/OIDC Setup](./SSO-OIDC-SETUP.md)** - Configure authentication providers
-- **[Sponsor Integration](./SPONSOR_INTEGRATION.md)** - GitHub Sponsors integration
-- **[Webhook Configuration](./WEBHOOKS.md)** - Set up GitHub webhooks
-
-### Architecture
-
-- **[Architecture Overview](./ARCHITECTURE.md)** - System design and components
-- **[API Documentation](./API.md)** - REST API endpoints
-- **[Database Schema](./DATABASE.md)** - SQLite structure
-
-### Maintenance
-
-- **[Migration Guide](../MIGRATION_GUIDE.md)** - Upgrade from previous versions
-- **[Better Auth Migration](./BETTER_AUTH_MIGRATION.md)** - Migrate authentication system
-- **[Troubleshooting](./TROUBLESHOOTING.md)** - Common issues and solutions
-- **[Backup & Restore](./BACKUP.md)** - Data management
-
-## Quick Start
-
-1. **Clone and install**:
 ```bash
-git clone https://github.com/yourusername/gitea-mirror.git
+git clone https://github.com/RayLabsHQ/gitea-mirror.git
 cd gitea-mirror
-bun install
+bun run setup           # installs deps and seeds the SQLite DB
+bun run dev             # starts the Astro/Bun app on http://localhost:4321
 ```
 
-2. **Configure**:
-```bash
-cp .env.example .env
-# Edit .env with your GitHub and Gitea tokens
-```
+The first user you create locally becomes the administrator. All other configuration—GitHub owners, Gitea targets, scheduling, cleanup—is done through the **Configuration** screen in the UI.
 
-3. **Initialize and run**:
-```bash
-bun run init-db
-bun run dev
-```
+## Contributing & support
 
-4. **Access**: Open http://localhost:4321
+- 🎯 Contribution guide: [../CONTRIBUTING.md](../CONTRIBUTING.md)
+- 📘 Code of conduct: [../CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)
+- 🐞 Issues & feature requests: <https://github.com/RayLabsHQ/gitea-mirror/issues>
+- 💬 Discussions: <https://github.com/RayLabsHQ/gitea-mirror/discussions>
 
-## Key Features
-
-- 🔄 **Automatic Syncing** - Keep repositories synchronized
-- 🗂️ **Organization Support** - Mirror entire organizations
-- ⭐ **Starred Repos** - Mirror your starred repositories
-- 🔐 **Self-Hosted** - Full control over your data
-- 🚀 **Fast** - Built with Bun for optimal performance
-- 🔒 **Secure** - JWT authentication, encrypted tokens
-
-## Technology Stack
-
-- **Runtime**: Bun
-- **Framework**: Astro with React
-- **Database**: SQLite with Drizzle ORM
-- **Styling**: Tailwind CSS v4
-- **Authentication**: Better Auth
-
-## System Requirements
-
-- Bun >= 1.2.9
-- Node.js >= 20 (optional, for compatibility)
-- SQLite 3
-- 512MB RAM minimum
-- 1GB disk space
-
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md) for details.
-
-### Development Setup
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Submit a pull request
-
-### Code of Conduct
-
-Please read our [Code of Conduct](../CODE_OF_CONDUCT.md) before contributing.
-
-## Support
-
-- **Issues**: [GitHub Issues](https://github.com/yourusername/gitea-mirror/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/yourusername/gitea-mirror/discussions)
-- **Wiki**: [GitHub Wiki](https://github.com/yourusername/gitea-mirror/wiki)
-
-## Security
-
-For security issues, please see [SECURITY.md](../SECURITY.md).
-
-## License
-
-Gitea Mirror is open source software licensed under the [MIT License](../LICENSE).
-
----
-
-For detailed information on any topic, please refer to the specific documentation guides listed above.
+Security disclosures should follow the process in [../SECURITY.md](../SECURITY.md).

docs/SHUTDOWN_PROCESS.md

@@ -1,236 +0,0 @@
-# Graceful Shutdown Process
-
-This document details how the gitea-mirror application handles graceful shutdown during active mirroring operations, with specific focus on job interruption and recovery.
-
-## Overview
-
-The graceful shutdown system is designed for **fast, clean termination** without waiting for long-running jobs to complete. It prioritizes **quick shutdown times** (under 30 seconds) while **preserving all progress** for seamless recovery.
-
-## Key Principle
-
-**The application does NOT wait for jobs to finish before shutting down.** Instead, it saves the current state and resumes after restart.
-
-## Shutdown Scenario Example
-
-### Initial State
-- **Job**: Mirror 500 repositories
-- **Progress**: 200 repositories completed
-- **Remaining**: 300 repositories pending
-- **Action**: User initiates shutdown (SIGTERM, Ctrl+C, Docker stop)
-
-### Shutdown Process (Under 30 seconds)
-
-#### Step 1: Signal Detection (Immediate)
-```
-📡 Received SIGTERM signal
-🛑 Graceful shutdown initiated by signal: SIGTERM
-📊 Shutdown status: 1 active jobs, 2 callbacks
-```
-
-#### Step 2: Job State Saving (1-10 seconds)
-```
-📝 Step 1: Saving active job states...
-Saving state for job abc-123...
-✅ Saved state for job abc-123
-```
-
-**What gets saved:**
-- `inProgress: false` - Mark job as not currently running
-- `completedItems: 200` - Number of repos successfully mirrored
-- `totalItems: 500` - Total repos in the job
-- `completedItemIds: [repo1, repo2, ..., repo200]` - List of completed repos
-- `itemIds: [repo1, repo2, ..., repo500]` - Full list of repos
-- `lastCheckpoint: 2025-05-24T17:30:00Z` - Exact shutdown time
-- `message: "Job interrupted by application shutdown - will resume on restart"`
-- `status: "imported"` - Keeps status as resumable (not "failed")
-
-#### Step 3: Service Cleanup (1-5 seconds)
-```
-🔧 Step 2: Executing shutdown callbacks...
-🛑 Shutting down cleanup service...
-✅ Cleanup service stopped
-✅ Shutdown callback 1 completed
-```
-
-#### Step 4: Clean Exit (Immediate)
-```
-💾 Step 3: Closing database connections...
-✅ Graceful shutdown completed successfully
-```
-
-**Total shutdown time: ~15 seconds** (well under the 30-second limit)
-
-## What Happens to the Remaining 300 Repos?
-
-### During Shutdown
-- **NOT processed** - The remaining 300 repos are not mirrored
-- **NOT lost** - Their IDs are preserved in the job state
-- **NOT marked as failed** - Job status remains "imported" for recovery
-
-### After Restart
-The recovery system automatically:
-
-1. **Detects interrupted job** during startup
-2. **Calculates remaining work**: 500 - 200 = 300 repos
-3. **Extracts remaining repo IDs**: repos 201-500 from the original list
-4. **Resumes processing** from exactly where it left off
-5. **Continues until completion** of all 500 repos
-
-## Timeout Configuration
-
-### Shutdown Timeouts
-```typescript
-const SHUTDOWN_TIMEOUT = 30000; // 30 seconds max shutdown time
-const JOB_SAVE_TIMEOUT = 10000; // 10 seconds to save job state
-```
-
-### Timeout Behavior
-- **Normal case**: Shutdown completes in 10-20 seconds
-- **Slow database**: Up to 30 seconds allowed
-- **Timeout exceeded**: Force exit with code 1
-- **Container kill**: Orchestrator should allow 45+ seconds grace period
-
-## Job State Persistence
-
-### Database Schema
-The `mirror_jobs` table stores complete job state:
-
-```sql
--- Job identification
-id TEXT PRIMARY KEY,
-user_id TEXT NOT NULL,
-job_type TEXT NOT NULL DEFAULT 'mirror',
-
--- Progress tracking  
-total_items INTEGER,
-completed_items INTEGER DEFAULT 0,
-item_ids TEXT, -- JSON array of all repo IDs
-completed_item_ids TEXT DEFAULT '[]', -- JSON array of completed repo IDs
-
--- State management
-in_progress INTEGER NOT NULL DEFAULT 0, -- Boolean: currently running
-started_at TIMESTAMP,
-completed_at TIMESTAMP,
-last_checkpoint TIMESTAMP, -- Last progress save
-
--- Status and messaging
-status TEXT NOT NULL DEFAULT 'imported',
-message TEXT NOT NULL
-```
-
-### Recovery Query
-The recovery system finds interrupted jobs:
-
-```sql
-SELECT * FROM mirror_jobs 
-WHERE in_progress = 0 
-  AND status = 'imported' 
-  AND completed_at IS NULL
-  AND total_items > completed_items;
-```
-
-## Shutdown-Aware Processing
-
-### Concurrency Check
-During job execution, each repo processing checks for shutdown:
-
-```typescript
-// Before processing each repository
-if (isShuttingDown()) {
-  throw new Error('Processing interrupted by application shutdown');
-}
-```
-
-### Checkpoint Intervals
-Jobs save progress periodically (every 10 repos by default):
-
-```typescript
-checkpointInterval: 10, // Save progress every 10 repositories
-```
-
-This ensures minimal work loss even if shutdown occurs between checkpoints.
-
-## Container Integration
-
-### Docker Entrypoint
-The Docker entrypoint properly forwards signals:
-
-```bash
-# Set up signal handlers
-trap 'shutdown_handler' TERM INT HUP
-
-# Start application in background
-bun ./dist/server/entry.mjs &
-APP_PID=$!
-
-# Wait for application to finish
-wait "$APP_PID"
-```
-
-### Kubernetes Configuration
-Recommended pod configuration:
-
-```yaml
-apiVersion: v1
-kind: Pod
-spec:
-  terminationGracePeriodSeconds: 45  # Allow time for graceful shutdown
-  containers:
-  - name: gitea-mirror
-    # ... other configuration
-```
-
-## Monitoring and Logging
-
-### Shutdown Logs
-```
-🛑 Graceful shutdown initiated by signal: SIGTERM
-📊 Shutdown status: 1 active jobs, 2 callbacks
-📝 Step 1: Saving active job states...
-Saving state for 1 active jobs...
-✅ Completed saving all active jobs
-🔧 Step 2: Executing shutdown callbacks...
-✅ Completed all shutdown callbacks  
-💾 Step 3: Closing database connections...
-✅ Graceful shutdown completed successfully
-```
-
-### Recovery Logs
-```
-⚠️  Jobs found that need recovery. Starting recovery process...
-Resuming job abc-123 with 300 remaining items...
-✅ Recovery completed successfully
-```
-
-## Best Practices
-
-### For Operations
-1. **Monitor shutdown times** - Should complete under 30 seconds
-2. **Check recovery logs** - Verify jobs resume correctly after restart
-3. **Set appropriate grace periods** - Allow 45+ seconds in orchestrators
-4. **Plan maintenance windows** - Jobs will resume but may take time to complete
-
-### For Development
-1. **Test shutdown scenarios** - Use `bun run test-shutdown`
-2. **Monitor job progress** - Check checkpoint frequency and timing
-3. **Verify recovery** - Ensure interrupted jobs resume correctly
-4. **Handle edge cases** - Test shutdown during different job phases
-
-## Troubleshooting
-
-### Shutdown Takes Too Long
-- **Check**: Database performance during job state saving
-- **Solution**: Increase `SHUTDOWN_TIMEOUT` environment variable
-- **Monitor**: Job complexity and checkpoint frequency
-
-### Jobs Don't Resume
-- **Check**: Recovery logs for errors during startup
-- **Verify**: Database contains interrupted jobs with correct status
-- **Test**: Run `bun run startup-recovery` manually
-
-### Container Force-Killed
-- **Check**: Container orchestrator termination grace period
-- **Increase**: Grace period to 45+ seconds
-- **Monitor**: Application shutdown completion time
-
-This design ensures **production-ready graceful shutdown** with **zero data loss** and **fast recovery times** suitable for modern containerized deployments.

docs/SPONSOR_INTEGRATION.md

@@ -1,91 +0,0 @@
-# GitHub Sponsors Integration
-
-This guide shows how GitHub Sponsors is integrated into the open-source version of Gitea Mirror.
-
-## Components
-
-### GitHubSponsors Card
-
-A card component that displays in the sidebar or dashboard:
-
-```tsx
-import { GitHubSponsors } from '@/components/sponsors/GitHubSponsors';
-
-// In your layout or dashboard
-<GitHubSponsors />
-```
-
-### SponsorButton
-
-A smaller button for headers or navigation:
-
-```tsx
-import { SponsorButton } from '@/components/sponsors/GitHubSponsors';
-
-// In your header
-<SponsorButton />
-```
-
-## Integration Points
-
-### 1. Dashboard Sidebar
-
-Add the sponsor card to the dashboard sidebar for visibility:
-
-```tsx
-// src/components/layout/DashboardLayout.tsx
-<aside>
-  {/* Other sidebar content */}
-  <GitHubSponsors />
-</aside>
-```
-
-### 2. Header Navigation
-
-Add the sponsor button to the main navigation:
-
-```tsx
-// src/components/layout/Header.tsx
-<nav>
-  {/* Other nav items */}
-  <SponsorButton />
-</nav>
-```
-
-### 3. Settings Page
-
-Add a support section in settings:
-
-```tsx
-// src/components/settings/SupportSection.tsx
-<Card>
-  <CardHeader>
-    <CardTitle>Support Development</CardTitle>
-  </CardHeader>
-  <CardContent>
-    <GitHubSponsors />
-  </CardContent>
-</Card>
-```
-
-## Behavior
-
-- **Only appears in self-hosted mode**: The components automatically hide in hosted mode
-- **Non-intrusive**: Designed to be helpful without being annoying
-- **Multiple options**: GitHub Sponsors, Buy Me a Coffee, and starring the repo
-
-## Customization
-
-You can customize the sponsor components by:
-
-1. Updating the GitHub Sponsors URL
-2. Adding/removing donation platforms
-3. Changing the styling to match your theme
-4. Adjusting the placement based on user feedback
-
-## Best Practices
-
-1. **Don't be pushy**: Show sponsor options tastefully
-2. **Provide value first**: Ensure the tool is useful before asking for support
-3. **Be transparent**: Explain how sponsorships help the project
-4. **Thank sponsors**: Acknowledge supporters in README or releases

docs/testing.md

@@ -1,127 +0,0 @@
-# Testing in Gitea Mirror
-
-This document provides guidance on testing in the Gitea Mirror project.
-
-## Current Status
-
-The project now uses Bun's built-in test runner, which is Jest-compatible and provides a fast, reliable testing experience. We've migrated away from Vitest due to compatibility issues with Bun.
-
-## Running Tests
-
-To run tests, use the following commands:
-
-```bash
-# Run all tests
-bun test
-
-# Run tests in watch mode (automatically re-run when files change)
-bun test --watch
-
-# Run tests with coverage reporting
-bun test --coverage
-```
-
-## Test File Naming Conventions
-
-Bun's test runner automatically discovers test files that match the following patterns:
-
-- `*.test.{js|jsx|ts|tsx}`
-- `*_test.{js|jsx|ts|tsx}`
-- `*.spec.{js|jsx|ts|tsx}`
-- `*_spec.{js|jsx|ts|tsx}`
-
-## Writing Tests
-
-The project uses Bun's test runner with a Jest-compatible API. Here's an example test:
-
-```typescript
-// example.test.ts
-import { describe, test, expect } from "bun:test";
-
-describe("Example Test", () => {
-  test("should pass", () => {
-    expect(true).toBe(true);
-  });
-});
-```
-
-### Testing React Components
-
-For testing React components, we use React Testing Library:
-
-```typescript
-// component.test.tsx
-import { describe, test, expect } from "bun:test";
-import { render, screen } from "@testing-library/react";
-import MyComponent from "../components/MyComponent";
-
-describe("MyComponent", () => {
-  test("renders correctly", () => {
-    render(<MyComponent />);
-    expect(screen.getByText("Hello World")).toBeInTheDocument();
-  });
-});
-```
-
-## Test Setup
-
-The test setup is defined in `src/tests/setup.bun.ts` and includes:
-
-- Automatic cleanup after each test
-- Setup for any global test environment needs
-
-## Mocking
-
-Bun's test runner provides built-in mocking capabilities:
-
-```typescript
-import { test, expect, mock } from "bun:test";
-
-// Create a mock function
-const mockFn = mock(() => "mocked value");
-
-test("mock function", () => {
-  const result = mockFn();
-  expect(result).toBe("mocked value");
-  expect(mockFn).toHaveBeenCalled();
-});
-
-// Mock a module
-mock.module("./some-module", () => {
-  return {
-    someFunction: () => "mocked module function"
-  };
-});
-```
-
-## CI Integration
-
-The CI workflow has been updated to use Bun's test runner. Tests are automatically run as part of the CI pipeline.
-
-## Test Coverage
-
-To generate test coverage reports, run:
-
-```bash
-bun test --coverage
-```
-
-This will generate a coverage report in the `coverage` directory.
-
-## Types of Tests
-
-The project includes several types of tests:
-
-1. **Unit Tests**: Testing individual functions and utilities
-2. **API Tests**: Testing API endpoints
-3. **Component Tests**: Testing React components
-4. **Integration Tests**: Testing how components work together
-
-## Future Improvements
-
-When expanding the test suite, consider:
-
-1. Adding more comprehensive API endpoint tests
-2. Increasing component test coverage
-3. Setting up end-to-end tests with a tool like Playwright
-4. Adding performance tests for critical paths

helm/gitea-mirror/README.md

@@ -29,7 +29,7 @@ kubectl create namespace gitea-mirror
 helm upgrade --install gitea-mirror ./helm/gitea-mirror   --namespace gitea-mirror   --set "gitea-mirror.github.username=<your-gh-username>"   --set "gitea-mirror.github.token=<your-gh-token>"   --set "gitea-mirror.gitea.url=https://gitea.example.com"   --set "gitea-mirror.gitea.token=<your-gitea-token>"
 ```
 
-The default Service is `ClusterIP` on port `8080`. You can expose it via Ingress or Gateway API; see below.
+The default Service is `ClusterIP` on port `4321`. You can expose it via Ingress or Gateway API; see below.
 
 ---
 
@@ -78,7 +78,7 @@ If you enabled persistence with a PVC the data may persist; delete the PVC manua
 
 | Key | Type | Default | Description |
 | --- | --- | --- | --- |
-| `deployment.port` | int | `8080` | Container port & named `http` port. |
+| `deployment.port` | int | `4321` | Container port & named `http` port. |
 | `deployment.strategy.type` | string | `Recreate` | Update strategy (`Recreate` or `RollingUpdate`). |
 | `deployment.strategy.rollingUpdate.maxUnavailable/maxSurge` | string/int | — | Used when `type=RollingUpdate`. |
 | `deployment.env` | list | `[]` | Extra environment variables. |
@@ -95,7 +95,7 @@ If you enabled persistence with a PVC the data may persist; delete the PVC manua
 | Key | Type | Default | Description |
 | --- | --- | --- | --- |
 | `service.type` | string | `ClusterIP` | Service type. |
-| `service.port` | int | `8080` | Service port. |
+| `service.port` | int | `4321` | Service port. |
 | `service.clusterIP` | string | `None` | ClusterIP (only when `type=ClusterIP`). |
 | `service.externalTrafficPolicy` | string | `""` | External traffic policy (LB). |
 | `service.loadBalancerIP` | string | `""` | LoadBalancer IP. |
@@ -228,7 +228,7 @@ ingress:
         - mirror.example.com
 ```
 
-This creates an Ingress routing `/` to the service on port `8080`.
+This creates an Ingress routing `/` to the service on port `4321`.
 
 ### Using Gateway API (HTTPRoute)
 
@@ -257,7 +257,7 @@ By default, the chart provisions a PVC named `gitea-mirror-storage` with `1Gi` a
 
 ## Environment & health endpoints
 
-The container listens on `PORT` (defaults to `deployment.port` = `8080`) and exposes `GET /api/health` for liveness/readiness/startup probes.
+The container listens on `PORT` (defaults to `deployment.port` = `4321`) and exposes `GET /api/health` for liveness/readiness/startup probes.
 
 ---
 

helm/gitea-mirror/values.yaml

@@ -46,7 +46,7 @@ route:
 
 service:
   type: ClusterIP
-  port: 8080
+  port: 4321
   clusterIP: None
   annotations: {}
   externalTrafficPolicy:
@@ -55,7 +55,7 @@ service:
   loadBalancerClass:
 
 deployment:
-  port: 8080
+  port: 4321
   strategy:
     type: Recreate
   env: []

package.json

@@ -1,7 +1,7 @@
 {
   "name": "gitea-mirror",
   "type": "module",
-  "version": "3.8.6",
+  "version": "3.8.9",
   "engines": {
     "bun": ">=1.2.9"
   },
@@ -46,7 +46,7 @@
     "@astrojs/mdx": "4.3.7",
     "@astrojs/node": "9.5.0",
     "@astrojs/react": "^4.4.0",
-    "@better-auth/sso": "^1.3.28",
+    "@better-auth/sso": "1.4.0-beta.12",
     "@octokit/plugin-throttling": "^11.0.2",
     "@octokit/rest": "^22.0.0",
     "@radix-ui/react-accordion": "^1.2.12",
@@ -74,7 +74,8 @@
     "@types/react-dom": "^19.2.2",
     "astro": "^5.14.8",
     "bcryptjs": "^3.0.2",
-    "better-auth": "^1.3.28",
+    "buffer": "^6.0.3",
+    "better-auth": "1.4.0-beta.12",
     "canvas-confetti": "^1.9.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

src/components/dashboard/Dashboard.tsx

@@ -306,7 +306,7 @@ export function Dashboard() {
           title="Repositories"
           value={repoCount}
           icon={<GitFork className="h-4 w-4" />}
-          description="Total in mirror queue"
+          description="Total imported repositories"
         />
         <StatusCard
           title="Mirrored"

src/lib/auth-client.ts

@@ -1,3 +1,4 @@
+import "@/lib/polyfills/buffer";
 import { createAuthClient } from "better-auth/react";
 import { oidcClient } from "better-auth/client/plugins";
 import { ssoClient } from "@better-auth/sso/client";

src/lib/db/schema.ts

@@ -54,6 +54,8 @@ export const giteaConfigSchema = z.object({
     .enum(["skip", "reference", "full-copy"])
     .default("reference"),
   // Mirror options
+  issueConcurrency: z.number().int().min(1).default(3),
+  pullRequestConcurrency: z.number().int().min(1).default(5),
   mirrorReleases: z.boolean().default(false),
   releaseLimit: z.number().default(10),
   mirrorMetadata: z.boolean().default(false),

src/lib/env-config-loader.ts

@@ -49,6 +49,9 @@ interface EnvConfig {
     mirrorLabels?: boolean;
     mirrorMilestones?: boolean;
     mirrorMetadata?: boolean;
+    releaseLimit?: number;
+    issueConcurrency?: number;
+    pullRequestConcurrency?: number;
   };
   schedule: {
     enabled?: boolean;
@@ -136,6 +139,8 @@ function parseEnvConfig(): EnvConfig {
       mirrorMilestones: process.env.MIRROR_MILESTONES === 'true',
       mirrorMetadata: process.env.MIRROR_METADATA === 'true',
       releaseLimit: process.env.RELEASE_LIMIT ? parseInt(process.env.RELEASE_LIMIT, 10) : undefined,
+      issueConcurrency: process.env.MIRROR_ISSUE_CONCURRENCY ? parseInt(process.env.MIRROR_ISSUE_CONCURRENCY, 10) : undefined,
+      pullRequestConcurrency: process.env.MIRROR_PULL_REQUEST_CONCURRENCY ? parseInt(process.env.MIRROR_PULL_REQUEST_CONCURRENCY, 10) : undefined,
     },
     schedule: {
       enabled: process.env.SCHEDULE_ENABLED === 'true' || 
@@ -277,6 +282,12 @@ export async function initializeConfigFromEnv(): Promise<void> {
       // Mirror metadata options
       mirrorReleases: envConfig.mirror.mirrorReleases ?? existingConfig?.[0]?.giteaConfig?.mirrorReleases ?? false,
       releaseLimit: envConfig.mirror.releaseLimit ?? existingConfig?.[0]?.giteaConfig?.releaseLimit ?? 10,
+      issueConcurrency: envConfig.mirror.issueConcurrency && envConfig.mirror.issueConcurrency > 0
+        ? envConfig.mirror.issueConcurrency
+        : existingConfig?.[0]?.giteaConfig?.issueConcurrency ?? 3,
+      pullRequestConcurrency: envConfig.mirror.pullRequestConcurrency && envConfig.mirror.pullRequestConcurrency > 0
+        ? envConfig.mirror.pullRequestConcurrency
+        : existingConfig?.[0]?.giteaConfig?.pullRequestConcurrency ?? 5,
       mirrorMetadata: envConfig.mirror.mirrorMetadata ?? (envConfig.mirror.mirrorIssues || envConfig.mirror.mirrorPullRequests || envConfig.mirror.mirrorLabels || envConfig.mirror.mirrorMilestones) ?? existingConfig?.[0]?.giteaConfig?.mirrorMetadata ?? false,
       mirrorIssues: envConfig.mirror.mirrorIssues ?? existingConfig?.[0]?.giteaConfig?.mirrorIssues ?? false,
       mirrorPullRequests: envConfig.mirror.mirrorPullRequests ?? existingConfig?.[0]?.giteaConfig?.mirrorPullRequests ?? false,

src/lib/gitea.ts

@@ -12,6 +12,7 @@ import { createMirrorJob } from "./helpers";
 import { db, organizations, repositories } from "./db";
 import { eq, and } from "drizzle-orm";
 import { decryptConfigTokens } from "./utils/config-encryption";
+import { formatDateShort } from "./utils";
 
 /**
  * Helper function to get organization configuration including destination override
@@ -1558,6 +1559,8 @@ export const mirrorGitRepoIssuesToGitea = async ({
       repo,
       state: "all",
       per_page: 100,
+      sort: "created",
+      direction: "asc",
     },
     (res) => res.data
   );
@@ -1590,6 +1593,18 @@ export const mirrorGitRepoIssuesToGitea = async ({
   // Import the processWithRetry function
   const { processWithRetry } = await import("@/lib/utils/concurrency");
 
+  const rawIssueConcurrency = config.giteaConfig?.issueConcurrency ?? 3;
+  const issueConcurrencyLimit =
+    Number.isFinite(rawIssueConcurrency)
+      ? Math.max(1, Math.floor(rawIssueConcurrency))
+      : 1;
+
+  if (issueConcurrencyLimit > 1) {
+    console.warn(
+      `[Issues] Concurrency is set to ${issueConcurrencyLimit}. This may lead to out-of-order issue creation in Gitea but is faster.`
+    );
+  }
+
   // Process issues in parallel with concurrency control
   await processWithRetry(
     filteredIssues,
@@ -1632,11 +1647,15 @@ export const mirrorGitRepoIssuesToGitea = async ({
               .join(", ")} on GitHub.`
           : "";
 
+      const issueAuthor = issue.user?.login ?? "unknown";
+      const issueCreatedOn = formatDateShort(issue.created_at);
+      const issueOriginHeader = `Originally created by @${issueAuthor} on GitHub${
+        issueCreatedOn ? ` (${issueCreatedOn})` : ""
+      }.`;
+
       const issuePayload: any = {
         title: issue.title,
-        body: `Originally created by @${
-          issue.user?.login
-        } on GitHub.${originalAssignees}\n\n${issue.body || ""}`,
+        body: `${issueOriginHeader}${originalAssignees}\n\n${issue.body ?? ""}`,
         closed: issue.state === "closed",
         labels: giteaLabelIds,
       };
@@ -1662,15 +1681,30 @@ export const mirrorGitRepoIssuesToGitea = async ({
         (res) => res.data
       );
 
-      // Process comments in parallel with concurrency control
-      if (comments.length > 0) {
+      // Ensure comments are applied in chronological order to preserve discussion flow
+      const sortedComments = comments
+        .slice()
+        .sort(
+          (a, b) =>
+            new Date(a.created_at || 0).getTime() -
+            new Date(b.created_at || 0).getTime()
+        );
+
+      // Process comments sequentially to preserve historical ordering
+      if (sortedComments.length > 0) {
         await processWithRetry(
-          comments,
+          sortedComments,
           async (comment) => {
+            const commenter = comment.user?.login ?? "unknown";
+            const commentDate = formatDateShort(comment.created_at);
+            const commentHeader = `@${commenter} commented on GitHub${
+              commentDate ? ` (${commentDate})` : ""
+            }:`;
+
             await httpPost(
               `${config.giteaConfig!.url}/api/v1/repos/${giteaOwner}/${repoName}/issues/${createdIssue.data.number}/comments`,
               {
-                body: `@${comment.user?.login} commented on GitHub:\n\n${comment.body}`,
+                body: `${commentHeader}\n\n${comment.body ?? ""}`,
               },
               {
                 Authorization: `token ${decryptedConfig.giteaConfig!.token}`,
@@ -1679,7 +1713,7 @@ export const mirrorGitRepoIssuesToGitea = async ({
             return comment;
           },
           {
-            concurrencyLimit: 5,
+            concurrencyLimit: 1,
             maxRetries: 2,
             retryDelay: 1000,
             onRetry: (_comment, error, attempt) => {
@@ -1694,7 +1728,7 @@ export const mirrorGitRepoIssuesToGitea = async ({
       return issue;
     },
     {
-      concurrencyLimit: 3, // Process 3 issues at a time
+      concurrencyLimit: issueConcurrencyLimit,
       maxRetries: 2,
       retryDelay: 2000,
       onProgress: (completed, total, result) => {
@@ -1966,6 +2000,8 @@ export async function mirrorGitRepoPullRequestsToGitea({
       repo,
       state: "all",
       per_page: 100,
+      sort: "created",
+      direction: "asc",
     },
     (res) => res.data
   );
@@ -2022,6 +2058,18 @@ export async function mirrorGitRepoPullRequestsToGitea({
 
   const { processWithRetry } = await import("@/lib/utils/concurrency");
 
+  const rawPullConcurrency = config.giteaConfig?.pullRequestConcurrency ?? 5;
+  const pullRequestConcurrencyLimit =
+    Number.isFinite(rawPullConcurrency)
+      ? Math.max(1, Math.floor(rawPullConcurrency))
+      : 1;
+
+  if (pullRequestConcurrencyLimit > 1) {
+    console.warn(
+      `[Pull Requests] Concurrency is set to ${pullRequestConcurrencyLimit}. This may lead to out-of-order pull request mirroring in Gitea.`
+    );
+  }
+
   let successCount = 0;
   let failedCount = 0;
 
@@ -2144,7 +2192,7 @@ export async function mirrorGitRepoPullRequestsToGitea({
       }
     },
     {
-      concurrencyLimit: 5,
+      concurrencyLimit: pullRequestConcurrencyLimit,
       maxRetries: 3,
       retryDelay: 1000,
     }

src/lib/polyfills/buffer.ts

@@ -0,0 +1,5 @@
+import { Buffer } from "buffer";
+
+if (typeof globalThis !== "undefined" && (globalThis as any).Buffer === undefined) {
+  (globalThis as any).Buffer = Buffer;
+}

src/lib/sso/oidc-config.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "bun:test";
+import { normalizeOidcProviderConfig, OidcConfigError } from "./oidc-config";
+
+const issuer = "https://auth.example.com";
+
+describe("normalizeOidcProviderConfig", () => {
+  it("returns provided endpoints when complete", async () => {
+    const result = await normalizeOidcProviderConfig(issuer, {
+      clientId: "client",
+      clientSecret: "secret",
+      authorizationEndpoint: "https://auth.example.com/auth",
+      tokenEndpoint: "https://auth.example.com/token",
+      jwksEndpoint: "https://auth.example.com/jwks",
+      userInfoEndpoint: "https://auth.example.com/userinfo",
+      scopes: ["openid", "email"],
+      pkce: false,
+    }, async () => {
+      throw new Error("fetch should not be called when endpoints are provided");
+    });
+
+    expect(result.oidcConfig.authorizationEndpoint).toBe("https://auth.example.com/auth");
+    expect(result.oidcConfig.tokenEndpoint).toBe("https://auth.example.com/token");
+    expect(result.oidcConfig.jwksEndpoint).toBe("https://auth.example.com/jwks");
+    expect(result.oidcConfig.userInfoEndpoint).toBe("https://auth.example.com/userinfo");
+    expect(result.oidcConfig.scopes).toEqual(["openid", "email"]);
+    expect(result.oidcConfig.pkce).toBe(false);
+  });
+
+  it("derives missing fields from discovery", async () => {
+    const fetchMock = async () =>
+      new Response(JSON.stringify({
+        authorization_endpoint: "https://auth.example.com/auth",
+        token_endpoint: "https://auth.example.com/token",
+        jwks_uri: "https://auth.example.com/jwks",
+        userinfo_endpoint: "https://auth.example.com/userinfo",
+        scopes_supported: ["openid", "email", "profile"],
+      }));
+
+    const result = await normalizeOidcProviderConfig(issuer, {
+      clientId: "client",
+      clientSecret: "secret",
+    }, fetchMock);
+
+    expect(result.oidcConfig.authorizationEndpoint).toBe("https://auth.example.com/auth");
+    expect(result.oidcConfig.tokenEndpoint).toBe("https://auth.example.com/token");
+    expect(result.oidcConfig.jwksEndpoint).toBe("https://auth.example.com/jwks");
+    expect(result.oidcConfig.userInfoEndpoint).toBe("https://auth.example.com/userinfo");
+    expect(result.oidcConfig.scopes).toEqual(["openid", "email", "profile"]);
+  });
+
+  it("throws for invalid issuer URL", async () => {
+    await expect(
+      normalizeOidcProviderConfig("not-a-url", {}),
+    ).rejects.toBeInstanceOf(OidcConfigError);
+  });
+});

src/lib/sso/oidc-config.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+
+const DEFAULT_SCOPES = ["openid", "email", "profile"] as const;
+const DISCOVERY_TIMEOUT_MS = 10000;
+
+const discoverySchema = z.object({
+  issuer: z.string().url().optional(),
+  authorization_endpoint: z.string().url().optional(),
+  token_endpoint: z.string().url().optional(),
+  userinfo_endpoint: z.string().url().optional(),
+  jwks_uri: z.string().url().optional(),
+  scopes_supported: z.array(z.string()).optional(),
+});
+
+export class OidcConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OidcConfigError";
+  }
+}
+
+export type RawOidcConfig = {
+  clientId?: string;
+  clientSecret?: string;
+  authorizationEndpoint?: string;
+  tokenEndpoint?: string;
+  jwksEndpoint?: string;
+  userInfoEndpoint?: string;
+  discoveryEndpoint?: string;
+  scopes?: string[];
+  pkce?: boolean;
+  mapping?: ProviderMapping;
+};
+
+export type ProviderMapping = {
+  id: string;
+  email: string;
+  emailVerified?: string;
+  name?: string;
+  image?: string;
+  firstName?: string;
+  lastName?: string;
+};
+
+export type NormalizedOidcConfig = {
+  oidcConfig: {
+    clientId?: string;
+    clientSecret?: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    jwksEndpoint?: string;
+    userInfoEndpoint?: string;
+    discoveryEndpoint: string;
+    scopes: string[];
+    pkce: boolean;
+  };
+  mapping: ProviderMapping;
+};
+
+type FetchFn = typeof fetch;
+
+function cleanUrl(value: string | undefined, field: string): string | undefined {
+  if (!value || typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  try {
+    return new URL(trimmed).toString();
+  } catch {
+    throw new OidcConfigError(`Invalid ${field} URL: ${value}`);
+  }
+}
+
+function sanitizeScopes(scopes: string[] | undefined, fallback: readonly string[]): string[] {
+  const candidates = Array.isArray(scopes) ? scopes : [];
+  const sanitized = candidates
+    .map(scope => scope?.trim())
+    .filter((scope): scope is string => Boolean(scope));
+
+  if (sanitized.length === 0) {
+    return [...fallback];
+  }
+
+  return Array.from(new Set(sanitized));
+}
+
+async function fetchDiscoveryDocument(url: string, fetchFn: FetchFn): Promise<z.infer<typeof discoverySchema>> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), DISCOVERY_TIMEOUT_MS);
+
+  try {
+    const response = await fetchFn(url, {
+      signal: controller.signal,
+      headers: { Accept: "application/json" },
+    });
+
+    if (!response.ok) {
+      throw new OidcConfigError(`OIDC discovery request failed (${response.status} ${response.statusText})`);
+    }
+
+    let payload: unknown;
+    try {
+      payload = await response.json();
+    } catch {
+      throw new OidcConfigError("OIDC discovery response is not valid JSON");
+    }
+
+    const parsed = discoverySchema.parse(payload);
+    if (!parsed.authorization_endpoint || !parsed.token_endpoint) {
+      throw new OidcConfigError("OIDC discovery document is missing required endpoints");
+    }
+    return parsed;
+  } catch (error) {
+    if (error instanceof OidcConfigError) {
+      throw error;
+    }
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new OidcConfigError(`OIDC discovery timed out after ${DISCOVERY_TIMEOUT_MS / 1000}s`);
+    }
+    throw new OidcConfigError(`Failed to fetch OIDC discovery document: ${error instanceof Error ? error.message : "unknown error"}`);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+export async function normalizeOidcProviderConfig(
+  issuer: string,
+  rawConfig: RawOidcConfig,
+  fetchFn: FetchFn = fetch,
+): Promise<NormalizedOidcConfig> {
+  if (!issuer || typeof issuer !== "string") {
+    throw new OidcConfigError("Issuer is required");
+  }
+
+  let normalizedIssuer: string;
+  try {
+    const issuerUrl = new URL(issuer.trim());
+    normalizedIssuer = issuerUrl.toString().replace(/\/$/, "");
+  } catch {
+    throw new OidcConfigError(`Invalid issuer URL: ${issuer}`);
+  }
+
+  const discoveryEndpoint = cleanUrl(
+    rawConfig.discoveryEndpoint,
+    "discovery endpoint",
+  ) ?? `${normalizedIssuer}/.well-known/openid-configuration`;
+
+  const authorizationEndpoint = cleanUrl(rawConfig.authorizationEndpoint, "authorization endpoint");
+  const tokenEndpoint = cleanUrl(rawConfig.tokenEndpoint, "token endpoint");
+  const jwksEndpoint = cleanUrl(rawConfig.jwksEndpoint, "JWKS endpoint");
+  const userInfoEndpoint = cleanUrl(rawConfig.userInfoEndpoint, "userinfo endpoint");
+  const providedScopes = Array.isArray(rawConfig.scopes) ? rawConfig.scopes : undefined;
+  let scopes = sanitizeScopes(providedScopes, DEFAULT_SCOPES);
+
+  const shouldFetchDiscovery =
+    !authorizationEndpoint ||
+    !tokenEndpoint ||
+    !jwksEndpoint ||
+    !userInfoEndpoint ||
+    !providedScopes ||
+    providedScopes.length === 0;
+
+  let resolvedAuthorization = authorizationEndpoint;
+  let resolvedToken = tokenEndpoint;
+  let resolvedJwks = jwksEndpoint;
+  let resolvedUserInfo = userInfoEndpoint;
+
+  if (shouldFetchDiscovery) {
+    const discovery = await fetchDiscoveryDocument(discoveryEndpoint, fetchFn);
+    resolvedAuthorization = resolvedAuthorization ?? discovery.authorization_endpoint;
+    resolvedToken = resolvedToken ?? discovery.token_endpoint;
+    resolvedJwks = resolvedJwks ?? discovery.jwks_uri;
+    resolvedUserInfo = resolvedUserInfo ?? discovery.userinfo_endpoint;
+    if (!providedScopes || providedScopes.length === 0) {
+      scopes = sanitizeScopes(discovery.scopes_supported, DEFAULT_SCOPES);
+    }
+  }
+
+  if (!resolvedAuthorization || !resolvedToken) {
+    throw new OidcConfigError("OIDC configuration must include authorization and token endpoints");
+  }
+
+  return {
+    oidcConfig: {
+      clientId: rawConfig.clientId,
+      clientSecret: rawConfig.clientSecret,
+      authorizationEndpoint: resolvedAuthorization,
+      tokenEndpoint: resolvedToken,
+      jwksEndpoint: resolvedJwks,
+      userInfoEndpoint: resolvedUserInfo,
+      discoveryEndpoint,
+      scopes,
+      pkce: rawConfig.pkce !== false,
+    },
+    mapping: rawConfig.mapping ?? {
+      id: "sub",
+      email: "email",
+      emailVerified: "email_verified",
+      name: "name",
+      image: "picture",
+    },
+  };
+}

src/lib/utils.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "bun:test";
-import { jsonResponse, formatDate, truncate, safeParse, parseErrorMessage, showErrorToast } from "./utils";
+import { jsonResponse, formatDate, formatDateShort, truncate, safeParse, parseErrorMessage, showErrorToast } from "./utils";
 
 describe("jsonResponse", () => {
   test("creates a Response with JSON content", () => {
@@ -65,6 +65,18 @@ describe("formatDate", () => {
   });
 });
 
+describe("formatDateShort", () => {
+  test("returns formatted date when input is provided", () => {
+    const formatted = formatDateShort("2014-10-20T15:32:10Z");
+    expect(formatted).toBe("Oct 20, 2014");
+  });
+
+  test("returns undefined when date is missing", () => {
+    expect(formatDateShort(null)).toBeUndefined();
+    expect(formatDateShort(undefined)).toBeUndefined();
+  });
+});
+
 describe("truncate", () => {
   test("truncates a string that exceeds the length", () => {
     const str = "This is a long string that needs truncation";

src/lib/utils.ts

@@ -29,6 +29,15 @@ export function formatDate(date?: Date | string | null): string {
   }).format(new Date(date));
 }
 
+export function formatDateShort(date?: Date | string | null): string | undefined {
+  if (!date) return undefined;
+  return new Intl.DateTimeFormat("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  }).format(new Date(date));
+}
+
 export function formatLastSyncTime(date: Date | string | null): string {
   if (!date) return "Never";
   

src/lib/utils/config-defaults.ts

@@ -86,6 +86,8 @@ export async function createDefaultConfig({ userId, envOverrides = {} }: Default
       addTopics: true,
       preserveVisibility: false,
       forkStrategy: "reference",
+      issueConcurrency: 3,
+      pullRequestConcurrency: 5,
     },
     include: [],
     exclude: [],

src/lib/utils/config-mapper.ts

@@ -89,6 +89,8 @@ export function mapUiToDbConfig(
     forkStrategy: advancedOptions.skipForks ? "skip" : "reference",
     
     // Mirror options from UI
+    issueConcurrency: giteaConfig.issueConcurrency ?? 3,
+    pullRequestConcurrency: giteaConfig.pullRequestConcurrency ?? 5,
     mirrorReleases: mirrorOptions.mirrorReleases,
     releaseLimit: mirrorOptions.releaseLimit || 10,
     mirrorMetadata: mirrorOptions.mirrorMetadata,
@@ -132,6 +134,8 @@ export function mapDbToUiConfig(dbConfig: any): {
     preserveOrgStructure: dbConfig.giteaConfig?.preserveVisibility || false, // Map preserveVisibility
     mirrorStrategy: dbConfig.githubConfig?.mirrorStrategy || "preserve", // Get from GitHub config
     personalReposOrg: undefined, // Not stored in current schema
+    issueConcurrency: dbConfig.giteaConfig?.issueConcurrency ?? 3,
+    pullRequestConcurrency: dbConfig.giteaConfig?.pullRequestConcurrency ?? 5,
   };
 
   // Map mirror options from various database fields

src/pages/api/auth/sso/register.ts

@@ -2,6 +2,10 @@ import type { APIContext } from "astro";
 import { createSecureErrorResponse } from "@/lib/utils";
 import { requireAuth } from "@/lib/utils/auth-helpers";
 import { auth } from "@/lib/auth";
+import { db, ssoProviders } from "@/lib/db";
+import { eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { normalizeOidcProviderConfig, OidcConfigError } from "@/lib/sso/oidc-config";
 
 // POST /api/auth/sso/register - Register a new SSO provider using Better Auth
 export async function POST(context: APIContext) {
@@ -104,43 +108,37 @@ export async function POST(context: APIContext) {
         userInfoEndpoint,
         scopes,
         pkce = true,
-        mapping = {
-          id: "sub",
-          email: "email",
-          emailVerified: "email_verified",
-          name: "name",
-          image: "picture",
-        }
+        mapping,
       } = body;
 
-      // Use provided scopes or default if not specified
-      const finalScopes = scopes || ["openid", "email", "profile"];
+      try {
+        const normalized = await normalizeOidcProviderConfig(validatedIssuer, {
+          clientId,
+          clientSecret,
+          authorizationEndpoint,
+          tokenEndpoint,
+          jwksEndpoint,
+          userInfoEndpoint,
+          discoveryEndpoint,
+          scopes,
+          pkce,
+          mapping,
+        });
 
-      // Validate endpoint URLs if provided
-      const validateUrl = (url: string | undefined, name: string): string | undefined => {
-        if (!url) return undefined;
-        if (typeof url !== 'string' || url.trim() === '') return undefined;
-        try {
-          const validatedUrl = new URL(url.trim());
-          return validatedUrl.toString();
-        } catch (e) {
-          console.warn(`Invalid ${name} URL: ${url}, skipping`);
-          return undefined;
+        registrationBody.oidcConfig = normalized.oidcConfig;
+        registrationBody.mapping = normalized.mapping;
+      } catch (error) {
+        if (error instanceof OidcConfigError) {
+          return new Response(
+            JSON.stringify({ error: error.message }),
+            {
+              status: 400,
+              headers: { "Content-Type": "application/json" },
+            }
+          );
         }
-      };
-
-      registrationBody.oidcConfig = {
-        clientId: clientId || undefined,
-        clientSecret: clientSecret || undefined,
-        authorizationEndpoint: validateUrl(authorizationEndpoint, 'authorization endpoint'),
-        tokenEndpoint: validateUrl(tokenEndpoint, 'token endpoint'),
-        jwksEndpoint: validateUrl(jwksEndpoint, 'JWKS endpoint'),
-        discoveryEndpoint: validateUrl(discoveryEndpoint, 'discovery endpoint'),
-        userInfoEndpoint: validateUrl(userInfoEndpoint, 'userinfo endpoint'),
-        scopes: finalScopes,
-        pkce,
-      };
-      registrationBody.mapping = mapping;
+        throw error;
+      }
     }
 
     // Get the user's auth headers to make the request
@@ -169,6 +167,51 @@ export async function POST(context: APIContext) {
 
     const result = await response.json();
 
+    // Mirror provider entry into local SSO table for UI listing
+    try {
+      const existing = await db
+        .select()
+        .from(ssoProviders)
+        .where(eq(ssoProviders.providerId, registrationBody.providerId))
+        .limit(1);
+
+      const values: any = {
+        issuer: registrationBody.issuer,
+        domain: registrationBody.domain,
+        organizationId: registrationBody.organizationId,
+        updatedAt: new Date(),
+      };
+
+      if (registrationBody.oidcConfig) {
+        values.oidcConfig = JSON.stringify({
+          ...registrationBody.oidcConfig,
+          mapping: registrationBody.mapping,
+        });
+      }
+
+      if (existing.length > 0) {
+        await db
+          .update(ssoProviders)
+          .set(values)
+          .where(eq(ssoProviders.id, existing[0].id));
+      } else {
+        await db.insert(ssoProviders).values({
+          id: nanoid(),
+          issuer: registrationBody.issuer,
+          domain: registrationBody.domain,
+          oidcConfig: JSON.stringify({
+            ...registrationBody.oidcConfig,
+            mapping: registrationBody.mapping,
+          }),
+          userId: user.id,
+          providerId: registrationBody.providerId,
+          organizationId: registrationBody.organizationId,
+        });
+      }
+    } catch (mirroringError) {
+      console.warn("Failed to mirror SSO provider to local DB:", mirroringError);
+    }
+
     return new Response(JSON.stringify(result), {
       status: 201,
       headers: { "Content-Type": "application/json" },

src/pages/api/sso/providers.ts

@@ -4,6 +4,7 @@ import { requireAuth } from "@/lib/utils/auth-helpers";
 import { db, ssoProviders } from "@/lib/db";
 import { nanoid } from "nanoid";
 import { eq } from "drizzle-orm";
+import { normalizeOidcProviderConfig, OidcConfigError, type RawOidcConfig } from "@/lib/sso/oidc-config";
 
 // GET /api/sso/providers - List all SSO providers
 export async function GET(context: APIContext) {
@@ -45,10 +46,12 @@ export async function POST(context: APIContext) {
       tokenEndpoint,
       jwksEndpoint,
       userInfoEndpoint,
+      discoveryEndpoint,
       mapping,
       providerId,
       organizationId,
       scopes,
+      pkce,
     } = body;
 
     // Validate required fields
@@ -79,22 +82,51 @@ export async function POST(context: APIContext) {
       );
     }
 
-    // Create OIDC config object
-    const oidcConfig = {
-      clientId,
-      clientSecret,
-      authorizationEndpoint,
-      tokenEndpoint,
-      jwksEndpoint,
-      userInfoEndpoint,
-      scopes: scopes || ["openid", "email", "profile"],
-      mapping: mapping || {
-        id: "sub",
-        email: "email",
-        emailVerified: "email_verified",
-        name: "name",
-        image: "picture",
-      },
+    // Clean issuer URL (remove trailing slash); validate format
+    let cleanIssuer = issuer;
+    try {
+      const issuerUrl = new URL(issuer.toString().trim());
+      cleanIssuer = issuerUrl.toString().replace(/\/$/, "");
+    } catch {
+      return new Response(
+        JSON.stringify({ error: `Invalid issuer URL format: ${issuer}` }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    let normalized;
+    try {
+      normalized = await normalizeOidcProviderConfig(cleanIssuer, {
+        clientId,
+        clientSecret,
+        authorizationEndpoint,
+        tokenEndpoint,
+        jwksEndpoint,
+        userInfoEndpoint,
+        discoveryEndpoint,
+        scopes,
+        pkce,
+        mapping,
+      });
+    } catch (error) {
+      if (error instanceof OidcConfigError) {
+        return new Response(
+          JSON.stringify({ error: error.message }),
+          {
+            status: 400,
+            headers: { "Content-Type": "application/json" },
+          }
+        );
+      }
+      throw error;
+    }
+
+    const storedOidcConfig = {
+      ...normalized.oidcConfig,
+      mapping: normalized.mapping,
     };
 
     // Insert new provider
@@ -102,9 +134,9 @@ export async function POST(context: APIContext) {
       .insert(ssoProviders)
       .values({
         id: nanoid(),
-        issuer,
+        issuer: cleanIssuer,
         domain,
-        oidcConfig: JSON.stringify(oidcConfig),
+        oidcConfig: JSON.stringify(storedOidcConfig),
         userId: user.id,
         providerId,
         organizationId,
@@ -156,7 +188,9 @@ export async function PUT(context: APIContext) {
       tokenEndpoint,
       jwksEndpoint,
       userInfoEndpoint,
+      discoveryEndpoint,
       scopes,
+      pkce,
       organizationId,
     } = body;
 
@@ -179,26 +213,62 @@ export async function PUT(context: APIContext) {
 
     // Parse existing config
     const existingConfig = JSON.parse(existingProvider.oidcConfig);
+    const effectiveIssuer = issuer || existingProvider.issuer;
 
-    // Create updated OIDC config
-    const updatedOidcConfig = {
-      ...existingConfig,
-      clientId: clientId || existingConfig.clientId,
-      clientSecret: clientSecret || existingConfig.clientSecret,
-      authorizationEndpoint: authorizationEndpoint || existingConfig.authorizationEndpoint,
-      tokenEndpoint: tokenEndpoint || existingConfig.tokenEndpoint,
-      jwksEndpoint: jwksEndpoint || existingConfig.jwksEndpoint,
-      userInfoEndpoint: userInfoEndpoint || existingConfig.userInfoEndpoint,
-      scopes: scopes || existingConfig.scopes || ["openid", "email", "profile"],
+    let cleanIssuer = effectiveIssuer;
+    try {
+      const issuerUrl = new URL(effectiveIssuer.toString().trim());
+      cleanIssuer = issuerUrl.toString().replace(/\/$/, "");
+    } catch {
+      return new Response(
+        JSON.stringify({ error: `Invalid issuer URL format: ${effectiveIssuer}` }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    const mergedConfig: RawOidcConfig = {
+      clientId: clientId ?? existingConfig.clientId,
+      clientSecret: clientSecret ?? existingConfig.clientSecret,
+      authorizationEndpoint: authorizationEndpoint ?? existingConfig.authorizationEndpoint,
+      tokenEndpoint: tokenEndpoint ?? existingConfig.tokenEndpoint,
+      jwksEndpoint: jwksEndpoint ?? existingConfig.jwksEndpoint,
+      userInfoEndpoint: userInfoEndpoint ?? existingConfig.userInfoEndpoint,
+      discoveryEndpoint: discoveryEndpoint ?? existingConfig.discoveryEndpoint,
+      scopes: scopes ?? existingConfig.scopes,
+      pkce: pkce ?? existingConfig.pkce,
+      mapping: existingConfig.mapping,
+    };
+
+    let normalized;
+    try {
+      normalized = await normalizeOidcProviderConfig(cleanIssuer, mergedConfig);
+    } catch (error) {
+      if (error instanceof OidcConfigError) {
+        return new Response(
+          JSON.stringify({ error: error.message }),
+          {
+            status: 400,
+            headers: { "Content-Type": "application/json" },
+          }
+        );
+      }
+      throw error;
+    }
+
+    const storedOidcConfig = {
+      ...normalized.oidcConfig,
+      mapping: normalized.mapping,
     };
 
-    // Update provider
     const [updatedProvider] = await db
       .update(ssoProviders)
       .set({
-        issuer: issuer || existingProvider.issuer,
+        issuer: cleanIssuer,
         domain: domain || existingProvider.domain,
-        oidcConfig: JSON.stringify(updatedOidcConfig),
+        oidcConfig: JSON.stringify(storedOidcConfig),
         organizationId: organizationId !== undefined ? organizationId : existingProvider.organizationId,
         updatedAt: new Date(),
       })

src/types/config.ts

@@ -13,6 +13,8 @@ export interface GiteaConfig {
   preserveOrgStructure: boolean;
   mirrorStrategy?: MirrorStrategy; // New field for the strategy
   personalReposOrg?: string; // Override destination for personal repos
+  issueConcurrency?: number;
+  pullRequestConcurrency?: number;
 }
 
 export interface ScheduleConfig {

www/README.md

@@ -1,13 +1,30 @@
-# Astro with Tailwind
+# Gitea Mirror Marketing Site
 
-```sh
-bun create astro@latest -- --template with-tailwindcss
+This Astro workspace powers the public marketing experience for Gitea Mirror. It includes the landing page, screenshots, call-to-action components, and the new use case library that highlights real-world workflows.
+
+## Developing Locally
+
+```bash
+bun install
+bun run dev
 ```
 
-[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/astro/tree/latest/examples/with-tailwindcss)
-[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/astro/tree/latest/examples/with-tailwindcss)
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/withastro/astro?devcontainer_path=.devcontainer/with-tailwindcss/devcontainer.json)
+The site is available at `http://localhost:4321`. Tailwind CSS v4 handles styling; classes can be used directly inside Astro, MDX, and React components.
 
-Astro comes with [Tailwind](https://tailwindcss.com) support out of the box. This example showcases how to style your Astro project with Tailwind.
+## Project Structure
 
-For complete setup instructions, please see our [Tailwind Integration Guide](https://docs.astro.build/en/guides/integrations-guide/tailwind).
+- `src/pages/index.astro` – Main landing page
+- `src/components/` – Reusable UI (Header, Hero, Features, UseCases, etc.)
+- `src/lib/use-cases.ts` – Central data source for use case titles, summaries, and tags
+- `src/pages/use-cases/` – MDX guides for each use case, rendered with `UseCaseLayout`
+- `src/layouts/UseCaseLayout.astro` – Shared layout that injects the header, shader background, and footer into MDX guides
+
+## Authoring Use Case Guides
+
+1. Add or update a record in `src/lib/use-cases.ts`. This keeps the landing page and library listing in sync.
+2. Create a new MDX file in `src/pages/use-cases/<slug>.mdx` with the `UseCaseLayout` layout and descriptive frontmatter.
+3. Run `bun run dev` to preview the layout and ensure the new guide inherits global styles.
+
+## Deployment
+
+The marketing site is built with the standard Astro pipeline. Use `bun run build` to generate a production build before deploying.

www/astro.config.mjs

@@ -1,8 +1,8 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import tailwindcss from '@tailwindcss/vite';
-
 import react from '@astrojs/react';
+import mdx from '@astrojs/mdx';
 
 // https://astro.build/config
 export default defineConfig({
@@ -10,5 +10,5 @@ export default defineConfig({
       plugins: [tailwindcss()]
 	},
 
-  integrations: [react()]
+  integrations: [react(), mdx()]
 });

www/docs/SEO_KEYWORDS.md

@@ -1,236 +1,628 @@
-# SEO Keywords & Content Strategy for Gitea Mirror
+# SEO Keywords & Programmatic Content Strategy for Gitea Mirror
 
-## Target Audience & Pain Points
-
-### Primary Audience
-- DevOps engineers managing GitHub repositories
-- Companies looking to backup GitHub data
-- Self-hosting enthusiasts
-- Organizations migrating from GitHub to self-hosted solutions
-- Developers needing GitHub disaster recovery
-
-### Key Pain Points
-- Manual GitHub to Gitea migration is time-consuming
-- No automated backup solution for GitHub organizations
-- Difficulty preserving repository structure during migration
-- Need for scheduled, automatic synchronization
-- Complex authentication setup for self-hosted Git services
-
-## Keyword Categories & Opportunities
-
-### 1. Problem-Solving Keywords (High Intent)
-- **"github to gitea migration"** - Core functionality keyword
-- **"mirror github repository to gitea"** - Direct search intent
-- **"sync github gitea automatically"** - Automation focus
-- **"backup github to self hosted"** - Backup use case
-- **"github organization mirror tool"** - Organization-specific
-- **"gitea import from github"** - Alternative phrasing
-- **"migrate starred github repos"** - Specific feature
-
-### 2. Comparison & Alternative Keywords
-- **"github vs gitea migration"** - Comparison content
-- **"gitea mirror alternatives"** - Competitor analysis
-- **"self hosted github backup solutions"** - Solution category
-- **"github repository sync tools"** - Tool category
-- **"gitea github integration"** - Integration focus
-- **"github backup automation"** - Automation emphasis
-
-### 3. How-To & Tutorial Keywords
-- **"how to mirror github to gitea"** - Tutorial intent
-- **"setup gitea mirror docker"** - Installation guide
-- **"gitea github sync tutorial"** - Step-by-step content
-- **"automate github backup gitea"** - Automation tutorial
-- **"mirror private github repos gitea"** - Private repos guide
-- **"gitea import github wiki"** - Feature-specific tutorial
-
-### 4. Feature-Specific Keywords
-- **"gitea sso authentication setup"** - Auth feature
-- **"gitea oidc provider configuration"** - OIDC setup
-- **"gitea better auth integration"** - Specific tech stack
-- **"gitea scheduled mirror"** - Scheduling feature
-- **"gitea bulk repository import"** - Bulk operations
-- **"gitea preserve organization structure"** - Organization feature
-
-### 5. Platform & Deployment Keywords
-- **"gitea mirror proxmox"** - Platform-specific
-- **"gitea mirror docker compose"** - Docker deployment
-- **"gitea mirror arm64"** - Architecture-specific
-- **"gitea mirror reverse proxy"** - Infrastructure setup
-- **"gitea authentik integration"** - Auth provider integration
-
-### 6. Use Case Keywords
-- **"self host github backup"** - Backup use case
-- **"enterprise github migration gitea"** - Enterprise focus
-- **"github disaster recovery gitea"** - DR use case
-- **"github archive self hosted"** - Archival use case
-- **"github organization backup automation"** - Org backup
-
-### 7. Long-Tail Problem Keywords
-- **"mirror github issues to gitea"** - Specific feature
-- **"sync github releases gitea automatically"** - Release sync
-- **"gitea mirror multiple organizations"** - Multi-org
-- **"github starred repositories backup"** - Starred repos
-- **"gitea mirror skip forks"** - Fork handling
-
-### 8. Technical Integration Keywords
-- **"gitea github api integration"** - API focus
-- **"gitea webhook github sync"** - Webhook integration
-- **"gitea ci/cd github mirror"** - CI/CD integration
-- **"gitea github actions migration"** - Actions migration
-
-## Blog Post Ideas & Content Strategy
-
-### High-Priority Blog Posts
-
-1. **"Complete Guide to Migrating from GitHub to Gitea in 2025"**
-   - **Target Keywords**: github to gitea migration, gitea import from github
-   - **Content**: Comprehensive migration guide with screenshots
-   - **Length**: 2,500-3,000 words
-   - **Include**: Step-by-step instructions, troubleshooting, best practices
-
-2. **"How to Automatically Backup Your GitHub Repositories to Self-Hosted Gitea"**
-   - **Target Keywords**: backup github to self hosted, github backup automation
-   - **Content**: Focus on automation and scheduling features
-   - **Length**: 1,800-2,200 words
-   - **Include**: Docker setup, cron scheduling, backup strategies
-
-3. **"Gitea Mirror vs Manual Migration: Which GitHub Migration Method is Best?"**
-   - **Target Keywords**: gitea mirror alternatives, github repository sync tools
-   - **Content**: Comparison post with pros/cons, feature matrix
-   - **Length**: 1,500-2,000 words
-   - **Include**: Comparison table, use case recommendations
-
-4. **"Setting Up Enterprise GitHub Backup with Gitea Mirror and Docker"**
-   - **Target Keywords**: enterprise github migration gitea, github organization backup automation
-   - **Content**: Enterprise-focused guide with security considerations
-   - **Length**: 2,000-2,500 words
-   - **Include**: Multi-user setup, permission management, scaling
-
-5. **"Mirror GitHub Organizations to Gitea While Preserving Structure"**
-   - **Target Keywords**: github organization mirror tool, gitea preserve organization structure
-   - **Content**: Deep dive into organization mirroring strategies
-   - **Length**: 1,500-1,800 words
-   - **Include**: Strategy explanations, configuration examples
-
-6. **"Gitea SSO Setup: Complete Authentication Guide with Examples"**
-   - **Target Keywords**: gitea sso authentication setup, gitea oidc provider configuration
-   - **Content**: Cover all auth methods including header auth
-   - **Length**: 2,000-2,500 words
-   - **Include**: Provider examples (Google, Azure, Authentik)
-
-7. **"How to Mirror Private GitHub Repositories to Your Gitea Instance"**
-   - **Target Keywords**: mirror private github repos gitea, gitea github api integration
-   - **Content**: Security-focused content with token management
-   - **Length**: 1,500-1,800 words
-   - **Include**: Token permissions, security best practices
-
-8. **"Gitea Mirror on Proxmox: Ultimate Self-Hosting Guide"**
-   - **Target Keywords**: gitea mirror proxmox, self host github backup
-   - **Content**: LXC container setup tutorial
-   - **Length**: 1,800-2,200 words
-   - **Include**: Proxmox setup, resource allocation, networking
-
-## Landing Page Optimization
-
-### Title Tag Options
-- "Gitea Mirror - Automated GitHub to Gitea Migration & Backup Tool"
-- "GitHub to Gitea Mirror - Sync, Backup & Migrate Repositories Automatically"
-- "Gitea Mirror - Self-Hosted GitHub Repository Backup & Sync Solution"
-
-### Meta Description Options
-- "Automatically mirror and backup your GitHub repositories to self-hosted Gitea. Support for organizations, private repos, scheduled sync, and SSO authentication. Docker & Proxmox ready."
-- "The easiest way to migrate from GitHub to Gitea. Mirror repositories, organizations, issues, and releases automatically. Self-hosted backup solution with enterprise features."
-
-### H1 Options
-- "Automatically Mirror GitHub Repositories to Your Gitea Instance"
-- "Self-Hosted GitHub Backup & Migration Tool for Gitea"
-- "The Complete GitHub to Gitea Migration Solution"
-
-### Key Landing Page Sections to Optimize
-
-1. **Hero Section**
-   - Include primary keywords naturally
-   - Clear value proposition
-   - Quick start CTA
-
-2. **Features Section**
-   - Target feature-specific keywords
-   - Use semantic variations
-   - Include comparison points
-
-3. **Use Cases Section**
-   - Target use case keywords
-   - Include customer scenarios
-   - Enterprise focus subsection
-
-4. **Installation Section**
-   - Target platform keywords
-   - Docker, Proxmox, manual options
-   - Quick start emphasis
-
-5. **FAQ Section**
-   - Target long-tail keywords
-   - Common migration questions
-   - Technical integration queries
-
-## Content Calendar Suggestions
-
-### Month 1
-- Week 1-2: "Complete Guide to Migrating from GitHub to Gitea"
-- Week 3-4: "How to Automatically Backup Your GitHub Repositories"
-
-### Month 2
-- Week 1-2: "Gitea Mirror vs Manual Migration"
-- Week 3-4: "Enterprise GitHub Backup Guide"
-
-### Month 3
-- Week 1-2: "Mirror GitHub Organizations Guide"
-- Week 3-4: "Gitea SSO Setup Guide"
-
-### Month 4
-- Week 1-2: "Private Repository Mirroring"
-- Week 3-4: "Gitea Mirror on Proxmox"
-
-## SEO Research Tips
-
-### When Using Ahrefs
-1. **Search Volume**: Target 100-1,000 monthly searches initially
-2. **Keyword Difficulty**: Aim for KD < 30 for new content
-3. **SERP Analysis**: Check competitor content depth
-4. **Parent Topics**: Find broader topics to target
-5. **Featured Snippets**: Look for snippet opportunities
-
-### Content Optimization
-1. Include target keyword in:
-   - Title tag
-   - H1 (once)
-   - First 100 words
-   - At least one H2
-   - URL slug
-   - Meta description
-
-2. Use semantic variations throughout
-3. Include related keywords naturally
-4. Optimize for search intent
-5. Add schema markup for tutorials
-
-## Tracking & Updates
-
-### KPIs to Monitor
-- Organic traffic growth
-- Keyword rankings
-- Click-through rates
-- Conversion rates (signups/downloads)
-- Time on page
-
-### Regular Updates
-- Review keyword performance monthly
-- Update content quarterly
-- Add new keywords based on search console data
-- Monitor competitor content
-- Track feature releases for new keyword opportunities
+> **Goal**: Generate 5,000-15,000 organic visits/month within 6-12 months
+> **Strategy**: Low-effort, high-intent pages targeting long-tail keywords
+> **Focus**: Problem-solving content over generic tool descriptions
 
 ---
 
-*Last Updated: [Current Date]*
-*Next Review: [Date + 3 months]*
+## 🎯 LOW-HANGING FRUIT: Quick Wins (Start This Week)
+
+### Tier 1: Ultra Low-Effort, High-Intent Pages (1-2 hours each)
+
+These are **simple template pages** with **minimal content** but **high search volume** and **buyer intent**.
+
+| Page | Keyword | Monthly Searches | Difficulty | Effort | Priority |
+|------|---------|-----------------|------------|--------|----------|
+| `/use-cases/backup-github-repositories` | "backup github repositories" | 500-1K | Low (15) | 1h | ⭐⭐⭐⭐⭐ |
+| `/use-cases/migrate-github-to-gitea` | "migrate github to gitea" | 300-800 | Low (10) | 1h | ⭐⭐⭐⭐⭐ |
+| `/solutions/github-disaster-recovery` | "github disaster recovery" | 200-500 | Low (12) | 1h | ⭐⭐⭐⭐⭐ |
+| `/vs/manual-vs-automated-github-migration` | "automated github migration" | 150-400 | Very Low (8) | 1.5h | ⭐⭐⭐⭐ |
+| `/guides/setup-gitea-mirror-docker` | "gitea mirror docker setup" | 100-300 | Very Low (5) | 2h | ⭐⭐⭐⭐ |
+
+**Why these work:**
+- Specific, actionable queries ("how to backup", "migrate to")
+- Low competition (KD < 15)
+- High commercial intent (ready to install)
+- Can reuse existing docs content
+
+**Template for these pages:** 400-600 words, 30 minutes to write each
+
+---
+
+## 📊 KEYWORD STRATEGY: 3-Tier Approach
+
+### Tier 1: Problem-Solving Keywords (HIGHEST PRIORITY)
+**Intent**: "I have this specific problem"
+**Effort**: Low (template-based)
+**Pages needed**: 15
+
+| Primary Keyword | Secondary Keywords | Est. Traffic | Page URL |
+|----------------|-------------------|--------------|----------|
+| backup github repositories | github backup tool, automated github backup | 500/mo | `/use-cases/backup-github-repositories` |
+| migrate github to gitea | github gitea migration, import github to gitea | 400/mo | `/use-cases/migrate-github-to-gitea` |
+| github disaster recovery | backup github organization, github downtime backup | 250/mo | `/solutions/github-disaster-recovery` |
+| sync github to self-hosted | self-hosted github alternative, github to gitea sync | 200/mo | `/use-cases/sync-github-to-self-hosted-gitea` |
+| preserve github history | github history backup, archive github repos | 180/mo | `/use-cases/preserve-github-history` |
+| github vendor lock-in | avoid github lock-in, github alternatives | 150/mo | `/solutions/avoid-vendor-lock-in` |
+| github backup automation | automate github mirror, scheduled github backup | 140/mo | `/use-cases/github-backup-automation` |
+| mirror starred repositories | backup starred repos, export github stars | 120/mo | `/use-cases/starred-repos-collection` |
+| github offline access | offline git mirror, air-gapped github | 100/mo | `/solutions/need-offline-git-access` |
+| github rate limits | bypass github api limits, github api alternatives | 90/mo | `/solutions/github-rate-limits` |
+
+**Total Tier 1 Traffic Potential**: ~2,500 visits/month
+
+---
+
+### Tier 2: Feature-Specific Keywords (MEDIUM PRIORITY)
+**Intent**: "I want to do this specific thing"
+**Effort**: Medium (requires explaining features)
+**Pages needed**: 12
+
+| Primary Keyword | Est. Traffic | Page URL |
+|----------------|--------------|----------|
+| mirror github issues | 80/mo | `/features/github-issues-migration` |
+| sync github releases | 70/mo | `/features/github-releases-sync` |
+| mirror github wiki | 60/mo | `/features/wiki-migration` |
+| preserve github organization structure | 50/mo | `/features/organization-structure-preservation` |
+| mirror private github repos | 180/mo | `/features/private-repository-mirroring` |
+| github metadata migration | 45/mo | `/features/metadata-migration` |
+| scheduled github sync | 120/mo | `/features/scheduled-synchronization` |
+| batch github migration | 40/mo | `/features/batch-repository-processing` |
+| github pull request migration | 35/mo | `/features/pull-request-mirroring` |
+| git lfs mirror | 30/mo | `/features/git-lfs-support` |
+
+**Total Tier 2 Traffic Potential**: ~1,200 visits/month
+
+---
+
+### Tier 3: Comparison Keywords (HIGH CONVERSION)
+**Intent**: "Evaluating options"
+**Effort**: Medium-High (research required)
+**Pages needed**: 8
+
+| Primary Keyword | Est. Traffic | Conversion Potential | Page URL |
+|----------------|--------------|---------------------|----------|
+| github backup tools comparison | 250/mo | Very High | `/vs/github-backup-solutions` |
+| gitea vs github | 800/mo | Medium | `/vs/github-vs-gitea` |
+| manual vs automated migration | 60/mo | High | `/vs/manual-vs-automated-migration` |
+| git clone vs mirror | 45/mo | Medium | `/vs/git-clone-vs-automated-sync` |
+| gitea alternatives | 150/mo | Medium | `/alternatives` |
+| self-hosted git servers | 400/mo | Low | `/vs/self-hosted-vs-cloud-git` |
+
+**Total Tier 3 Traffic Potential**: ~1,700 visits/month
+
+---
+
+## 🚀 IMPLEMENTATION ROADMAP: 4-Week Sprint
+
+### Week 1: Foundation (5 pages)
+**Goal**: Get first pages indexed, establish content structure
+
+**Day 1-2: Setup** (4 hours)
+- [ ] Create Astro content collections (`src/content/config.ts`)
+- [ ] Build page templates (use-cases, features, solutions)
+- [ ] Setup SEO component with structured data
+- [ ] Create sitemap generator
+
+**Day 3-5: Core Content** (8 hours)
+- [ ] `/use-cases/backup-github-repositories` - 600 words
+- [ ] `/use-cases/migrate-github-to-gitea` - 600 words
+- [ ] `/solutions/github-disaster-recovery` - 500 words
+- [ ] `/features/automatic-github-mirroring` - 700 words
+- [ ] `/vs/manual-vs-automated-migration` - 800 words
+
+**Day 6-7: Technical Setup** (3 hours)
+- [ ] Submit sitemap to Google Search Console
+- [ ] Setup Google Analytics 4
+- [ ] Add schema.org markup
+- [ ] Create robots.txt
+- [ ] Setup canonical URLs
+
+**Week 1 Target**: 5 pages live, indexed by Google
+
+---
+
+### Week 2: Scale Content (10 pages)
+**Goal**: Batch create similar pages using templates
+
+**Use Case Pages** (5 pages, 1 hour each):
+- [ ] `/use-cases/sync-github-to-self-hosted-gitea`
+- [ ] `/use-cases/preserve-github-history`
+- [ ] `/use-cases/github-backup-automation`
+- [ ] `/use-cases/starred-repos-collection`
+- [ ] `/use-cases/vendor-lock-in-prevention`
+
+**Feature Pages** (5 pages, 1.5 hours each):
+- [ ] `/features/private-repository-mirroring`
+- [ ] `/features/scheduled-synchronization`
+- [ ] `/features/github-issues-migration`
+- [ ] `/features/github-releases-sync`
+- [ ] `/features/metadata-migration`
+
+**Week 2 Target**: 15 total pages, monitor first impressions in GSC
+
+---
+
+### Week 3: Problem-Solution Focus (8 pages)
+**Goal**: Target high-intent problem queries
+
+**Solution Pages** (6 pages, 45 min each):
+- [ ] `/solutions/avoid-vendor-lock-in`
+- [ ] `/solutions/need-offline-git-access`
+- [ ] `/solutions/github-rate-limits`
+- [ ] `/solutions/github-pricing-too-expensive`
+- [ ] `/solutions/comply-with-data-regulations`
+- [ ] `/solutions/preserve-deleted-github-repos`
+
+**Guide Pages** (2 pages, 2 hours each):
+- [ ] `/guides/setup-gitea-mirror-docker`
+- [ ] `/guides/migrate-github-organization-to-gitea`
+
+**Week 3 Target**: 23 total pages, start seeing traffic
+
+---
+
+### Week 4: Comparison & Polish (7 pages + optimization)
+**Goal**: High-conversion comparison content + optimization
+
+**Comparison Pages** (4 pages, 2 hours each):
+- [ ] `/vs/github-backup-solutions`
+- [ ] `/vs/github-vs-gitea`
+- [ ] `/vs/self-hosted-vs-cloud-git`
+- [ ] `/alternatives`
+
+**Integration Pages** (3 pages, 1 hour each):
+- [ ] `/integrations/docker-compose`
+- [ ] `/integrations/kubernetes`
+- [ ] `/integrations/helm-charts`
+
+**Optimization** (8 hours):
+- [ ] Add internal linking between all pages
+- [ ] Optimize images (WebP, alt text)
+- [ ] Add FAQ sections to top 10 pages
+- [ ] Create content calendar for Month 2
+
+**Week 4 Target**: 30 total pages, 50-100 visitors/week
+
+---
+
+## 📝 CONTENT TEMPLATES
+
+### Template 1: Use Case Page (400-600 words, 30 min)
+
+```markdown
+# [Use Case Title] - Gitea Mirror
+
+> **In this guide**: Learn how to [solve specific problem] using Gitea Mirror's automated [feature].
+
+## The Problem
+
+[2-3 sentences describing the pain point]
+
+**Common challenges:**
+- Challenge 1
+- Challenge 2
+- Challenge 3
+
+## How Gitea Mirror Solves This
+
+[3-4 sentences explaining the solution]
+
+**Key capabilities:**
+- ✅ Capability 1
+- ✅ Capability 2
+- ✅ Capability 3
+
+## Quick Start (5 Minutes)
+
+\`\`\`bash
+# Step 1: Pull the Docker image
+docker pull giteamirror/gitea-mirror:latest
+
+# Step 2: Run with environment variables
+docker run -d \\
+  -e GITHUB_TOKEN=your_token \\
+  -e GITEA_URL=https://gitea.example.com \\
+  giteamirror/gitea-mirror
+\`\`\`
+
+[2 sentences on what happens next]
+
+## Real-World Example
+
+[Short scenario: "A DevOps team needed to..."]
+
+## Related Features
+
+- [Link to feature 1]
+- [Link to feature 2]
+
+## Get Started
+
+[CTA button/link to GitHub repo]
+
+---
+
+**Keywords**: [primary], [secondary], [tertiary]
+**Last Updated**: [Date]
+```
+
+**Why this works:**
+- Answers search query immediately
+- Shows code (high engagement)
+- Internal links (SEO juice)
+- Clear CTA
+- **Total time: 30 minutes**
+
+---
+
+### Template 2: Feature Page (500-700 words, 45 min)
+
+```markdown
+# [Feature Name] - Gitea Mirror
+
+> Automatically [feature benefit] from GitHub to Gitea with zero manual work.
+
+## What Is [Feature Name]?
+
+[2-3 sentences explaining the feature]
+
+## Why You Need This
+
+**Without Gitea Mirror:**
+- ❌ Manual problem 1
+- ❌ Manual problem 2
+- ❌ Manual problem 3
+
+**With Gitea Mirror:**
+- ✅ Automated solution 1
+- ✅ Automated solution 2
+- ✅ Automated solution 3
+
+## How It Works
+
+1. **Step 1**: [Action]
+2. **Step 2**: [Action]
+3. **Step 3**: [Result]
+
+## Configuration
+
+\`\`\`yaml
+# Example configuration
+feature_enabled: true
+option1: value
+option2: value
+\`\`\`
+
+## Use Cases
+
+### Use Case 1
+[Scenario where this feature helps]
+
+### Use Case 2
+[Another scenario]
+
+## Best Practices
+
+- Tip 1
+- Tip 2
+- Tip 3
+
+## See It In Action
+
+[Screenshot or GIF]
+
+## Get Started
+
+[CTA]
+
+---
+
+**Related**:
+- [Use case page]
+- [Guide page]
+```
+
+---
+
+### Template 3: Solution Page (300-500 words, 20 min)
+
+```markdown
+# [Problem Statement] - Solved
+
+> **The Problem**: [One sentence problem]
+> **The Solution**: Gitea Mirror's automated [approach]
+
+## Why This Problem Matters
+
+[2 sentences on impact]
+
+**Consequences of not solving:**
+1. Consequence 1
+2. Consequence 2
+3. Consequence 3
+
+## How Gitea Mirror Fixes This
+
+[Explain the solution in 3-4 sentences]
+
+## Implementation
+
+\`\`\`bash
+# 2-3 line code snippet
+\`\`\`
+
+## Success Story
+
+"[Quote or short anecdote]"
+
+## Next Steps
+
+1. [Link to getting started]
+2. [Link to relevant feature]
+
+[CTA button]
+```
+
+**Total time: 20 minutes**
+
+---
+
+## 🎨 SEO OPTIMIZATION CHECKLIST
+
+### On-Page SEO (Per Page)
+```
+✅ Title tag: [Keyword] - Gitea Mirror (50-60 chars)
+✅ Meta description with CTA (150-160 chars)
+✅ H1 includes primary keyword
+✅ URL slug = primary keyword
+✅ First paragraph mentions keyword
+✅ H2s include semantic variations
+✅ Image alt text descriptive
+✅ Internal links (3-5 per page)
+✅ External links (1-2 authoritative sources)
+✅ Schema.org markup (SoftwareApplication)
+✅ Canonical URL set
+✅ Mobile responsive
+✅ Page speed < 3s
+```
+
+### Content Quality Checks
+```
+✅ Answers search intent completely
+✅ 400-1500 word count (based on competition)
+✅ Code examples where relevant
+✅ Screenshots/visuals
+✅ Updated date visible
+✅ Clear CTA
+✅ Related content links
+✅ No keyword stuffing (1-2% density)
+```
+
+---
+
+## 📈 TRACKING & METRICS
+
+### Week 1-2 KPIs
+- [ ] All pages indexed in Google (check GSC)
+- [ ] 0 technical SEO errors (screaming frog)
+- [ ] < 3s page load time
+- [ ] Mobile usability 100/100
+
+### Week 3-4 KPIs
+- [ ] 10+ impressions/day in GSC
+- [ ] 3+ clicks/day from organic
+- [ ] 1+ page ranking in top 50
+
+### Month 2 Goals
+- [ ] 100+ impressions/day
+- [ ] 20+ clicks/day
+- [ ] 10+ keywords in top 50
+- [ ] 5+ keywords in top 20
+
+### Month 3 Goals
+- [ ] 500+ impressions/day
+- [ ] 50+ clicks/day
+- [ ] 20+ keywords in top 20
+- [ ] 10+ keywords in top 10
+
+---
+
+## 🔗 INTERNAL LINKING STRATEGY
+
+**Hub & Spoke Model**
+
+### Hub Pages (Link FROM these everywhere)
+1. Homepage
+2. `/use-cases/migrate-github-to-gitea` (main use case)
+3. `/features/automatic-github-mirroring` (main feature)
+
+### Spoke Pages (Link TO hubs + related spokes)
+- Use case pages link to: Related features, guides, solutions
+- Feature pages link to: Use cases, guides
+- Solution pages link to: Use cases, features
+- Guide pages link to: Features, use cases
+
+**Example**:
+```
+/use-cases/backup-github-repositories
+  → Links to:
+    - /features/scheduled-synchronization
+    - /features/automatic-github-mirroring
+    - /guides/setup-gitea-mirror-docker
+    - /solutions/github-disaster-recovery
+```
+
+---
+
+## 💡 CONTENT HACKS: Work Smarter
+
+### 1. Batch Similar Pages (2x faster)
+Write all "use case" pages in one session using the template. Copy structure, change specifics.
+
+### 2. Reuse Existing Content
+- Main repo README → Use case pages
+- Docker docs → Guide pages
+- GitHub issues → Problem pages
+
+### 3. AI-Assisted Expansion
+- Write 200-word outline manually
+- Expand with AI to 600 words
+- Edit for accuracy (10 min)
+- **Time saved: 50%**
+
+### 4. Screenshot Once, Use Everywhere
+Create a `/public/screenshots/` library:
+- Dashboard view
+- Configuration screen
+- Migration in progress
+- Results page
+
+Reuse across all pages.
+
+### 5. Schema Markup Template
+Create one JSON-LD template, reuse with variable substitution:
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "Gitea Mirror",
+  "description": "[PAGE_DESCRIPTION]",
+  "url": "[PAGE_URL]"
+}
+```
+
+---
+
+## 🎯 MONTH 2-3 EXPANSION PLAN
+
+### Month 2: Depth Over Breadth
+**Goal**: Make existing pages rank higher
+
+**Activities**:
+- [ ] Add 200 words to each existing page
+- [ ] Add FAQ sections (5 Q&As per page)
+- [ ] Create 10 more guide pages (tutorials)
+- [ ] Add video embeds (YouTube shorts)
+- [ ] Guest post on Dev.to (backlinks)
+
+**New Pages** (10):
+- 5 more use case pages
+- 5 advanced guides
+
+### Month 3: Authority Building
+**Goal**: Establish Gitea Mirror as THE GitHub migration resource
+
+**Activities**:
+- [ ] Ultimate Guide: "Complete GitHub to Gitea Migration Guide" (3,000 words)
+- [ ] Comparison matrix: All GitHub backup tools
+- [ ] Interactive tool: "Migration time calculator"
+- [ ] Video tutorials (5-10 minutes each)
+- [ ] Community: Add testimonials/case studies
+
+**New Pages** (15):
+- 5 integration pages
+- 5 technical spec pages
+- 5 advanced solution pages
+
+---
+
+## 🏆 SUCCESS METRICS (6 Months)
+
+### Conservative Target
+- **Pages**: 50 indexed
+- **Traffic**: 5,000 visits/month
+- **Keywords**: 30 in top 20
+- **Backlinks**: 15-20
+- **GitHub Stars**: +50 from organic
+
+### Optimistic Target
+- **Pages**: 80 indexed
+- **Traffic**: 12,000 visits/month
+- **Keywords**: 50 in top 20, 20 in top 10
+- **Backlinks**: 40-50
+- **GitHub Stars**: +200 from organic
+
+---
+
+## 🔧 TECHNICAL SETUP (Do Once)
+
+### Astro Content Collections
+```typescript
+// src/content/config.ts
+import { defineCollection, z } from 'astro:content';
+
+const useCases = defineCollection({
+  type: 'content',
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    keywords: z.array(z.string()),
+    problem: z.string(),
+    solution: z.string(),
+    difficulty: z.enum(['beginner', 'intermediate', 'advanced']),
+    timeToRead: z.number(),
+    relatedPages: z.array(z.string()).optional(),
+  }),
+});
+
+export const collections = {
+  'use-cases': useCases,
+  'features': defineCollection({ /* ... */ }),
+  'guides': defineCollection({ /* ... */ }),
+  'solutions': defineCollection({ /* ... */ }),
+  'vs': defineCollection({ /* ... */ }),
+};
+```
+
+### Dynamic Route Template
+```astro
+---
+// src/pages/use-cases/[...slug].astro
+import { getCollection } from 'astro:content';
+
+export async function getStaticPaths() {
+  const useCases = await getCollection('use-cases');
+  return useCases.map(entry => ({
+    params: { slug: entry.slug },
+    props: { entry },
+  }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await entry.render();
+---
+
+<Layout title={entry.data.title} description={entry.data.description}>
+  <article>
+    <h1>{entry.data.title}</h1>
+    <Content />
+  </article>
+</Layout>
+```
+
+---
+
+## 📋 QUICK ACTION CHECKLIST
+
+**Today:**
+- [ ] Create content collections structure
+- [ ] Write first use case page (1 hour)
+- [ ] Setup Google Search Console
+
+**This Week:**
+- [ ] Complete 5 high-priority pages
+- [ ] Submit sitemap
+- [ ] Add schema markup
+
+**This Month:**
+- [ ] 30 pages live
+- [ ] Internal linking complete
+- [ ] First organic traffic
+
+---
+
+**Last Updated**: January 2025
+**Next Review**: February 2025
+**Owner**: [Your Team]

www/package.json

@@ -1,7 +1,7 @@
 {
   "name": "www",
   "type": "module",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "scripts": {
     "dev": "astro dev",
     "build": "astro build",
@@ -9,28 +9,28 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@astrojs/mdx": "^4.3.6",
+    "@astrojs/mdx": "^4.3.7",
     "@astrojs/react": "^4.4.0",
     "@radix-ui/react-icons": "^1.3.2",
     "@radix-ui/react-slot": "^1.2.3",
     "@splinetool/react-spline": "^4.1.0",
-    "@splinetool/runtime": "^1.10.73",
-    "@tailwindcss/vite": "^4.1.14",
+    "@splinetool/runtime": "^1.10.85",
+    "@tailwindcss/vite": "^4.1.15",
     "@types/canvas-confetti": "^1.9.0",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "astro": "^5.14.3",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "astro": "^5.14.8",
     "canvas-confetti": "^1.9.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^0.544.0",
+    "lucide-react": "^0.546.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "tailwind-merge": "^3.3.1",
-    "tailwindcss": "^4.1.14"
+    "tailwindcss": "^4.1.15"
   },
   "devDependencies": {
     "tw-animate-css": "^1.4.0"
   },
-  "packageManager": "pnpm@10.18.0"
+  "packageManager": "pnpm@10.18.3"
 }

www/pnpm-lock.yaml

@@ -9,38 +9,38 @@ importers:
   .:
     dependencies:
       '@astrojs/mdx':
-        specifier: ^4.3.6
-        version: 4.3.6(astro@5.14.3(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1)(rollup@4.52.4)(typescript@5.8.3))
+        specifier: ^4.3.7
+        version: 4.3.7(astro@5.14.8(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.52.4)(typescript@5.8.3))
       '@astrojs/react':
         specifier: ^4.4.0
-        version: 4.4.0(@types/node@24.7.1)(@types/react-dom@19.2.0(@types/react@19.2.0))(@types/react@19.2.0)(jiti@2.6.1)(lightningcss@1.30.1)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
+        version: 4.4.0(@types/node@24.7.1)(@types/react-dom@19.2.2(@types/react@19.2.2))(@types/react@19.2.2)(jiti@2.6.1)(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
       '@radix-ui/react-icons':
         specifier: ^1.3.2
         version: 1.3.2(react@19.2.0)
       '@radix-ui/react-slot':
         specifier: ^1.2.3
-        version: 1.2.3(@types/react@19.2.0)(react@19.2.0)
+        version: 1.2.3(@types/react@19.2.2)(react@19.2.0)
       '@splinetool/react-spline':
         specifier: ^4.1.0
-        version: 4.1.0(@splinetool/runtime@1.10.73)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
+        version: 4.1.0(@splinetool/runtime@1.10.85)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
       '@splinetool/runtime':
-        specifier: ^1.10.73
-        version: 1.10.73
+        specifier: ^1.10.85
+        version: 1.10.85
       '@tailwindcss/vite':
-        specifier: ^4.1.14
-        version: 4.1.14(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1))
+        specifier: ^4.1.15
+        version: 4.1.15(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2))
       '@types/canvas-confetti':
         specifier: ^1.9.0
         version: 1.9.0
       '@types/react':
-        specifier: ^19.2.0
-        version: 19.2.0
+        specifier: ^19.2.2
+        version: 19.2.2
       '@types/react-dom':
-        specifier: ^19.2.0
-        version: 19.2.0(@types/react@19.2.0)
+        specifier: ^19.2.2
+        version: 19.2.2(@types/react@19.2.2)
       astro:
-        specifier: ^5.14.3
-        version: 5.14.3(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1)(rollup@4.52.4)(typescript@5.8.3)
+        specifier: ^5.14.8
+        version: 5.14.8(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.52.4)(typescript@5.8.3)
       canvas-confetti:
         specifier: ^1.9.3
         version: 1.9.3
@@ -51,8 +51,8 @@ importers:
         specifier: ^2.1.1
         version: 2.1.1
       lucide-react:
-        specifier: ^0.544.0
-        version: 0.544.0(react@19.2.0)
+        specifier: ^0.546.0
+        version: 0.546.0(react@19.2.0)
       react:
         specifier: ^19.2.0
         version: 19.2.0
@@ -63,8 +63,8 @@ importers:
         specifier: ^3.3.1
         version: 3.3.1
       tailwindcss:
-        specifier: ^4.1.14
-        version: 4.1.14
+        specifier: ^4.1.15
+        version: 4.1.15
     devDependencies:
       tw-animate-css:
         specifier: ^1.4.0
@@ -79,20 +79,14 @@ packages:
   '@astrojs/compiler@2.13.0':
     resolution: {integrity: sha512-mqVORhUJViA28fwHYaWmsXSzLO9osbdZ5ImUfxBarqsYdMlPbqAqGJCxsNzvppp1BEzc1mJNjOVvQqeDN8Vspw==}
 
-  '@astrojs/internal-helpers@0.7.3':
-    resolution: {integrity: sha512-6Pl0bQEIChuW5wqN7jdKrzWfCscW2rG/Cz+fzt4PhSQX2ivBpnhXgFUCs0M3DCYvjYHnPVG2W36X5rmFjZ62sw==}
-
   '@astrojs/internal-helpers@0.7.4':
     resolution: {integrity: sha512-lDA9MqE8WGi7T/t2BMi+EAXhs4Vcvr94Gqx3q15cFEz8oFZMO4/SFBqYr/UcmNlvW+35alowkVj+w9VhLvs5Cw==}
 
-  '@astrojs/markdown-remark@6.3.7':
-    resolution: {integrity: sha512-KXGdq6/BC18doBCYXp08alHlWChH0hdD2B1qv9wIyOHbvwI5K6I7FhSta8dq1hBQNdun8YkKPR013D/Hm8xd0g==}
-
   '@astrojs/markdown-remark@6.3.8':
     resolution: {integrity: sha512-uFNyFWadnULWK2cOw4n0hLKeu+xaVWeuECdP10cQ3K2fkybtTlhb7J7TcScdjmS8Yps7oje9S/ehYMfZrhrgCg==}
 
-  '@astrojs/mdx@4.3.6':
-    resolution: {integrity: sha512-jH04tYgaqLfq3To42+z1oEcXrXUzo3BxZ4fTkb+7BEmOJkQ9/c3iIixFEC+x0GgE8lJb4SuEDGldpAv7+1yY8A==}
+  '@astrojs/mdx@4.3.7':
+    resolution: {integrity: sha512-5SRmvMyT/UMWaU2eoD+htnXtE2mUZZEH2K/nEzhuEy+iCsOSuS/DUry59WuKUJRQETi1mgJFdNR4dZLJHYVuRA==}
     engines: {node: 18.20.8 || ^20.3.0 || >=22.0.0}
     peerDependencies:
       astro: ^5.0.0
@@ -486,10 +480,6 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@isaacs/fs-minipass@4.0.1':
-    resolution: {integrity: sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==}
-    engines: {node: '>=18.0.0'}
-
   '@jridgewell/gen-mapping@0.3.12':
     resolution: {integrity: sha512-OuLGC46TjB5BbN1dH8JULVVZY4WTdkF7tV9Ys6wLL1rubZnCMstOhNHueU5bLCrnRuDhKPDM4g6sw4Bel5Gzqg==}
 
@@ -689,71 +679,71 @@ packages:
       next:
         optional: true
 
-  '@splinetool/runtime@1.10.73':
-    resolution: {integrity: sha512-VirKiO226oHuhKYl5SH1ymBS/qvxqErpP8yVy8j3Svd3NKSPIDoNB4tOz2SjVPzPtVUr9JNy4TSpuCu/4QCWwg==}
+  '@splinetool/runtime@1.10.85':
+    resolution: {integrity: sha512-dpfsXTq/IF7pu98al6HX+tAkdM9+CU3l1TpGtkqZ81GHuirl0/UINAwHQLspvrwIstaC2yqN0OOQXd3cYLFYDA==}
 
   '@swc/helpers@0.5.17':
     resolution: {integrity: sha512-5IKx/Y13RsYd+sauPb2x+U/xZikHjolzfuDgTAl/Tdf3Q8rslRvC19NKDLgAJQ6wsqADk10ntlv08nPFw/gO/A==}
 
-  '@tailwindcss/node@4.1.14':
-    resolution: {integrity: sha512-hpz+8vFk3Ic2xssIA3e01R6jkmsAhvkQdXlEbRTk6S10xDAtiQiM3FyvZVGsucefq764euO/b8WUW9ysLdThHw==}
+  '@tailwindcss/node@4.1.15':
+    resolution: {integrity: sha512-HF4+7QxATZWY3Jr8OlZrBSXmwT3Watj0OogeDvdUY/ByXJHQ+LBtqA2brDb3sBxYslIFx6UP94BJ4X6a4L9Bmw==}
 
-  '@tailwindcss/oxide-android-arm64@4.1.14':
-    resolution: {integrity: sha512-a94ifZrGwMvbdeAxWoSuGcIl6/DOP5cdxagid7xJv6bwFp3oebp7y2ImYsnZBMTwjn5Ev5xESvS3FFYUGgPODQ==}
+  '@tailwindcss/oxide-android-arm64@4.1.15':
+    resolution: {integrity: sha512-TkUkUgAw8At4cBjCeVCRMc/guVLKOU1D+sBPrHt5uVcGhlbVKxrCaCW9OKUIBv1oWkjh4GbunD/u/Mf0ql6kEA==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [android]
 
-  '@tailwindcss/oxide-darwin-arm64@4.1.14':
-    resolution: {integrity: sha512-HkFP/CqfSh09xCnrPJA7jud7hij5ahKyWomrC3oiO2U9i0UjP17o9pJbxUN0IJ471GTQQmzwhp0DEcpbp4MZTA==}
+  '@tailwindcss/oxide-darwin-arm64@4.1.15':
+    resolution: {integrity: sha512-xt5XEJpn2piMSfvd1UFN6jrWXyaKCwikP4Pidcf+yfHTSzSpYhG3dcMktjNkQO3JiLCp+0bG0HoWGvz97K162w==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [darwin]
 
-  '@tailwindcss/oxide-darwin-x64@4.1.14':
-    resolution: {integrity: sha512-eVNaWmCgdLf5iv6Qd3s7JI5SEFBFRtfm6W0mphJYXgvnDEAZ5sZzqmI06bK6xo0IErDHdTA5/t7d4eTfWbWOFw==}
+  '@tailwindcss/oxide-darwin-x64@4.1.15':
+    resolution: {integrity: sha512-TnWaxP6Bx2CojZEXAV2M01Yl13nYPpp0EtGpUrY+LMciKfIXiLL2r/SiSRpagE5Fp2gX+rflp/Os1VJDAyqymg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [darwin]
 
-  '@tailwindcss/oxide-freebsd-x64@4.1.14':
-    resolution: {integrity: sha512-QWLoRXNikEuqtNb0dhQN6wsSVVjX6dmUFzuuiL09ZeXju25dsei2uIPl71y2Ic6QbNBsB4scwBoFnlBfabHkEw==}
+  '@tailwindcss/oxide-freebsd-x64@4.1.15':
+    resolution: {integrity: sha512-quISQDWqiB6Cqhjc3iWptXVZHNVENsWoI77L1qgGEHNIdLDLFnw3/AfY7DidAiiCIkGX/MjIdB3bbBZR/G2aJg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [freebsd]
 
-  '@tailwindcss/oxide-linux-arm-gnueabihf@4.1.14':
-    resolution: {integrity: sha512-VB4gjQni9+F0VCASU+L8zSIyjrLLsy03sjcR3bM0V2g4SNamo0FakZFKyUQ96ZVwGK4CaJsc9zd/obQy74o0Fw==}
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.1.15':
+    resolution: {integrity: sha512-ObG76+vPlab65xzVUQbExmDU9FIeYLQ5k2LrQdR2Ud6hboR+ZobXpDoKEYXf/uOezOfIYmy2Ta3w0ejkTg9yxg==}
     engines: {node: '>= 10'}
     cpu: [arm]
     os: [linux]
 
-  '@tailwindcss/oxide-linux-arm64-gnu@4.1.14':
-    resolution: {integrity: sha512-qaEy0dIZ6d9vyLnmeg24yzA8XuEAD9WjpM5nIM1sUgQ/Zv7cVkharPDQcmm/t/TvXoKo/0knI3me3AGfdx6w1w==}
+  '@tailwindcss/oxide-linux-arm64-gnu@4.1.15':
+    resolution: {integrity: sha512-4WbBacRmk43pkb8/xts3wnOZMDKsPFyEH/oisCm2q3aLZND25ufvJKcDUpAu0cS+CBOL05dYa8D4U5OWECuH/Q==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
 
-  '@tailwindcss/oxide-linux-arm64-musl@4.1.14':
-    resolution: {integrity: sha512-ISZjT44s59O8xKsPEIesiIydMG/sCXoMBCqsphDm/WcbnuWLxxb+GcvSIIA5NjUw6F8Tex7s5/LM2yDy8RqYBQ==}
+  '@tailwindcss/oxide-linux-arm64-musl@4.1.15':
+    resolution: {integrity: sha512-AbvmEiteEj1nf42nE8skdHv73NoR+EwXVSgPY6l39X12Ex8pzOwwfi3Kc8GAmjsnsaDEbk+aj9NyL3UeyHcTLg==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
 
-  '@tailwindcss/oxide-linux-x64-gnu@4.1.14':
-    resolution: {integrity: sha512-02c6JhLPJj10L2caH4U0zF8Hji4dOeahmuMl23stk0MU1wfd1OraE7rOloidSF8W5JTHkFdVo/O7uRUJJnUAJg==}
+  '@tailwindcss/oxide-linux-x64-gnu@4.1.15':
+    resolution: {integrity: sha512-+rzMVlvVgrXtFiS+ES78yWgKqpThgV19ISKD58Ck+YO5pO5KjyxLt7AWKsWMbY0R9yBDC82w6QVGz837AKQcHg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
 
-  '@tailwindcss/oxide-linux-x64-musl@4.1.14':
-    resolution: {integrity: sha512-TNGeLiN1XS66kQhxHG/7wMeQDOoL0S33x9BgmydbrWAb9Qw0KYdd8o1ifx4HOGDWhVmJ+Ul+JQ7lyknQFilO3Q==}
+  '@tailwindcss/oxide-linux-x64-musl@4.1.15':
+    resolution: {integrity: sha512-fPdEy7a8eQN9qOIK3Em9D3TO1z41JScJn8yxl/76mp4sAXFDfV4YXxsiptJcOwy6bGR+70ZSwFIZhTXzQeqwQg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
 
-  '@tailwindcss/oxide-wasm32-wasi@4.1.14':
-    resolution: {integrity: sha512-uZYAsaW/jS/IYkd6EWPJKW/NlPNSkWkBlaeVBi/WsFQNP05/bzkebUL8FH1pdsqx4f2fH/bWFcUABOM9nfiJkQ==}
+  '@tailwindcss/oxide-wasm32-wasi@4.1.15':
+    resolution: {integrity: sha512-sJ4yd6iXXdlgIMfIBXuVGp/NvmviEoMVWMOAGxtxhzLPp9LOj5k0pMEMZdjeMCl4C6Up+RM8T3Zgk+BMQ0bGcQ==}
     engines: {node: '>=14.0.0'}
     cpu: [wasm32]
     bundledDependencies:
@@ -764,24 +754,24 @@ packages:
       - '@emnapi/wasi-threads'
       - tslib
 
-  '@tailwindcss/oxide-win32-arm64-msvc@4.1.14':
-    resolution: {integrity: sha512-Az0RnnkcvRqsuoLH2Z4n3JfAef0wElgzHD5Aky/e+0tBUxUhIeIqFBTMNQvmMRSP15fWwmvjBxZ3Q8RhsDnxAA==}
+  '@tailwindcss/oxide-win32-arm64-msvc@4.1.15':
+    resolution: {integrity: sha512-sJGE5faXnNQ1iXeqmRin7Ds/ru2fgCiaQZQQz3ZGIDtvbkeV85rAZ0QJFMDg0FrqsffZG96H1U9AQlNBRLsHVg==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [win32]
 
-  '@tailwindcss/oxide-win32-x64-msvc@4.1.14':
-    resolution: {integrity: sha512-ttblVGHgf68kEE4om1n/n44I0yGPkCPbLsqzjvybhpwa6mKKtgFfAzy6btc3HRmuW7nHe0OOrSeNP9sQmmH9XA==}
+  '@tailwindcss/oxide-win32-x64-msvc@4.1.15':
+    resolution: {integrity: sha512-NLeHE7jUV6HcFKS504bpOohyi01zPXi2PXmjFfkzTph8xRxDdxkRsXm/xDO5uV5K3brrE1cCwbUYmFUSHR3u1w==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [win32]
 
-  '@tailwindcss/oxide@4.1.14':
-    resolution: {integrity: sha512-23yx+VUbBwCg2x5XWdB8+1lkPajzLmALEfMb51zZUBYaYVPDQvBSD/WYDqiVyBIo2BZFa3yw1Rpy3G2Jp+K0dw==}
+  '@tailwindcss/oxide@4.1.15':
+    resolution: {integrity: sha512-krhX+UOOgnsUuks2SR7hFafXmLQrKxB4YyRTERuCE59JlYL+FawgaAlSkOYmDRJdf1Q+IFNDMl9iRnBW7QBDfQ==}
     engines: {node: '>= 10'}
 
-  '@tailwindcss/vite@4.1.14':
-    resolution: {integrity: sha512-BoFUoU0XqgCUS1UXWhmDJroKKhNXeDzD7/XwabjkDIAbMnc4ULn5e2FuEuBbhZ6ENZoSYzKlzvZ44Yr6EUDUSA==}
+  '@tailwindcss/vite@4.1.15':
+    resolution: {integrity: sha512-B6s60MZRTUil+xKoZoGe6i0Iar5VuW+pmcGlda2FX+guDuQ1G1sjiIy1W0frneVpeL/ZjZ4KEgWZHNrIm++2qA==}
     peerDependencies:
       vite: ^5.2.0 || ^6 || ^7
 
@@ -830,13 +820,13 @@ packages:
   '@types/node@24.7.1':
     resolution: {integrity: sha512-CmyhGZanP88uuC5GpWU9q+fI61j2SkhO3UGMUdfYRE6Bcy0ccyzn1Rqj9YAB/ZY4kOXmNf0ocah5GtphmLMP6Q==}
 
-  '@types/react-dom@19.2.0':
-    resolution: {integrity: sha512-brtBs0MnE9SMx7px208g39lRmC5uHZs96caOJfTjFcYSLHNamvaSMfJNagChVNkup2SdtOxKX1FDBkRSJe1ZAg==}
+  '@types/react-dom@19.2.2':
+    resolution: {integrity: sha512-9KQPoO6mZCi7jcIStSnlOWn2nEF3mNmyr3rIAsGnAbQKYbRLyqmeSc39EVgtxXVia+LMT8j3knZLAZAh+xLmrw==}
     peerDependencies:
       '@types/react': ^19.2.0
 
-  '@types/react@19.2.0':
-    resolution: {integrity: sha512-1LOH8xovvsKsCBq1wnT4ntDUdCJKmnEakhsuoUSy6ExlHCkGP2hqnatagYTgFk6oeL0VU31u7SNjunPN+GchtA==}
+  '@types/react@19.2.2':
+    resolution: {integrity: sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA==}
 
   '@types/unist@2.0.11':
     resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==}
@@ -896,8 +886,8 @@ packages:
     resolution: {integrity: sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==}
     hasBin: true
 
-  astro@5.14.3:
-    resolution: {integrity: sha512-iRvl3eEYYdSYA195eNREjh43hqMMwKY1uoHYiKfLCB9G+bjFtaBtDe8R0ip7AbTD69wyOKgUCOtMad+lkOnT/w==}
+  astro@5.14.8:
+    resolution: {integrity: sha512-nKqCLs7BFvGQL9QWQOUqxHhlHtV0UMLXz1ANJygozvjcexBWS7FYkWI2LzRPMNYmbW4msIWNWnX2RvLdvI5Cnw==}
     engines: {node: 18.20.8 || ^20.3.0 || >=22.0.0, npm: '>=9.6.5', pnpm: '>=7.1.0'}
     hasBin: true
 
@@ -962,10 +952,6 @@ packages:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
 
-  chownr@3.0.0:
-    resolution: {integrity: sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==}
-    engines: {node: '>=18'}
-
   ci-info@4.3.1:
     resolution: {integrity: sha512-Wdy2Igu8OcBpI2pZePZ5oWjPC38tmDVx5WKUXKwlLYkA0ozo85sLsLvkBbBn/sZaSCMFOGZJ14fvW9t5/d7kdA==}
     engines: {node: '>=8'}
@@ -1041,10 +1027,6 @@ packages:
   destr@2.0.5:
     resolution: {integrity: sha512-ugFTXCtDZunbzasqBxrK93Ik/DRYsO6S/fedkWEMKqt04xZ4csmnmwGDBAb07QWNaGMAmnTIemsYZCksjATwsA==}
 
-  detect-libc@2.0.4:
-    resolution: {integrity: sha512-3UDv+G9CsCKO1WKMGw9fwq/SWJYbI0c5Y7LU1AXYoDdbhE2AHQ6N6Nb34sG8Fj7T5APy8qXDCKuuIHd1BR0tVA==}
-    engines: {node: '>=8'}
-
   detect-libc@2.1.2:
     resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
     engines: {node: '>=8'}
@@ -1303,68 +1285,74 @@ packages:
     resolution: {integrity: sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==}
     engines: {node: '>=6'}
 
-  lightningcss-darwin-arm64@1.30.1:
-    resolution: {integrity: sha512-c8JK7hyE65X1MHMN+Viq9n11RRC7hgin3HhYKhrMyaXflk5GVplZ60IxyoVtzILeKr+xAJwg6zK6sjTBJ0FKYQ==}
+  lightningcss-android-arm64@1.30.2:
+    resolution: {integrity: sha512-BH9sEdOCahSgmkVhBLeU7Hc9DWeZ1Eb6wNS6Da8igvUwAe0sqROHddIlvU06q3WyXVEOYDZ6ykBZQnjTbmo4+A==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.30.2:
+    resolution: {integrity: sha512-ylTcDJBN3Hp21TdhRT5zBOIi73P6/W0qwvlFEk22fkdXchtNTOU4Qc37SkzV+EKYxLouZ6M4LG9NfZ1qkhhBWA==}
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
     os: [darwin]
 
-  lightningcss-darwin-x64@1.30.1:
-    resolution: {integrity: sha512-k1EvjakfumAQoTfcXUcHQZhSpLlkAuEkdMBsI/ivWw9hL+7FtilQc0Cy3hrx0AAQrVtQAbMI7YjCgYgvn37PzA==}
+  lightningcss-darwin-x64@1.30.2:
+    resolution: {integrity: sha512-oBZgKchomuDYxr7ilwLcyms6BCyLn0z8J0+ZZmfpjwg9fRVZIR5/GMXd7r9RH94iDhld3UmSjBM6nXWM2TfZTQ==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [darwin]
 
-  lightningcss-freebsd-x64@1.30.1:
-    resolution: {integrity: sha512-kmW6UGCGg2PcyUE59K5r0kWfKPAVy4SltVeut+umLCFoJ53RdCUWxcRDzO1eTaxf/7Q2H7LTquFHPL5R+Gjyig==}
+  lightningcss-freebsd-x64@1.30.2:
+    resolution: {integrity: sha512-c2bH6xTrf4BDpK8MoGG4Bd6zAMZDAXS569UxCAGcA7IKbHNMlhGQ89eRmvpIUGfKWNVdbhSbkQaWhEoMGmGslA==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [freebsd]
 
-  lightningcss-linux-arm-gnueabihf@1.30.1:
-    resolution: {integrity: sha512-MjxUShl1v8pit+6D/zSPq9S9dQ2NPFSQwGvxBCYaBYLPlCWuPh9/t1MRS8iUaR8i+a6w7aps+B4N0S1TYP/R+Q==}
+  lightningcss-linux-arm-gnueabihf@1.30.2:
+    resolution: {integrity: sha512-eVdpxh4wYcm0PofJIZVuYuLiqBIakQ9uFZmipf6LF/HRj5Bgm0eb3qL/mr1smyXIS1twwOxNWndd8z0E374hiA==}
     engines: {node: '>= 12.0.0'}
     cpu: [arm]
     os: [linux]
 
-  lightningcss-linux-arm64-gnu@1.30.1:
-    resolution: {integrity: sha512-gB72maP8rmrKsnKYy8XUuXi/4OctJiuQjcuqWNlJQ6jZiWqtPvqFziskH3hnajfvKB27ynbVCucKSm2rkQp4Bw==}
+  lightningcss-linux-arm64-gnu@1.30.2:
+    resolution: {integrity: sha512-UK65WJAbwIJbiBFXpxrbTNArtfuznvxAJw4Q2ZGlU8kPeDIWEX1dg3rn2veBVUylA2Ezg89ktszWbaQnxD/e3A==}
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
     os: [linux]
 
-  lightningcss-linux-arm64-musl@1.30.1:
-    resolution: {integrity: sha512-jmUQVx4331m6LIX+0wUhBbmMX7TCfjF5FoOH6SD1CttzuYlGNVpA7QnrmLxrsub43ClTINfGSYyHe2HWeLl5CQ==}
+  lightningcss-linux-arm64-musl@1.30.2:
+    resolution: {integrity: sha512-5Vh9dGeblpTxWHpOx8iauV02popZDsCYMPIgiuw97OJ5uaDsL86cnqSFs5LZkG3ghHoX5isLgWzMs+eD1YzrnA==}
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
     os: [linux]
 
-  lightningcss-linux-x64-gnu@1.30.1:
-    resolution: {integrity: sha512-piWx3z4wN8J8z3+O5kO74+yr6ze/dKmPnI7vLqfSqI8bccaTGY5xiSGVIJBDd5K5BHlvVLpUB3S2YCfelyJ1bw==}
+  lightningcss-linux-x64-gnu@1.30.2:
+    resolution: {integrity: sha512-Cfd46gdmj1vQ+lR6VRTTadNHu6ALuw2pKR9lYq4FnhvgBc4zWY1EtZcAc6EffShbb1MFrIPfLDXD6Xprbnni4w==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [linux]
 
-  lightningcss-linux-x64-musl@1.30.1:
-    resolution: {integrity: sha512-rRomAK7eIkL+tHY0YPxbc5Dra2gXlI63HL+v1Pdi1a3sC+tJTcFrHX+E86sulgAXeI7rSzDYhPSeHHjqFhqfeQ==}
+  lightningcss-linux-x64-musl@1.30.2:
+    resolution: {integrity: sha512-XJaLUUFXb6/QG2lGIW6aIk6jKdtjtcffUT0NKvIqhSBY3hh9Ch+1LCeH80dR9q9LBjG3ewbDjnumefsLsP6aiA==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [linux]
 
-  lightningcss-win32-arm64-msvc@1.30.1:
-    resolution: {integrity: sha512-mSL4rqPi4iXq5YVqzSsJgMVFENoa4nGTT/GjO2c0Yl9OuQfPsIfncvLrEW6RbbB24WtZ3xP/2CCmI3tNkNV4oA==}
+  lightningcss-win32-arm64-msvc@1.30.2:
+    resolution: {integrity: sha512-FZn+vaj7zLv//D/192WFFVA0RgHawIcHqLX9xuWiQt7P0PtdFEVaxgF9rjM/IRYHQXNnk61/H/gb2Ei+kUQ4xQ==}
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
     os: [win32]
 
-  lightningcss-win32-x64-msvc@1.30.1:
-    resolution: {integrity: sha512-PVqXh48wh4T53F/1CCu8PIPCxLzWyCnn/9T5W1Jpmdy5h9Cwd+0YQS6/LwhHXSafuc61/xg9Lv5OrCby6a++jg==}
+  lightningcss-win32-x64-msvc@1.30.2:
+    resolution: {integrity: sha512-5g1yc73p+iAkid5phb4oVFMB45417DkRevRbt/El/gKXJk4jid+vPFF/AXbxn05Aky8PapwzZrdJShv5C0avjw==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [win32]
 
-  lightningcss@1.30.1:
-    resolution: {integrity: sha512-xi6IyHML+c9+Q3W0S4fCQJOym42pyurFiJUHEcEyHS0CeKzia4yZDEsLlqOFykxOdHpNy0NmvVO31vcSqAxJCg==}
+  lightningcss@1.30.2:
+    resolution: {integrity: sha512-utfs7Pr5uJyyvDETitgsaqSyjCb2qNRAtuqUeWIAKztsOYdcACf2KtARYXg2pSvhkt+9NfoaNY7fxjl6nuMjIQ==}
     engines: {node: '>= 12.0.0'}
 
   lodash.debounce@4.0.8:
@@ -1379,8 +1367,8 @@ packages:
   lru-cache@5.1.1:
     resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
 
-  lucide-react@0.544.0:
-    resolution: {integrity: sha512-t5tS44bqd825zAW45UQxpG2CvcC4urOwn2TrwSH8u+MjeE+1NnWl6QqeQ/6NdjMqdOygyiT9p3Ev0p1NJykxjw==}
+  lucide-react@0.546.0:
+    resolution: {integrity: sha512-Z94u6fKT43lKeYHiVyvyR8fT7pwCzDu7RyMPpTvh054+xahSgj4HFQ+NmflvzdXsoAjYGdCguGaFKYuvq0ThCQ==}
     peerDependencies:
       react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
@@ -1556,14 +1544,6 @@ packages:
   micromark@4.0.2:
     resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==}
 
-  minipass@7.1.2:
-    resolution: {integrity: sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==}
-    engines: {node: '>=16 || 14 >=14.17'}
-
-  minizlib@3.1.0:
-    resolution: {integrity: sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==}
-    engines: {node: '>= 18'}
-
   mrmime@2.0.1:
     resolution: {integrity: sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==}
     engines: {node: '>=10'}
@@ -1834,17 +1814,13 @@ packages:
   tailwind-merge@3.3.1:
     resolution: {integrity: sha512-gBXpgUm/3rp1lMZZrM/w7D8GKqshif0zAymAhbCyIt8KMe+0v9DQ7cdYLR4FHH/cKpdTXb+A/tKKU3eolfsI+g==}
 
-  tailwindcss@4.1.14:
-    resolution: {integrity: sha512-b7pCxjGO98LnxVkKjaZSDeNuljC4ueKUddjENJOADtubtdo8llTaJy7HwBMeLNSSo2N5QIAgklslK1+Ir8r6CA==}
+  tailwindcss@4.1.15:
+    resolution: {integrity: sha512-k2WLnWkYFkdpRv+Oby3EBXIyQC8/s1HOFMBUViwtAh6Z5uAozeUSMQlIsn/c6Q2iJzqG6aJT3wdPaRNj70iYxQ==}
 
   tapable@2.2.2:
     resolution: {integrity: sha512-Re10+NauLTMCudc7T5WLFLAwDhQ0JWdrMK+9B2M8zR5hRExKmsRDCBA7/aV/pNJFltmBFO5BAMlQFi/vq3nKOg==}
     engines: {node: '>=6'}
 
-  tar@7.5.1:
-    resolution: {integrity: sha512-nlGpxf+hv0v7GkWBK2V9spgactGOp0qvfWRxUMjqHyzrt3SgwE48DIv/FhqPHJYLHpgW1opq3nERbz5Anq7n1g==}
-    engines: {node: '>=18'}
-
   thumbhash@0.1.1:
     resolution: {integrity: sha512-kH5pKeIIBPQXAOni2AiY/Cu/NKdkFREdpH+TLdM0g6WA7RriCv0kPLgP731ady67MhTAqrVG/4mnEeibVuCJcg==}
 
@@ -2014,9 +1990,6 @@ packages:
   vfile-location@5.0.3:
     resolution: {integrity: sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==}
 
-  vfile-message@4.0.2:
-    resolution: {integrity: sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw==}
-
   vfile-message@4.0.3:
     resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
 
@@ -2092,10 +2065,6 @@ packages:
   yallist@3.1.1:
     resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
 
-  yallist@5.0.0:
-    resolution: {integrity: sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==}
-    engines: {node: '>=18'}
-
   yargs-parser@21.1.1:
     resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
     engines: {node: '>=12'}
@@ -2138,36 +2107,8 @@ snapshots:
 
   '@astrojs/compiler@2.13.0': {}
 
-  '@astrojs/internal-helpers@0.7.3': {}
-
   '@astrojs/internal-helpers@0.7.4': {}
 
-  '@astrojs/markdown-remark@6.3.7':
-    dependencies:
-      '@astrojs/internal-helpers': 0.7.3
-      '@astrojs/prism': 3.3.0
-      github-slugger: 2.0.0
-      hast-util-from-html: 2.0.3
-      hast-util-to-text: 4.0.2
-      import-meta-resolve: 4.2.0
-      js-yaml: 4.1.0
-      mdast-util-definitions: 6.0.0
-      rehype-raw: 7.0.0
-      rehype-stringify: 10.0.1
-      remark-gfm: 4.0.1
-      remark-parse: 11.0.0
-      remark-rehype: 11.1.2
-      remark-smartypants: 3.0.2
-      shiki: 3.13.0
-      smol-toml: 1.4.2
-      unified: 11.0.5
-      unist-util-remove-position: 5.0.0
-      unist-util-visit: 5.0.0
-      unist-util-visit-parents: 6.0.1
-      vfile: 6.0.3
-    transitivePeerDependencies:
-      - supports-color
-
   '@astrojs/markdown-remark@6.3.8':
     dependencies:
       '@astrojs/internal-helpers': 0.7.4
@@ -2194,12 +2135,12 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@astrojs/mdx@4.3.6(astro@5.14.3(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1)(rollup@4.52.4)(typescript@5.8.3))':
+  '@astrojs/mdx@4.3.7(astro@5.14.8(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.52.4)(typescript@5.8.3))':
     dependencies:
-      '@astrojs/markdown-remark': 6.3.7
+      '@astrojs/markdown-remark': 6.3.8
       '@mdx-js/mdx': 3.1.1
       acorn: 8.15.0
-      astro: 5.14.3(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1)(rollup@4.52.4)(typescript@5.8.3)
+      astro: 5.14.8(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.52.4)(typescript@5.8.3)
       es-module-lexer: 1.7.0
       estree-util-visit: 2.0.0
       hast-util-to-html: 9.0.5
@@ -2217,15 +2158,15 @@ snapshots:
     dependencies:
       prismjs: 1.30.0
 
-  '@astrojs/react@4.4.0(@types/node@24.7.1)(@types/react-dom@19.2.0(@types/react@19.2.0))(@types/react@19.2.0)(jiti@2.6.1)(lightningcss@1.30.1)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)':
+  '@astrojs/react@4.4.0(@types/node@24.7.1)(@types/react-dom@19.2.2(@types/react@19.2.2))(@types/react@19.2.2)(jiti@2.6.1)(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)':
     dependencies:
-      '@types/react': 19.2.0
-      '@types/react-dom': 19.2.0(@types/react@19.2.0)
-      '@vitejs/plugin-react': 4.7.0(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1))
+      '@types/react': 19.2.2
+      '@types/react-dom': 19.2.2(@types/react@19.2.2)
+      '@vitejs/plugin-react': 4.7.0(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2))
       react: 19.2.0
       react-dom: 19.2.0(react@19.2.0)
       ultrahtml: 1.6.0
-      vite: 6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1)
+      vite: 6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2)
     transitivePeerDependencies:
       - '@types/node'
       - jiti
@@ -2540,10 +2481,6 @@ snapshots:
   '@img/sharp-win32-x64@0.34.4':
     optional: true
 
-  '@isaacs/fs-minipass@4.0.1':
-    dependencies:
-      minipass: 7.1.2
-
   '@jridgewell/gen-mapping@0.3.12':
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
@@ -2595,22 +2532,22 @@ snapshots:
 
   '@oslojs/encoding@1.1.0': {}
 
-  '@radix-ui/react-compose-refs@1.1.2(@types/react@19.2.0)(react@19.2.0)':
+  '@radix-ui/react-compose-refs@1.1.2(@types/react@19.2.2)(react@19.2.0)':
     dependencies:
       react: 19.2.0
     optionalDependencies:
-      '@types/react': 19.2.0
+      '@types/react': 19.2.2
 
   '@radix-ui/react-icons@1.3.2(react@19.2.0)':
     dependencies:
       react: 19.2.0
 
-  '@radix-ui/react-slot@1.2.3(@types/react@19.2.0)(react@19.2.0)':
+  '@radix-ui/react-slot@1.2.3(@types/react@19.2.2)(react@19.2.0)':
     dependencies:
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.0)(react@19.2.0)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.2)(react@19.2.0)
       react: 19.2.0
     optionalDependencies:
-      '@types/react': 19.2.0
+      '@types/react': 19.2.2
 
   '@rolldown/pluginutils@1.0.0-beta.27': {}
 
@@ -2721,9 +2658,9 @@ snapshots:
 
   '@shikijs/vscode-textmate@10.0.2': {}
 
-  '@splinetool/react-spline@4.1.0(@splinetool/runtime@1.10.73)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)':
+  '@splinetool/react-spline@4.1.0(@splinetool/runtime@1.10.85)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)':
     dependencies:
-      '@splinetool/runtime': 1.10.73
+      '@splinetool/runtime': 1.10.85
       blurhash: 2.0.5
       lodash.debounce: 4.0.8
       react: 19.2.0
@@ -2731,7 +2668,7 @@ snapshots:
       react-merge-refs: 2.1.1
       thumbhash: 0.1.1
 
-  '@splinetool/runtime@1.10.73':
+  '@splinetool/runtime@1.10.85':
     dependencies:
       on-change: 4.0.2
       semver-compare: 1.0.0
@@ -2740,76 +2677,73 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
-  '@tailwindcss/node@4.1.14':
+  '@tailwindcss/node@4.1.15':
     dependencies:
       '@jridgewell/remapping': 2.3.5
       enhanced-resolve: 5.18.3
       jiti: 2.6.1
-      lightningcss: 1.30.1
+      lightningcss: 1.30.2
       magic-string: 0.30.19
       source-map-js: 1.2.1
-      tailwindcss: 4.1.14
+      tailwindcss: 4.1.15
 
-  '@tailwindcss/oxide-android-arm64@4.1.14':
+  '@tailwindcss/oxide-android-arm64@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide-darwin-arm64@4.1.14':
+  '@tailwindcss/oxide-darwin-arm64@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide-darwin-x64@4.1.14':
+  '@tailwindcss/oxide-darwin-x64@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide-freebsd-x64@4.1.14':
+  '@tailwindcss/oxide-freebsd-x64@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide-linux-arm-gnueabihf@4.1.14':
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide-linux-arm64-gnu@4.1.14':
+  '@tailwindcss/oxide-linux-arm64-gnu@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide-linux-arm64-musl@4.1.14':
+  '@tailwindcss/oxide-linux-arm64-musl@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide-linux-x64-gnu@4.1.14':
+  '@tailwindcss/oxide-linux-x64-gnu@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide-linux-x64-musl@4.1.14':
+  '@tailwindcss/oxide-linux-x64-musl@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide-wasm32-wasi@4.1.14':
+  '@tailwindcss/oxide-wasm32-wasi@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide-win32-arm64-msvc@4.1.14':
+  '@tailwindcss/oxide-win32-arm64-msvc@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide-win32-x64-msvc@4.1.14':
+  '@tailwindcss/oxide-win32-x64-msvc@4.1.15':
     optional: true
 
-  '@tailwindcss/oxide@4.1.14':
-    dependencies:
-      detect-libc: 2.0.4
-      tar: 7.5.1
+  '@tailwindcss/oxide@4.1.15':
     optionalDependencies:
-      '@tailwindcss/oxide-android-arm64': 4.1.14
-      '@tailwindcss/oxide-darwin-arm64': 4.1.14
-      '@tailwindcss/oxide-darwin-x64': 4.1.14
-      '@tailwindcss/oxide-freebsd-x64': 4.1.14
-      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.1.14
-      '@tailwindcss/oxide-linux-arm64-gnu': 4.1.14
-      '@tailwindcss/oxide-linux-arm64-musl': 4.1.14
-      '@tailwindcss/oxide-linux-x64-gnu': 4.1.14
-      '@tailwindcss/oxide-linux-x64-musl': 4.1.14
-      '@tailwindcss/oxide-wasm32-wasi': 4.1.14
-      '@tailwindcss/oxide-win32-arm64-msvc': 4.1.14
-      '@tailwindcss/oxide-win32-x64-msvc': 4.1.14
+      '@tailwindcss/oxide-android-arm64': 4.1.15
+      '@tailwindcss/oxide-darwin-arm64': 4.1.15
+      '@tailwindcss/oxide-darwin-x64': 4.1.15
+      '@tailwindcss/oxide-freebsd-x64': 4.1.15
+      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.1.15
+      '@tailwindcss/oxide-linux-arm64-gnu': 4.1.15
+      '@tailwindcss/oxide-linux-arm64-musl': 4.1.15
+      '@tailwindcss/oxide-linux-x64-gnu': 4.1.15
+      '@tailwindcss/oxide-linux-x64-musl': 4.1.15
+      '@tailwindcss/oxide-wasm32-wasi': 4.1.15
+      '@tailwindcss/oxide-win32-arm64-msvc': 4.1.15
+      '@tailwindcss/oxide-win32-x64-msvc': 4.1.15
 
-  '@tailwindcss/vite@4.1.14(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1))':
+  '@tailwindcss/vite@4.1.15(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2))':
     dependencies:
-      '@tailwindcss/node': 4.1.14
-      '@tailwindcss/oxide': 4.1.14
-      tailwindcss: 4.1.14
-      vite: 6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1)
+      '@tailwindcss/node': 4.1.15
+      '@tailwindcss/oxide': 4.1.15
+      tailwindcss: 4.1.15
+      vite: 6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2)
 
   '@types/babel__core@7.20.5':
     dependencies:
@@ -2868,11 +2802,11 @@ snapshots:
     dependencies:
       undici-types: 7.14.0
 
-  '@types/react-dom@19.2.0(@types/react@19.2.0)':
+  '@types/react-dom@19.2.2(@types/react@19.2.2)':
     dependencies:
-      '@types/react': 19.2.0
+      '@types/react': 19.2.2
 
-  '@types/react@19.2.0':
+  '@types/react@19.2.2':
     dependencies:
       csstype: 3.1.3
 
@@ -2882,7 +2816,7 @@ snapshots:
 
   '@ungap/structured-clone@1.3.0': {}
 
-  '@vitejs/plugin-react@4.7.0(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1))':
+  '@vitejs/plugin-react@4.7.0(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2))':
     dependencies:
       '@babel/core': 7.28.0
       '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.28.0)
@@ -2890,7 +2824,7 @@ snapshots:
       '@rolldown/pluginutils': 1.0.0-beta.27
       '@types/babel__core': 7.20.5
       react-refresh: 0.17.0
-      vite: 6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1)
+      vite: 6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2)
     transitivePeerDependencies:
       - supports-color
 
@@ -2923,7 +2857,7 @@ snapshots:
 
   astring@1.9.0: {}
 
-  astro@5.14.3(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1)(rollup@4.52.4)(typescript@5.8.3):
+  astro@5.14.8(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.52.4)(typescript@5.8.3):
     dependencies:
       '@astrojs/compiler': 2.13.0
       '@astrojs/internal-helpers': 0.7.4
@@ -2979,8 +2913,8 @@ snapshots:
       unist-util-visit: 5.0.0
       unstorage: 1.17.1
       vfile: 6.0.3
-      vite: 6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1)
-      vitefu: 1.1.1(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1))
+      vite: 6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2)
+      vitefu: 1.1.1(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2))
       xxhash-wasm: 1.1.0
       yargs-parser: 21.1.1
       yocto-spinner: 0.2.3
@@ -3078,8 +3012,6 @@ snapshots:
     dependencies:
       readdirp: 4.1.2
 
-  chownr@3.0.0: {}
-
   ci-info@4.3.1: {}
 
   class-variance-authority@0.7.1:
@@ -3131,8 +3063,6 @@ snapshots:
 
   destr@2.0.5: {}
 
-  detect-libc@2.0.4: {}
-
   detect-libc@2.1.2: {}
 
   deterministic-object-hash@2.0.2:
@@ -3309,7 +3239,7 @@ snapshots:
       hast-util-from-parse5: 8.0.3
       parse5: 7.3.0
       vfile: 6.0.3
-      vfile-message: 4.0.2
+      vfile-message: 4.0.3
 
   hast-util-from-parse5@8.0.3:
     dependencies:
@@ -3397,7 +3327,7 @@ snapshots:
       space-separated-tokens: 2.0.2
       style-to-js: 1.1.17
       unist-util-position: 5.0.0
-      vfile-message: 4.0.2
+      vfile-message: 4.0.3
     transitivePeerDependencies:
       - supports-color
 
@@ -3483,50 +3413,54 @@ snapshots:
 
   kleur@4.1.5: {}
 
-  lightningcss-darwin-arm64@1.30.1:
+  lightningcss-android-arm64@1.30.2:
     optional: true
 
-  lightningcss-darwin-x64@1.30.1:
+  lightningcss-darwin-arm64@1.30.2:
     optional: true
 
-  lightningcss-freebsd-x64@1.30.1:
+  lightningcss-darwin-x64@1.30.2:
     optional: true
 
-  lightningcss-linux-arm-gnueabihf@1.30.1:
+  lightningcss-freebsd-x64@1.30.2:
     optional: true
 
-  lightningcss-linux-arm64-gnu@1.30.1:
+  lightningcss-linux-arm-gnueabihf@1.30.2:
     optional: true
 
-  lightningcss-linux-arm64-musl@1.30.1:
+  lightningcss-linux-arm64-gnu@1.30.2:
     optional: true
 
-  lightningcss-linux-x64-gnu@1.30.1:
+  lightningcss-linux-arm64-musl@1.30.2:
     optional: true
 
-  lightningcss-linux-x64-musl@1.30.1:
+  lightningcss-linux-x64-gnu@1.30.2:
     optional: true
 
-  lightningcss-win32-arm64-msvc@1.30.1:
+  lightningcss-linux-x64-musl@1.30.2:
     optional: true
 
-  lightningcss-win32-x64-msvc@1.30.1:
+  lightningcss-win32-arm64-msvc@1.30.2:
     optional: true
 
-  lightningcss@1.30.1:
+  lightningcss-win32-x64-msvc@1.30.2:
+    optional: true
+
+  lightningcss@1.30.2:
     dependencies:
       detect-libc: 2.1.2
     optionalDependencies:
-      lightningcss-darwin-arm64: 1.30.1
-      lightningcss-darwin-x64: 1.30.1
-      lightningcss-freebsd-x64: 1.30.1
-      lightningcss-linux-arm-gnueabihf: 1.30.1
-      lightningcss-linux-arm64-gnu: 1.30.1
-      lightningcss-linux-arm64-musl: 1.30.1
-      lightningcss-linux-x64-gnu: 1.30.1
-      lightningcss-linux-x64-musl: 1.30.1
-      lightningcss-win32-arm64-msvc: 1.30.1
-      lightningcss-win32-x64-msvc: 1.30.1
+      lightningcss-android-arm64: 1.30.2
+      lightningcss-darwin-arm64: 1.30.2
+      lightningcss-darwin-x64: 1.30.2
+      lightningcss-freebsd-x64: 1.30.2
+      lightningcss-linux-arm-gnueabihf: 1.30.2
+      lightningcss-linux-arm64-gnu: 1.30.2
+      lightningcss-linux-arm64-musl: 1.30.2
+      lightningcss-linux-x64-gnu: 1.30.2
+      lightningcss-linux-x64-musl: 1.30.2
+      lightningcss-win32-arm64-msvc: 1.30.2
+      lightningcss-win32-x64-msvc: 1.30.2
 
   lodash.debounce@4.0.8: {}
 
@@ -3538,7 +3472,7 @@ snapshots:
     dependencies:
       yallist: 3.1.1
 
-  lucide-react@0.544.0(react@19.2.0):
+  lucide-react@0.546.0(react@19.2.0):
     dependencies:
       react: 19.2.0
 
@@ -3667,7 +3601,7 @@ snapshots:
       parse-entities: 4.0.2
       stringify-entities: 4.0.4
       unist-util-stringify-position: 4.0.0
-      vfile-message: 4.0.2
+      vfile-message: 4.0.3
     transitivePeerDependencies:
       - supports-color
 
@@ -3991,12 +3925,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  minipass@7.1.2: {}
-
-  minizlib@3.1.0:
-    dependencies:
-      minipass: 7.1.2
-
   mrmime@2.0.1: {}
 
   ms@2.1.3: {}
@@ -4381,18 +4309,10 @@ snapshots:
 
   tailwind-merge@3.3.1: {}
 
-  tailwindcss@4.1.14: {}
+  tailwindcss@4.1.15: {}
 
   tapable@2.2.2: {}
 
-  tar@7.5.1:
-    dependencies:
-      '@isaacs/fs-minipass': 4.0.1
-      chownr: 3.0.0
-      minipass: 7.1.2
-      minizlib: 3.1.0
-      yallist: 5.0.0
-
   thumbhash@0.1.1: {}
 
   tiny-inflate@1.0.3: {}
@@ -4522,11 +4442,6 @@ snapshots:
       '@types/unist': 3.0.3
       vfile: 6.0.3
 
-  vfile-message@4.0.2:
-    dependencies:
-      '@types/unist': 3.0.3
-      unist-util-stringify-position: 4.0.0
-
   vfile-message@4.0.3:
     dependencies:
       '@types/unist': 3.0.3
@@ -4537,7 +4452,7 @@ snapshots:
       '@types/unist': 3.0.3
       vfile-message: 4.0.3
 
-  vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1):
+  vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2):
     dependencies:
       esbuild: 0.25.10
       fdir: 6.5.0(picomatch@4.0.3)
@@ -4549,11 +4464,11 @@ snapshots:
       '@types/node': 24.7.1
       fsevents: 2.3.3
       jiti: 2.6.1
-      lightningcss: 1.30.1
+      lightningcss: 1.30.2
 
-  vitefu@1.1.1(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1)):
+  vitefu@1.1.1(vite@6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2)):
     optionalDependencies:
-      vite: 6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.1)
+      vite: 6.3.6(@types/node@24.7.1)(jiti@2.6.1)(lightningcss@1.30.2)
 
   web-namespaces@2.0.1: {}
 
@@ -4573,8 +4488,6 @@ snapshots:
 
   yallist@3.1.1: {}
 
-  yallist@5.0.0: {}
-
   yargs-parser@21.1.1: {}
 
   yocto-queue@1.2.1: {}

www/src/components/Header.tsx

@@ -15,9 +15,10 @@ export function Header() {
   }, []);
 
   const navLinks = [
-    { href: '#features', label: 'Features' },
-    { href: '#screenshots', label: 'Screenshots' },
-    { href: '#installation', label: 'Installation' }
+    { href: '/#features', label: 'Features' },
+    { href: '/#use-cases', label: 'Use Cases' },
+    { href: '/#screenshots', label: 'Screenshots' },
+    { href: '/#installation', label: 'Installation' }
   ];
 
   return (
@@ -27,7 +28,7 @@ export function Header() {
       <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
         <div className="flex items-center justify-between h-16">
           {/* Logo */}
-          <a href="#" className="flex items-center gap-2 group">
+          <a href="/" className="flex items-center gap-2 group">
             <img
               src="/assets/logo.png"
               alt="Gitea Mirror Logo"

www/src/components/Hero.tsx

@@ -93,32 +93,6 @@ export function Hero() {
             />
           </a>
         </div>
-
-        {/* Call to action buttons */}
-        {/* <div className="mt-8 sm:mt-10 flex flex-col sm:flex-row items-center justify-center gap-3 sm:gap-4 px-4 z-20">
-          <Button
-            size="lg"
-            className="relative group w-full sm:w-auto min-h-[48px] text-base bg-gradient-to-r from-primary to-accent hover:from-primary/90 hover:to-accent/90 shadow-lg shadow-primary/25 hover:shadow-xl hover:shadow-primary/30 transition-all duration-300"
-            asChild
-          >
-            <a
-              href="https://github.com/RayLabsHQ/gitea-mirror"
-              target="_blank"
-              rel="noopener noreferrer"
-            >
-              Get Started
-              <ArrowRight className="ml-2 h-4 w-4 transition-transform group-hover:translate-x-1" />
-            </a>
-          </Button>
-          <Button
-            size="lg"
-            variant="outline"
-            className="relative w-full sm:w-auto min-h-[48px] text-base border-primary/20 hover:bg-primary/10 hover:border-primary/30 hover:text-foreground transition-all duration-300"
-            asChild
-          >
-            <a href="#features">View Features</a>
-          </Button>
-        </div> */}
       </div>
     </section>
   );

www/src/components/UseCases.astro

@@ -0,0 +1,74 @@
+---
+import { ArrowRight } from 'lucide-react';
+import { useCases } from '@/lib/use-cases';
+---
+
+<section id="use-cases" class="py-16 sm:py-24 px-4 sm:px-6 lg:px-8 bg-muted/30 border-y">
+  <div class="max-w-7xl mx-auto">
+    <div class="text-center max-w-3xl mx-auto mb-12 sm:mb-16">
+      <span class="inline-flex items-center rounded-full border px-3 py-1 text-xs font-semibold uppercase tracking-widest text-muted-foreground mb-4">
+        Use Cases
+      </span>
+      <h2 class="text-2xl sm:text-3xl md:text-4xl font-bold tracking-tight">
+        Proven Ways Teams Depend on
+        <span class="text-gradient from-primary to-accent block sm:inline"> Gitea Mirror</span>
+      </h2>
+      <p class="mt-4 text-base sm:text-lg text-muted-foreground">
+        Explore real-world workflows where automated mirroring removes risk, accelerates migrations, and keeps engineering teams shipping.
+      </p>
+    </div>
+
+    <div class="grid gap-4 sm:gap-6 lg:gap-8 lg:grid-cols-3">
+      {useCases.slice(0, 3).map((useCase) => (
+        <article class="group relative flex flex-col rounded-2xl border bg-background/80 p-6 sm:p-8 shadow-sm transition-all duration-300 hover:-translate-y-1 hover:shadow-lg">
+          <div class="absolute inset-0 rounded-2xl bg-gradient-to-br from-primary/5 via-accent/5 to-transparent opacity-0 group-hover:opacity-100 transition-opacity duration-300" />
+          <div class="relative flex flex-col h-full">
+            <h3 class="text-xl font-semibold mb-3">
+              {useCase.title}
+            </h3>
+            <p class="text-sm sm:text-base text-muted-foreground mb-4">
+              {useCase.summary}
+            </p>
+
+            <dl class="grid gap-3 text-sm sm:text-base text-muted-foreground">
+              <div>
+                <dt class="font-semibold text-foreground">Pain Point</dt>
+                <dd>{useCase.painPoint}</dd>
+              </div>
+              <div>
+                <dt class="font-semibold text-foreground">Outcome</dt>
+                <dd>{useCase.outcome}</dd>
+              </div>
+            </dl>
+
+            <div class="mt-6 flex flex-wrap gap-2">
+              {useCase.tags.map((tag) => (
+                <span class="inline-flex items-center rounded-full border border-muted px-3 py-1 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                  {tag}
+                </span>
+              ))}
+            </div>
+
+            <a
+              href={`/use-cases/${useCase.slug}/`}
+              class="mt-auto inline-flex items-center gap-2 pt-6 text-sm font-medium text-primary transition-colors hover:text-primary/80"
+            >
+              Read the playbook
+              <ArrowRight class="h-4 w-4 transition-transform group-hover:translate-x-1" />
+            </a>
+          </div>
+        </article>
+      ))}
+    </div>
+
+    <div class="mt-10 text-center">
+      <a
+        href="/use-cases/"
+        class="inline-flex items-center gap-2 rounded-full border border-primary/40 bg-primary/10 px-6 py-2 text-sm font-semibold text-primary transition-colors hover:bg-primary/15"
+      >
+        View more use cases
+        <ArrowRight class="h-4 w-4" />
+      </a>
+    </div>
+  </div>
+</section>

www/src/components/UseCasesList.tsx

@@ -0,0 +1,79 @@
+
+import { useCases } from '@/lib/use-cases';
+import { ArrowRight } from 'lucide-react';
+
+const featured = useCases.slice(0, 3);
+const more = useCases.slice(3);
+
+export function FeaturedUseCases() {
+  return (
+    <div className="mt-8 grid gap-6 lg:grid-cols-3">
+      {featured.map((item) => (
+        <article key={item.slug} className="group relative flex flex-col rounded-3xl border border-primary/50 bg-primary/5 p-6 sm:p-7 shadow-lg shadow-primary/10 transition-all duration-300 hover:-translate-y-1">
+          <div className="flex flex-wrap items-center gap-2 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
+            {item.tags.map((tag) => (
+              <span key={tag} className="inline-flex items-center rounded-full border border-muted px-2.5 py-1">{tag}</span>
+            ))}
+          </div>
+          <h2 className="mt-4 text-xl font-semibold sm:text-2xl text-foreground">{item.title}</h2>
+          <p className="mt-3 text-sm sm:text-base text-muted-foreground">{item.summary}</p>
+          <div className="mt-5 grid gap-3 text-sm text-muted-foreground">
+            <div>
+              <h3 className="text-xs font-semibold uppercase tracking-wide text-foreground/70">Pain point</h3>
+              <p>{item.painPoint}</p>
+            </div>
+            <div>
+              <h3 className="text-xs font-semibold uppercase tracking-wide text-foreground/70">Outcome</h3>
+              <p>{item.outcome}</p>
+            </div>
+          </div>
+          <a
+            href={`/use-cases/${item.slug}/`}
+            className="mt-6 inline-flex w-max items-center gap-2 rounded-full border border-primary/50 px-4 py-2 text-sm font-semibold text-primary transition-colors hover:bg-primary/10"
+          >
+            View playbook
+            <ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-1" />
+          </a>
+        </article>
+      ))}
+    </div>
+  );
+}
+
+export function MoreUseCases() {
+    return (
+        <div className="mt-8 grid gap-6 md:grid-cols-2">
+        {more.map((item) => (
+          <article key={item.slug} className="group relative flex flex-col rounded-3xl border border-muted bg-background/70 p-6 sm:p-7 transition-all duration-300 hover:-translate-y-1 hover:border-primary/40 hover:shadow-lg">
+            <div className="flex flex-wrap items-center gap-2 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
+              {item.tags.map((tag) => (
+                <span key={tag} className="inline-flex items-center rounded-full border border-muted px-2.5 py-1">{tag}</span>
+              ))}
+            </div>
+  
+            <h2 className="mt-4 text-xl font-semibold sm:text-2xl text-foreground/90">{item.title}</h2>
+            <p className="mt-3 text-sm sm:text-base text-muted-foreground">{item.summary}</p>
+  
+            <div className="mt-5 grid gap-3 text-sm text-muted-foreground">
+              <div>
+                <h3 className="text-xs font-semibold uppercase tracking-wide text-foreground/70">Pain point</h3>
+                <p>{item.painPoint}</p>
+              </div>
+              <div>
+                <h3 className="text-xs font-semibold uppercase tracking-wide text-foreground/70">Outcome</h3>
+                <p>{item.outcome}</p>
+              </div>
+            </div>
+  
+            <a
+              href={`/use-cases/${item.slug}/`}
+              className="mt-6 inline-flex w-max items-center gap-2 rounded-full border border-primary/50 px-4 py-2 text-sm font-semibold text-primary transition-colors hover:bg-primary/10"
+            >
+              View playbook
+              <ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-1" />
+            </a>
+          </article>
+        ))}
+      </div>
+    )
+}

www/src/layouts/UseCaseIndexLayout.astro

@@ -0,0 +1,115 @@
+---
+import '../styles/global.css';
+import { Header } from '../components/Header';
+import Footer from '../components/Footer.astro';
+
+const {
+  content: {
+    title = 'Use Case',
+    description = 'Explore how Gitea Mirror helps engineering teams stay resilient.',
+    canonical = 'https://gitea-mirror.com/use-cases',
+  }
+} = Astro.props;
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width" />
+    <title>{title} · Gitea Mirror</title>
+    <meta name="description" content={description} />
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <link rel="canonical" href={canonical} />
+    <script is:inline>
+      const theme = localStorage.getItem('theme') ||
+        (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+      document.documentElement.classList.toggle('dark', theme === 'dark');
+    </script>
+  </head>
+  <body class="min-h-screen bg-background text-foreground antialiased">
+    <Header client:load />
+    <main class="pt-24 pb-20">
+      <article class="use-case-content mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+        <slot />
+      </article>
+    </main>
+    <Footer />
+  </body>
+</html>
+
+<style is:global>
+  .use-case-content {
+    display: flex;
+    flex-direction: column;
+    gap: 2rem;
+    padding-top: 3rem;
+    padding-bottom: 3rem;
+    font-size: 1rem;
+    line-height: 1.75;
+  }
+
+  .use-case-content > :is(h1, h2, h3) {
+    font-weight: 700;
+    color: var(--foreground);
+    letter-spacing: -0.01em;
+  }
+
+  .use-case-content h1 {
+    font-size: clamp(2rem, 3vw + 1rem, 2.75rem);
+  }
+
+  .use-case-content h2 {
+    font-size: clamp(1.5rem, 2.5vw + 0.75rem, 2.125rem);
+    margin-top: 1rem;
+  }
+
+  .use-case-content h3 {
+    font-size: clamp(1.25rem, 1.5vw + 0.75rem, 1.5rem);
+  }
+
+  .use-case-content p {
+    margin: 0;
+    color: var(--muted-foreground);
+  }
+
+  .use-case-content ul,
+  .use-case-content ol {
+    padding-left: 1.5rem;
+    display: grid;
+    gap: 0.5rem;
+    color: var(--muted-foreground);
+  }
+
+  .use-case-content li::marker {
+    color: var(--primary);
+  }
+
+  .use-case-content pre {
+    background-color: color-mix(in srgb, var(--muted) 70%, transparent);
+    border-radius: 1rem;
+    padding: 1rem 1.25rem;
+    font-family: 'Fira Code', 'JetBrains Mono', ui-monospace, SFMono-Regular, monospace;
+    font-size: 0.95rem;
+    overflow-x: auto;
+  }
+
+  .use-case-content code:not(pre code) {
+    background-color: color-mix(in srgb, var(--muted) 70%, transparent);
+    color: var(--foreground);
+    padding: 0.1rem 0.35rem;
+    border-radius: 0.4rem;
+    font-size: 0.92em;
+  }
+
+  .use-case-content a {
+    color: color-mix(in srgb, var(--primary) 85%, var(--accent));
+    font-weight: 600;
+    text-decoration: underline;
+    text-decoration-thickness: 2px;
+    text-decoration-color: color-mix(in srgb, var(--primary) 50%, transparent);
+  }
+
+  .use-case-content a:hover {
+    text-decoration-color: var(--primary);
+  }
+</style>

www/src/layouts/UseCaseLayout.astro

@@ -0,0 +1,115 @@
+---
+import '../styles/global.css';
+import { Header } from '../components/Header';
+import Footer from '../components/Footer.astro';
+
+const {
+  content: {
+    title = 'Use Case',
+    description = 'Explore how Gitea Mirror helps engineering teams stay resilient.',
+    canonical = 'https://gitea-mirror.com/use-cases',
+  }
+} = Astro.props;
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width" />
+    <title>{title} · Gitea Mirror</title>
+    <meta name="description" content={description} />
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <link rel="canonical" href={canonical} />
+    <script is:inline>
+      const theme = localStorage.getItem('theme') ||
+        (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+      document.documentElement.classList.toggle('dark', theme === 'dark');
+    </script>
+  </head>
+  <body class="min-h-screen bg-background text-foreground antialiased">
+    <Header client:load />
+    <main class="pt-24 pb-20">
+      <article class="use-case-content mx-auto max-w-4xl px-4 sm:px-6 lg:px-8">
+        <slot />
+      </article>
+    </main>
+    <Footer />
+  </body>
+</html>
+
+<style is:global>
+  .use-case-content {
+    display: flex;
+    flex-direction: column;
+    gap: 2rem;
+    padding-top: 3rem;
+    padding-bottom: 3rem;
+    font-size: 1rem;
+    line-height: 1.75;
+  }
+
+  .use-case-content > :is(h1, h2, h3) {
+    font-weight: 700;
+    color: var(--foreground);
+    letter-spacing: -0.01em;
+  }
+
+  .use-case-content h1 {
+    font-size: clamp(2rem, 3vw + 1rem, 2.75rem);
+  }
+
+  .use-case-content h2 {
+    font-size: clamp(1.5rem, 2.5vw + 0.75rem, 2.125rem);
+    margin-top: 1rem;
+  }
+
+  .use-case-content h3 {
+    font-size: clamp(1.25rem, 1.5vw + 0.75rem, 1.5rem);
+  }
+
+  .use-case-content p {
+    margin: 0;
+    color: var(--muted-foreground);
+  }
+
+  .use-case-content ul,
+  .use-case-content ol {
+    padding-left: 1.5rem;
+    display: grid;
+    gap: 0.5rem;
+    color: var(--muted-foreground);
+  }
+
+  .use-case-content li::marker {
+    color: var(--primary);
+  }
+
+  .use-case-content pre {
+    background-color: color-mix(in srgb, var(--muted) 70%, transparent);
+    border-radius: 1rem;
+    padding: 1rem 1.25rem;
+    font-family: 'Fira Code', 'JetBrains Mono', ui-monospace, SFMono-Regular, monospace;
+    font-size: 0.95rem;
+    overflow-x: auto;
+  }
+
+  .use-case-content code:not(pre code) {
+    background-color: color-mix(in srgb, var(--muted) 70%, transparent);
+    color: var(--foreground);
+    padding: 0.1rem 0.35rem;
+    border-radius: 0.4rem;
+    font-size: 0.92em;
+  }
+
+  .use-case-content a {
+    color: color-mix(in srgb, var(--primary) 85%, var(--accent));
+    font-weight: 600;
+    text-decoration: underline;
+    text-decoration-thickness: 2px;
+    text-decoration-color: color-mix(in srgb, var(--primary) 50%, transparent);
+  }
+
+  .use-case-content a:hover {
+    text-decoration-color: var(--primary);
+  }
+</style>

www/src/lib/use-cases.ts

@@ -0,0 +1,75 @@
+export interface UseCase {
+  slug: string;
+  title: string;
+  summary: string;
+  painPoint: string;
+  outcome: string;
+  tags: string[];
+}
+
+export const useCases: UseCase[] = [
+  {
+    slug: 'backup-github-repositories',
+    title: 'Backup GitHub Repositories',
+    summary: 'Continuously mirror GitHub repositories into self-hosted Gitea so your side projects stay safe even when GitHub hiccups.',
+    painPoint: 'Homelabbers rely on GitHub availability but want local backups that preserve history, metadata, and LFS assets.',
+    outcome: 'Automated syncs capture full repository history, metadata, and file storage so you always have an up-to-date local copy.',
+    tags: ['Redundancy', 'Continuous Sync', 'Homelab'],
+  },
+  {
+    slug: 'deploy-with-helm-chart',
+    title: 'Deploy with Helm Chart',
+    summary: 'Install the project on Kubernetes in a few commands using the maintained Helm chart to keep your backup mirror humming.',
+    painPoint: 'Self-hosters want reproducible Git backups without hand-rolling manifests for every cluster or upgrade.',
+    outcome: 'Versioned Helm values capture backup config, making redeploys and upgrades fast, scriptable, and low-risk.',
+    tags: ['Kubernetes', 'Helm', 'Homelab'],
+  },
+  {
+    slug: 'proxmox-lxc-homelab',
+    title: 'Spin Up on Proxmox LXC',
+    summary: 'Run the one-liner Proxmox VE script to launch gitea-mirror inside a tuned LXC container for your lab backups.',
+    painPoint: 'Proxmox homelabbers want a repeatable Git backup without manually wiring containers, volumes, and services.',
+    outcome: 'The community script provisions the container, installs Bun, and wires persistence so mirroring works minutes after boot.',
+    tags: ['Proxmox', 'Automation', 'Homelab'],
+  },
+  {
+    slug: 'sync-github-to-self-hosted-gitea',
+    title: 'Sync GitHub to Self-Hosted Gitea',
+    summary: 'Run continuous mirrors so your homelab Gitea instance stays in lockstep with GitHub without manual pulls.',
+    painPoint: 'Tinkerers want to keep a local Gitea in sync but `git pull --mirror` cron jobs break on metadata and new repos.',
+    outcome: 'Gitea Mirror auto-discovers repos, syncs metadata, and respects intervals so your LAN copy matches upstream every hour.',
+    tags: ['Continuous Sync', 'Self-Hosted', 'Homelab'],
+  },
+  {
+    slug: 'preserve-github-history',
+    title: 'Preserve GitHub History Forever',
+    summary: 'Archive commit history, issues, and releases into Gitea so side projects survive account removals or repo deletion.',
+    painPoint: 'Homelab archivists fear SaaS changes wiping years of work, but manual exports miss metadata and LFS assets.',
+    outcome: 'Scheduled mirrors capture full history with metadata snapshots, giving you an air-gapped archive you control.',
+    tags: ['Archival', 'Metadata', 'Homelab'],
+  },
+  {
+    slug: 'github-backup-automation',
+    title: 'Automate GitHub Backups',
+    summary: 'Replace brittle scripts with policy-driven schedules, health checks, and alerts that keep your Git backups honest.',
+    painPoint: 'Cron jobs and shell scripts fail silently, leaving you with stale mirrors when you need a restore most.',
+    outcome: 'Gitea Mirror tracks sync status, retries failures, and exposes health endpoints so you can trust every backup window.',
+    tags: ['Automation', 'Observability', 'Homelab'],
+  },
+  {
+    slug: 'starred-repos-collection',
+    title: 'Build a Starred Repo Collection',
+    summary: 'Mirror starred GitHub projects into your own Gitea library so favorites stay browsable even when upstream disappears.',
+    painPoint: 'Curators star dozens of repos but lose them when owners delete or rename, and there’s no offline copy.',
+    outcome: 'The starred collector funnels every star into a dedicated Gitea org with metadata intact for long-term tinkering.',
+    tags: ['Curation', 'Automation', 'Homelab'],
+  },
+  {
+    slug: 'vendor-lock-in-prevention',
+    title: 'Stay Ready to Leave GitHub',
+    summary: 'Keep an always-current mirror so you can pivot from GitHub to self-hosted tooling whenever policies shift.',
+    painPoint: 'Indie builders worry about pricing, auth changes, or ToS updates but lack a live fallback they can swap to instantly.',
+    outcome: 'Continuous mirrors mean you can flip DNS to Gitea, keep working locally, and evaluate alternatives without downtime.',
+    tags: ['Vendor Independence', 'Continuity', 'Homelab'],
+  },
+];

www/src/pages/index.astro

@@ -4,6 +4,7 @@ import { Header } from '../components/Header';
 import { Hero } from '../components/Hero';
 import ShaderBackground from '../components/ShaderBackground.astro';
 import Features from '../components/Features.astro';
+import UseCases from '../components/UseCases.astro';
 import Screenshots from '../components/Screenshots.astro';
 import { Installation } from '../components/Installation';
 import { CTA } from '../components/CTA';
@@ -123,6 +124,7 @@ const structuredData = {
         <Hero client:load />
       </div>
       <Features />
+      <UseCases />
       <Screenshots />
       <Installation client:load />
       <CTA client:load />

www/src/pages/use-cases/backup-github-repositories.mdx

@@ -0,0 +1,120 @@
+---
+layout: ../../layouts/UseCaseLayout.astro
+title: "Backup GitHub Repositories with Gitea Mirror"
+description: "Run a homelab-friendly playbook to mirror GitHub into self-hosted Gitea with automated schedules, health checks, and restore drills."
+canonical: "https://gitea-mirror.com/use-cases/backup-github-repositories/"
+---
+
+# Backup GitHub Repositories with Gitea Mirror
+
+## Why homelabbers care
+
+GitHub is great—right up until an outage, SSO change, or account lockout strands your projects. Gitea Mirror keeps a self-hosted copy of everything (history, metadata, LFS) so you can keep working locally. This playbook walks through the minimal Docker setup the project ships with and shows how to prove your backups actually work.
+
+## Requirements
+
+- Docker Engine and Compose on the host that will run the mirror
+- A GitHub personal access token (classic) with `repo`, plus the `read:org` checkbox under `admin:org` when you mirror organizations (leave the write/admin boxes unchecked)
+- A self-hosted Gitea instance (can be on the same box) and admin or org owner credentials
+- Open ports 4321 (web UI) and 3000 (default Gitea) inside your network
+
+## Step-by-step
+
+### 1. Clone the repo and start the stack
+
+```bash
+git clone https://github.com/RayLabsHQ/gitea-mirror.git
+cd gitea-mirror
+docker compose -f docker-compose.alt.yml up -d
+```
+
+The `alt` compose file ships with sane defaults for a single-node backup mirror. It stores data in `./data`. To use a different path, edit the volume mapping (for example `- /srv/gitea-mirror:/app/data`).
+
+Verify the containers:
+
+```bash
+docker compose -f docker-compose.alt.yml ps
+docker compose -f docker-compose.alt.yml logs -f gitea-mirror
+```
+
+Wait for "Server started" before moving on.
+
+### 2. Generate tokens and connect GitHub
+
+1. Create a GitHub personal access token (classic) with `repo` enabled and, inside the `admin:org` section, check `read:org` so the mirror can list organization repositories—leave `write:org` and `admin:org` unchecked.
+2. Log in to Gitea and create an access token for an admin/owner account with `write:repository`.
+3. Visit `http://<host>:4321` and sign up—the first user becomes admin.
+4. Complete the setup wizard:
+   - Paste the GitHub PAT and Gitea URL/token.
+   - Choose which GitHub owners (user/org) to track.
+   - Leave sync interval at the default 1 hour to start.
+
+### 3. Stage your first backup job
+
+On the dashboard:
+
+1. Click **Mirror Repository** for a small test project.
+2. Open Gitea and confirm the mirror appears with the right owner/org.
+3. In **Configuration → Connections**, open the **Content & Data** section to enable **Mirror metadata** and **Git LFS** if you rely on issues, wikis, or large assets.
+
+For broader coverage, switch the organization strategy to **Preserve structure** so Gitea mirrors your GitHub org layout automatically.
+
+### 4. Turn on automatic syncs and cleanup
+
+Open **Configuration → Automation** in the web UI.
+
+- Enable **Automatic syncing** and pick an interval that matches how fresh you want the mirror (start with `60 minutes`, shorten for active repos).
+- Leave the scheduler enabled—auto-discovery ships with it, so new GitHub repositories and stars are pulled in on the next pass.
+- If you want the mirror to tidy up when GitHub repos disappear, enable **Handle orphaned repositories** and keep the action on **Archive** so history stays intact.
+
+<figure class="mt-8 flex flex-col items-center">
+  <img
+    src="/assets/configuration.png"
+    alt="Automation tab in Gitea Mirror showing the automatic syncing controls for GitHub backups."
+    class="w-full max-w-5xl rounded-xl border border-muted shadow-sm"
+    loading="lazy"
+  />
+  <figcaption class="mt-3 text-sm text-muted-foreground text-center">
+    Configure the scheduler and cleanup policies from the Automation tab so GitHub mirrors stay fresh without manual cron jobs.
+  </figcaption>
+</figure>
+
+### 5. Prove the backup works
+
+Treat the mirror like any other DR asset:
+
+1. Temporarily block outbound GitHub access on your machine.
+2. Clone from Gitea instead: `git clone http://<gitea-host>/<owner>/<repo>.git`.
+3. Confirm commit history, tags, releases, and issues exist.
+4. Remove the block and document the restore steps in your homelab wiki.
+
+## Health checks & monitoring
+
+- The container exposes `/api/health`; add it to Uptime Kuma, Healthchecks.io, or Prometheus.
+- Mirror failures surface in the activity log; consider exporting them through the `/api/events` endpoint.
+- Watch the `data/` volume on the host (e.g. `du -sh data/`) to make sure you have headroom for mirrored repos and LFS blobs.
+
+## Hardening tips
+
+- Put the stack behind a reverse proxy (Traefik, Caddy, Nginx) and enable TLS.
+- Rotate both GitHub and Gitea tokens quarterly; the UI will flag expired credentials.
+- Snapshot the `data/` volume (ZFS/BTRFS) or back it up with `restic` so the mirror survives host failure.
+
+## Next steps
+
+- Promote the mirror to read-only users who do not need GitHub access.
+- Layer on the [Helm](../deploy-with-helm-chart) or [Proxmox LXC](../proxmox-lxc-homelab) playbooks when you outgrow the single-node setup.
+
+## FAQ
+
+### Does Gitea Mirror copy issues, pull requests, releases, and LFS?
+
+Yes. Enable Mirror metadata, Mirror releases, and Git LFS from **Configuration → Connections → Content & Data**. Pull requests are mirrored as enriched issues with linked branches and metadata.
+
+### How often should I sync GitHub backups?
+
+Most homelabs pick 30–120 minutes. Faster schedules improve RPO but use more GitHub API quota; adjust by org/repo if only a few projects are critical.
+
+### Where are backups stored and how do I restore?
+
+Repositories and the SQLite DB live under the `data/` directory (or your configured volume). Restore by cloning from Gitea or by moving the volume to a fresh deployment and signing back in.

www/src/pages/use-cases/deploy-with-helm-chart.mdx

@@ -0,0 +1,148 @@
+---
+layout: ../../layouts/UseCaseLayout.astro
+title: "Deploy Gitea Mirror with the Helm Chart"
+description: "Install the Gitea Mirror backup service on Kubernetes with the official Helm chart, including secrets, persistence, and upgrade workflow."
+canonical: "https://gitea-mirror.com/use-cases/deploy-with-helm-chart/"
+---
+
+# Deploy Gitea Mirror with the Helm Chart
+
+## Why ship it to Kubernetes
+
+If your homelab already runs a cluster (k3s, Talos, MicroK8s), Helm is the fastest way to keep Gitea Mirror close to the rest of your self-hosted stack. The chart in [`helm/gitea-mirror`](https://github.com/RayLabsHQ/gitea-mirror/tree/main/helm/gitea-mirror) bundles the deployment, service, ingress, and persistence so you can version your backup mirror just like any other release.
+
+## Requirements
+
+- Kubernetes 1.23+ with storage (Rook, Longhorn, local-path, etc.)
+- Helm 3.8+
+- GitHub PAT and Gitea API token ready (same scopes as the Docker playbook)
+- Namespace with outbound access to GitHub and your Gitea host
+
+## Step-by-step
+
+### 1. Create a namespace (optional)
+
+```bash
+kubectl create namespace gitea-mirror
+```
+
+### 2. Provide credentials and install the chart
+
+The [chart README](https://github.com/RayLabsHQ/gitea-mirror/blob/main/helm/gitea-mirror/README.md) documents multiple supported approaches. Choose the one that matches how you manage secrets.
+
+**Inline quick start (no values file):**
+
+First, clone the repository or download the chart:
+```bash
+git clone https://github.com/RayLabsHQ/gitea-mirror.git
+cd gitea-mirror
+```
+
+Then install with credentials:
+```bash
+helm upgrade --install gitea-mirror ./helm/gitea-mirror \
+  --namespace gitea-mirror \
+  --set "gitea-mirror.github.username=<your-gh-username>" \
+  --set "gitea-mirror.github.token=<your-gh-token>" \
+  --set "gitea-mirror.gitea.url=https://gitea.example.com" \
+  --set "gitea-mirror.gitea.token=<your-gitea-token>"
+```
+
+**Using a values file:**
+
+```yaml
+# values-gitea-mirror.yaml
+gitea-mirror:
+  github:
+    username: "your-gh-user"
+    token: "ghp_your_token"
+  gitea:
+    url: "https://git.lab.local"
+    token: "gitea_your_token"
+
+persistence:
+  enabled: true
+  size: 1Gi
+```
+
+```bash
+helm upgrade --install gitea-mirror ./helm/gitea-mirror \
+  --namespace gitea-mirror \
+  --values values-gitea-mirror.yaml
+```
+
+**Bring your own Secret (recommended for production):**
+
+```bash
+kubectl -n gitea-mirror create secret generic gitea-mirror-secrets \
+  --from-literal=GITHUB_TOKEN="ghp_your_token" \
+  --from-literal=GITEA_TOKEN="gitea_your_token" \
+  --from-literal=ENCRYPTION_SECRET="$(openssl rand -base64 48)"
+```
+
+```yaml
+# values-gitea-mirror.yaml
+gitea-mirror:
+  existingSecret: "gitea-mirror-secrets"
+  github:
+    username: "your-gh-user"
+  gitea:
+    url: "https://git.lab.local"
+```
+
+Helm renders a `Deployment`, `Service`, optional Ingress/Gateway resources, and—when persistence is enabled—a PVC mounted at `/app/data` for the SQLite database and mirrored repositories.
+
+### 3. Verify the release
+
+```bash
+kubectl -n gitea-mirror get pods,svc,pvc
+kubectl -n gitea-mirror logs deploy/gitea-mirror --tail=100
+```
+
+Watch for `Server started` in the logs. Once ready, browse to the ingress host (or userland port-forward with `kubectl port-forward svc/gitea-mirror 4321:4321`). Complete the first-run wizard just like the Docker playbook.
+
+After the pod is healthy, open **Configuration → Connections** inside the UI to add GitHub owners, choose a destination strategy, and enable metadata/LFS mirroring.
+
+### 4. Keep it updated
+
+- Pull chart updates when you bump the repo: `git pull` then re-run the `helm upgrade` command.
+- Override the container image tag with `--set image.tag=v3.7.2` if you need to pin (defaults to `v{appVersion}` from Chart.yaml).
+- Use Helm rollbacks if a release misbehaves: `helm rollback gitea-mirror <REVISION> -n gitea-mirror`.
+
+## Observability
+
+- Attach the `/api/health` endpoint to your cluster’s probing (Kubernetes probes are already configured by the chart).
+- Expose the metrics endpoint via a `ServiceMonitor` if you run Prometheus; add `extraAnnotations` to make it discoverable.
+- Watch PVC growth with `kubectl df-pv` or your storage dashboard to ensure LFS blobs do not exhaust the volume.
+
+## Disaster-recovery drill
+
+1. Scale the deployment down: `kubectl -n gitea-mirror scale deploy gitea-mirror --replicas=0`.
+2. Snapshot the PVC (CSI snapshots or Velero).
+3. Restore into a test namespace and scale the deployment back up.
+4. Confirm you can log in and the mirrored repositories are intact.
+
+## Cleanup
+
+```bash
+helm uninstall gitea-mirror -n gitea-mirror
+kubectl delete namespace gitea-mirror
+```
+
+Remove the PVC manually if you want a clean slate: `kubectl delete pvc gitea-mirror-storage -n gitea-mirror`.
+
+Ready to run on bare metal instead? Head over to the [Proxmox LXC playbook](../proxmox-lxc-homelab).
+
+## FAQ
+
+### Where do I define GitHub owners and organizations?
+
+Add owners from the **Configuration → Connections** screen after the release is running. The chart seeds credentials and defaults, but owner discovery happens in the UI.
+
+### Can I manage secrets outside of Kubernetes?
+
+Yes. Leave `existingSecret` empty and the chart will create a secret with the values from the file, but using a pre-created secret keeps PATs out of Git history and lets you rotate them with `kubectl apply`.
+
+### How do I throttle syncs to fit my quota?
+
+Adjust `gitea-mirror.automation.schedule_interval` in your values file (default: 3600 seconds = 1 hour). Lower values mean more frequent syncs; higher values create quieter schedules. You can also configure intervals per owner/repository inside the web UI.

www/src/pages/use-cases/github-backup-automation.mdx

@@ -0,0 +1,93 @@
+---
+layout: ../../layouts/UseCaseLayout.astro
+title: "Automate GitHub Backups"
+description: "Replace fragile cron scripts with scheduled mirrors, health checks, and logging that keep GitHub backups trustworthy."
+canonical: "https://gitea-mirror.com/use-cases/github-backup-automation/"
+---
+
+# Automate GitHub Backups
+
+## Why automation beats cron
+
+Shell scripts and `git clone --mirror` jobs work until they don’t—usually when GitHub rotates tokens, repositories rename, or metadata gets missed. Gitea Mirror bundles scheduling, auto-discovery, and repository cleanup so your backups keep running while you sleep.
+
+## Requirements
+
+- Gitea Mirror deployment with outbound HTTPS access
+- GitHub PAT + Gitea token stored in the UI or supplied via environment variables
+- A monitoring target that can poll HTTP endpoints (Healthchecks.io, Uptime Kuma, Prometheus, etc.)
+
+## Step-by-step
+
+### 1. Enable automatic syncing
+
+1. Go to **Configuration → Automation**.
+2. Toggle **Automatic syncing** on and choose an interval that matches your recovery point objective (start with `30 minutes` for active teams, stretch to `12 hours` for archives).
+3. Confirm the scheduler is running by checking the **Last sync** and **Next sync** timestamps in the Automation card.
+
+### 2. Keep the repository list current
+
+- In **Configuration → Connections**, click **Import GitHub Data** so the dashboard knows about every repository, organization, and star you selected.
+- Enable **Mirror starred repositories** if you want personal favorites backed up, and set the **Starred repos organization** for tidy storage in Gitea.
+- Use the inline destination editor on the **Repositories** page when you need a repo to land in a different Gitea organization.
+
+### 3. Configure repository cleanup (optional)
+
+- Still on **Configuration → Automation**, enable **Handle orphaned repositories automatically**.
+- Leave the action on **Archive** to keep a read-only backup when a GitHub repo disappears, or switch to **Delete** if you require a strict mirror.
+- Disable **Dry run** after your first test so the cleanup service can act on what it finds.
+
+### 4. Monitor scheduler health
+
+- Point your monitoring system at `http://<mirror-host>:4321/api/health` to track uptime.
+- Review sync failures from the **Activity Log** page or export them via `/api/events` for long-term retention.
+- Run `bun run manage-db check` during maintenance windows to verify background tasks, migrations, and queue state.
+
+<figure class="mt-8 flex flex-col items-center">
+  <img
+    src="/assets/activity.png"
+    alt="Gitea Mirror activity log displaying recent GitHub backup jobs and their status."
+    class="w-full max-w-5xl rounded-xl border border-muted shadow-sm"
+    loading="lazy"
+  />
+  <figcaption class="mt-3 text-sm text-muted-foreground text-center">
+    The Activity Log highlights successful syncs and failures so you can react before GitHub backups fall behind.
+  </figcaption>
+</figure>
+
+### 5. Harden credentials and runbooks
+
+- Store GitHub and Gitea tokens via the Configuration UI—Gitea Mirror encrypts them at rest.
+- Rotate tokens on a schedule and note expiry dates in your homelab runbook; the dashboard surfaces failures when credentials expire.
+- Export the configuration JSON (`/api/export`) alongside your documentation so you can rebuild the mirror quickly if you need to redeploy.
+
+## Validate automation
+
+- Force a failure by temporarily revoking a PAT; the next scheduler run should flag the repository in the Activity Log. Restore the token and use **Sync Repository** to confirm recovery.
+- Run `bun run manage-db check` (or the UI health check) to ensure migrations and tasks are clean.
+- Spot-check the **Repositories** table or export the Activity Log CSV to confirm `Last mirrored` timestamps match your configured interval.
+
+## Best practices
+
+- Tune the sync interval to balance freshness with GitHub rate limits; most homelabs sit between 30 and 120 minutes.
+- Start with the cleanup action set to **Archive** until you are confident you will not remove something you still need.
+- Pair automation with the [Preserve GitHub History](../preserve-github-history/) playbook to maintain context, not just code.
+
+## Related playbooks
+
+- [Backup GitHub Repositories](../backup-github-repositories/)
+- [Run Gitea Mirror inside a Proxmox LXC](../proxmox-lxc-homelab/)
+
+## FAQ
+
+### What replaces my cron scripts?
+
+The built-in scheduler handles intervals, retries, and discovery. It also powers cleanup for deleted upstream repos (Archive/Delete) once enabled.
+
+### How do I get alerts if backups fail?
+
+Monitor `/api/health` with Healthchecks.io or Uptime Kuma and review the Activity Log. You can export failures via `/api/events` for centralized logging.
+
+### Will new repositories be discovered automatically?
+
+Yes. After importing your GitHub data once, the scheduler’s discovery step keeps the inventory updated and mirrors new repositories on the next run.

www/src/pages/use-cases/index.mdx

@@ -0,0 +1,120 @@
+---
+layout: ../../layouts/UseCaseIndexLayout.astro
+title: "Gitea Mirror Use Cases"
+description: "Homelab-friendly playbooks that keep GitHub repos mirrored inside Gitea without promising enterprise guarantees."
+canonical: "https://gitea-mirror.com/use-cases/"
+---
+
+import { ArrowRight, ShieldAlert, Sparkles, Home } from 'lucide-react';
+import { useCases } from '@/lib/use-cases';
+
+<section class="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+  <div class="rounded-3xl border border-primary/20 bg-gradient-to-br from-primary/10 via-background to-background p-8 sm:p-12 shadow-lg">
+    <div class="flex flex-wrap items-center gap-3 text-xs font-semibold uppercase tracking-[0.25em] text-primary">
+      <Sparkles class="h-4 w-4" />
+      Built by and for homelab tinkerers
+    </div>
+    <h1 class="mt-6 text-3xl font-bold sm:text-4xl md:text-[2.75rem] md:leading-tight">
+      Gitea Mirror in Action: Use Cases for Self-Hosted GitHub Backups
+    </h1>
+    <p class="mt-4 max-w-3xl text-base sm:text-lg text-muted-foreground">
+      Gitea Mirror is an open-source side project. It’s perfect for your homelab, indie dev studio, or early-stage team that
+      needs backups and optional failover. There’s <strong class="font-semibold text-foreground">no enterprise SLA</strong>—just
+      practical playbooks you can own, fork, and improve.
+    </p>
+
+    <div class="mt-6 grid gap-4 sm:grid-cols-2">
+      <div class="flex items-start gap-3 rounded-2xl border border-muted bg-background/80 p-4">
+        <div>
+          <h2 class="!mt-0 text-sm font-semibold uppercase tracking-wide text-foreground/80">Ideal for</h2>
+          <p class="mt-1 text-sm text-muted-foreground">
+            Homelabbers, solo builders, and scrappy startups that want GitHub peace of mind without managed pricing.
+          </p>
+        </div>
+      </div>
+      <div class="flex items-start gap-3 rounded-2xl border border-muted bg-background/80 p-4">
+        <div>
+          <h2 class="!mt-0 text-sm font-semibold uppercase tracking-wide text-foreground/80">Worth noting</h2>
+          <p class="mt-1 text-sm text-muted-foreground">
+            Community support only. No compliance guarantees, no 24/7 pager. Kick the tires before depending on it.
+          </p>
+        </div>
+      </div>
+    </div>
+  </div>
+</section>
+
+<section id="use-cases" class="py-16 sm:py-24 px-4 sm:px-6 lg:px-8">
+  <div class="max-w-7xl mx-auto">
+    <div class="text-center max-w-3xl mx-auto mb-12 sm:mb-16">
+      <span class="inline-flex items-center rounded-full border px-3 py-1 text-xs font-semibold uppercase tracking-widest text-muted-foreground mb-4">
+        Use Cases
+      </span>
+      <h2 class="text-2xl sm:text-3xl md:text-4xl font-bold tracking-tight">
+        Real-World Gitea Mirror Workflows
+      </h2>
+      <p class="mt-4 text-base sm:text-lg text-muted-foreground">
+        Discover how developers and teams are using Gitea Mirror to create reliable, self-hosted backups of their GitHub repositories. These use cases provide step-by-step instructions for common scenarios.
+      </p>
+    </div>
+
+    <div class="grid gap-4 sm:gap-6 lg:gap-8 lg:grid-cols-3">
+      {useCases.map((useCase) => (
+        <article class="group relative flex flex-col rounded-2xl border bg-background/80 p-6 sm:p-8 shadow-sm transition-all duration-300 hover:-translate-y-1 hover:shadow-lg">
+          <div class="absolute inset-0 rounded-2xl bg-gradient-to-br from-primary/5 via-accent/5 to-transparent opacity-0 group-hover:opacity-100 transition-opacity duration-300" />
+          <div class="relative flex flex-col h-full">
+            <h3 class="text-xl font-semibold mb-3">
+              {useCase.title}
+            </h3>
+            <p class="text-sm sm:text-base text-muted-foreground mb-4">
+              {useCase.summary}
+            </p>
+
+            <dl class="grid gap-3 text-sm sm:text-base text-muted-foreground">
+              <div>
+                <dt class="font-semibold text-foreground">Pain Point</dt>
+                <dd>{useCase.painPoint}</dd>
+              </div>
+              <div>
+                <dt class="font-semibold text-foreground">Outcome</dt>
+                <dd>{useCase.outcome}</dd>
+              </div>
+            </dl>
+
+            <div class="mt-6 flex flex-wrap gap-2">
+              {useCase.tags.map((tag) => (
+                <span class="inline-flex items-center rounded-full border border-muted px-3 py-1 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                  {tag}
+                </span>
+              ))}
+            </div>
+
+            <a
+              href={`/use-cases/${useCase.slug}/`}
+              class="mt-auto inline-flex items-center gap-2 pt-6 text-sm font-medium text-primary transition-colors hover:text-primary/80"
+            >
+              Read the playbook
+              <ArrowRight class="h-4 w-4 transition-transform group-hover:translate-x-1" />
+            </a>
+          </div>
+        </article>
+      ))}
+    </div>
+  </div>
+</section>
+
+<section class="mx-auto mt-16 max-w-7xl px-4 sm:px-6 lg:px-8 pb-8">
+  <div class="rounded-3xl border border-primary/20 bg-primary/5 p-6 sm:p-10 text-center">
+    <h2 class="text-2xl font-semibold sm:text-3xl">Have a niche workflow?</h2>
+    <p class="mt-3 text-sm sm:text-base text-muted-foreground">
+      Fork the project, open an issue, or drop a PR. These guides are community-made—just like the tooling behind them.
+    </p>
+    <a
+      href="https://github.com/RayLabsHQ/gitea-mirror"
+      class="mt-6 inline-flex items-center gap-2 rounded-full border border-primary/50 bg-background px-5 py-2 text-sm font-semibold text-primary transition-colors hover:bg-primary/10"
+    >
+      Contribute on GitHub
+      <ArrowRight class="h-4 w-4" />
+    </a>
+  </div>
+</section>

www/src/pages/use-cases/preserve-github-history.mdx

@@ -0,0 +1,97 @@
+---
+layout: ../../layouts/UseCaseLayout.astro
+title: "Preserve GitHub History Forever"
+description: "Archive commits, issues, releases, and LFS assets into Gitea so hobby projects survive account removals or repo deletions."
+canonical: "https://gitea-mirror.com/use-cases/preserve-github-history/"
+---
+
+# Preserve GitHub History Forever
+
+## Keep the entire story, not just the code
+
+GitHub accounts get banned, repos go private, and owners rage-delete history. If you care about the full timeline—issues, releases, wiki—Gitea Mirror snapshots everything on a schedule so the story survives in your homelab.
+
+## Requirements
+
+- Running Gitea Mirror (follow the [backup playbook](../backup-github-repositories/))
+- GitHub PAT with `repo` enabled (add the `read:org` checkbox under `admin:org` when you archive organization repositories; leave write/admin unchecked)
+- Destination Gitea with enough disk for cloned repos + attachments
+- Optional: object storage or snapshots for long-term archiving of the mirror volume
+
+## Step-by-step
+
+### 1. Set archival-friendly defaults
+
+In **Configuration → Connections**, open **Content & Data**:
+
+- Enable **Mirror metadata** and choose the components you care about (issues, pull requests, labels, milestones, wiki).
+- Enable **Mirror releases** and raise the **Latest releases** limit if you need a deeper history of release assets.
+- Toggle **Git LFS (Large File Storage)** so binaries follow the repository, assuming LFS is enabled in your Gitea instance.
+
+### 2. Create an "Archive" organization in Gitea
+
+1. In Gitea, create an org like `github-archive` and grant read-only access to everyone who needs the history.
+2. Back in Gitea Mirror under **Configuration → Connections**, pick the **Preserve structure** strategy (or set a destination organization) so repos land in that archive org.
+3. Tighten permissions in Gitea—disable pushes for regular users so the archive stays immutable while the service updates it via its token.
+
+<figure class="mt-8 flex flex-col items-center">
+  <img
+    src="/assets/repositories.png"
+    alt="Repositories dashboard in Gitea Mirror showing archived GitHub projects synced into Gitea."
+    class="w-full max-w-5xl rounded-xl border border-muted shadow-sm"
+    loading="lazy"
+  />
+  <figcaption class="mt-3 text-sm text-muted-foreground text-center">
+    Keep every GitHub project visible in the repositories dashboard while routing mirrors into a dedicated archive organization.
+  </figcaption>
+</figure>
+
+### 3. Choose retention & cadence
+
+- In **Configuration → Automation**, enable **Automatic syncing** and set the interval (`1h` keeps fast-moving repos current; `12h` is usually enough for archives).
+- Turn on **Handle orphaned repositories automatically** and leave the action on **Archive** so anything deleted upstream is preserved locally but marked read-only.
+- Bump the **Latest releases** limit or run an occasional manual sync from the **Repositories** table when you need older release assets.
+
+### 4. Record provenance
+
+- Add a README or label inside the archive organization that captures the upstream URL, first mirrored date, and token owner.
+- Export a CSV from the **Repositories** view or hit `/api/events` quarterly so you retain a human-friendly change log.
+- Store the configuration export (`/api/export`) alongside your disaster-recovery docs in case you need to rebuild the service.
+
+### 5. Back up the backup
+
+- Snapshots: Use ZFS/BTRFS or Proxmox backups on the mirror’s data volume.
+- Offsite: `restic`/`rclone` the `data/` directory to a NAS or object store.
+- Test: Restore to a test Gitea instance and spot-check history every few months.
+
+## Verify the archive
+
+1. Delete a draft issue on GitHub.
+2. Wait for the next sync; open the issue in Gitea—you should still see the original content.
+3. Compare `git tag -l` in both remotes to ensure releases match.
+4. Use `git lfs ls-files` to confirm large assets made it across.
+
+## Maintenance checklist
+
+- Rotate tokens annually and document the rotation date in the repo README.
+- Monitor disk growth; configure `persistence.size` if you run the Helm chart.
+- Log anomalies—failed runs, conflicts—in your homelab journal to track trends.
+
+## Related playbooks
+
+- [Automate GitHub Backups](../github-backup-automation/)
+- [Build a Starred Repo Collection](../starred-repos-collection/)
+
+## FAQ
+
+### Does this preserve issues, pull requests, and releases?
+
+Yes—enable Mirror metadata and Mirror releases from **Configuration → Connections → Content & Data**. Pull requests copy as enriched issues, keeping discussion and labels.
+
+### What happens if a GitHub repo is deleted or goes private?
+
+Turn on Handle orphaned repositories automatically and use Archive to keep a read-only copy locally. Delete enforces a strict mirror, removing the repo.
+
+### How much storage will I need long-term?
+
+Plan for repo size plus attachments and LFS. Monitor the mirror’s `data/` volume growth and consider ZFS/BTRFS snapshots or object storage for older archives.

www/src/pages/use-cases/proxmox-lxc-homelab.mdx

@@ -0,0 +1,108 @@
+---
+layout: ../../layouts/UseCaseLayout.astro
+title: "Run Gitea Mirror inside a Proxmox LXC"
+description: "Provision the community-maintained Proxmox VE LXC container for Gitea Mirror and wire it into your homelab backup workflow."
+canonical: "https://gitea-mirror.com/use-cases/proxmox-lxc-homelab/"
+---
+
+# Run Gitea Mirror inside a Proxmox LXC
+
+## Why run it on Proxmox
+
+When most of your homelab lives in Proxmox VE, the community LXC script is the fastest path from zero to a managed Gitea Mirror node. It handles Bun, systemd, persistent storage, and future upgrades so you can focus on keeping Git backups fresh.
+
+## Requirements
+
+- Proxmox VE host with the [community-scripts repository](https://community-scripts.github.io/ProxmoxVE/) enabled
+- Storage pool with ~6 GB free (default script allocation) and an available bridge (usually `vmbr0`)
+- GitHub PAT and Gitea token scoped for mirroring
+- DNS or IP address for the container on your LAN
+
+## Step-by-step
+
+### 1. Launch the installer
+
+SSH into the Proxmox host and run:
+
+```bash
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/gitea-mirror.sh)"
+```
+
+The helper script prompts for:
+
+- **Node**: the Proxmox host that will own the container
+- **Storage**: local-lvm, ZFS dataset, etc.
+- **Network bridge**: e.g. `vmbr0`
+- **IP assignment**: DHCP or static (consider static for a backup appliance)
+- **Container size**: defaults to 2 vCPU, 2 GiB RAM, 6 GiB disk—bump RAM if you mirror large orgs
+
+Accept the defaults or adjust as needed. The script downloads the release, installs Bun, seeds systemd, and prints the access URL on completion.
+
+### 2. First login and setup
+
+1. Browse to `http://<container-ip>:4321`.
+2. Create the admin account (first user = admin).
+3. Enter your GitHub PAT and Gitea API token in the onboarding wizard.
+4. Select the GitHub owners you want mirrored—auto-discovery runs by default once scheduling is enabled, so new repositories appear automatically.
+
+### 3. Validate persistence and services
+
+Inside the container (`pct enter <CTID>`):
+
+```bash
+systemctl status gitea-mirror
+ls /opt/gitea-mirror/data
+```
+
+You should see `gitea-mirror.db` and a `repos/` directory. Data lives under `/opt/gitea-mirror/data`; back it up or snapshot the underlying storage pool regularly.
+
+### 4. Expose the service (optional)
+
+- Add a Proxmox firewall rule or reverse proxy entry (Traefik/Caddy/HAProxy) if you want TLS.
+- Create a DNS record (`mirror.lab.local`) pointed at the container for easier access.
+
+### 5. Upgrades & maintenance
+
+- Re-run the installer script; it detects existing installs, backs up `/opt/gitea-mirror/data`, downloads the latest release, and restarts the service.
+- Watch for warnings about upgrades from v2 → v3 wiping config—take a snapshot first if you still run v2 artifacts.
+- Check logs with `journalctl -u gitea-mirror -n 200` or `journalctl -u gitea-mirror -f` for live tailing.
+
+## Disaster-recovery drill
+
+1. In Proxmox, snapshot the container (or use ZFS/BTRFS snapshots on the storage pool).
+2. Stop GitHub access temporarily and clone from the Gitea mirror to confirm the backup works.
+3. Restore the snapshot on a different node to ensure the service boots cleanly with the preserved data volume.
+
+<figure class="mt-8 flex flex-col items-center">
+  <img
+    src="/assets/dashboard_mobile.png"
+    alt="Mobile view of the Gitea Mirror dashboard running inside a Proxmox LXC container."
+    class="w-full max-w-sm rounded-xl border border-muted shadow-sm"
+    loading="lazy"
+  />
+  <figcaption class="mt-3 text-sm text-muted-foreground text-center">
+    Even inside a lightweight LXC container, the dashboard stays responsive for quick health checks on the go.
+  </figcaption>
+</figure>
+
+## Troubleshooting
+
+- **Port 4321 already used**: change `PORT` in `/opt/gitea-mirror.env` and restart with `systemctl restart gitea-mirror`.
+- **Disk full**: extend the container disk in Proxmox, then run `pct resize <CTID> rootfs +5G`.
+- **Token expired**: log in to the UI → Configuration to update GitHub/Gitea credentials.
+
+Looking for a cluster-native deployment? Try the [Helm playbook](../deploy-with-helm-chart).
+
+## FAQ
+
+### What container size should I start with?
+
+The script defaults to 2 vCPU, 2 GiB RAM, 6 GiB disk. Bump RAM for large orgs or many concurrent mirrors; you can resize disk later with `pct resize`.
+
+### How do I upgrade the LXC deployment?
+
+Re-run the community installer. It detects existing installs, backs up `/opt/gitea-mirror/data`, downloads the latest release, and restarts the service.
+
+### How should I back up and restore?
+
+Snapshot the container or back up `/opt/gitea-mirror/data`. Restore by attaching the volume to a fresh container and starting the service; your configuration is preserved.

www/src/pages/use-cases/starred-repos-collection.mdx

@@ -0,0 +1,89 @@
+---
+layout: ../../layouts/UseCaseLayout.astro
+title: "Build a Starred Repo Collection"
+description: "Mirror your starred GitHub projects into a dedicated Gitea library so favorites remain available offline."
+canonical: "https://gitea-mirror.com/use-cases/starred-repos-collection/"
+---
+
+# Build a Starred Repo Collection
+
+## Curate without losing projects
+
+Stars are a personal library—but they vanish when creators delete repos or your account is rate limited. Gitea Mirror can automatically capture every starred repository into a dedicated Gitea organization, complete with issues and releases, so your inspiration lives on.
+
+## Requirements
+
+- Gitea Mirror up and running (Docker, LXC, or Helm)
+- GitHub PAT for the account whose stars you want mirrored
+- Destination Gitea with a personal organization ready (e.g. `stars`)
+- Optional: DNS entry for the mirror so friends can browse the collection
+
+## Step-by-step
+
+### 1. Enable starred owner tracking
+
+1. In the onboarding wizard—or later under **Configuration → Connections**—add your GitHub username as an owner.
+2. Enable **Mirror starred repositories** and set the **Starred repos organization** to a dedicated space such as `stars-jamie`.
+3. Use the starred content selector to choose whether you want full metadata (issues, releases, PRs, wiki) or the lightweight code-only mode.
+
+### 2. Categorize the collection
+
+- Create sub-organizations in Gitea (e.g. `stars-iot`, `stars-ai`) if you want separate spaces you can curate manually.
+- Starred mirrors always land in the dedicated starred org, so use repository labels or Gitea teams to slice the collection by language, topic, or priority.
+- Tag repos in Gitea with labels like `language:rust`, `topic:homelab` for quick filtering.
+
+<figure class="mt-8 flex flex-col items-center">
+  <img
+    src="/assets/organisation.png"
+    alt="Organization view in Gitea Mirror highlighting starred GitHub repositories grouped in a dedicated Gitea org."
+    class="w-full max-w-5xl rounded-xl border border-muted shadow-sm"
+    loading="lazy"
+  />
+  <figcaption class="mt-3 text-sm text-muted-foreground text-center">
+    Group starred GitHub repositories into curated Gitea organizations for easier browsing and long-term preservation.
+  </figcaption>
+</figure>
+
+### 3. Keep the collection fresh
+
+- Enable **Automatic syncing** in **Configuration → Automation** and pick an interval around `1h` so new stars appear quickly.
+- Leave the scheduler running—auto-discovery pulls in new stars on each pass without additional configuration.
+- If you want unstarred projects archived or removed, enable **Handle orphaned repositories automatically** and choose **Archive** (recommended) or **Delete** for strict mirroring.
+
+### 4. Showcase the library
+
+- Point a read-only Gitea user at the org so friends can browse without write access.
+- Host the Gitea instance behind a reverse proxy with HTTPS, then link it on your blog.
+- Export the repo list weekly and share it as a curated newsletter.
+
+## Verify the collection works
+
+1. Star a new repo on GitHub.
+2. Wait for the star interval or run **Sync Repository** from the dashboard for an immediate refresh.
+3. Confirm the repo appears in your `stars` org with issues/releases intact.
+4. Unstar it on GitHub; if cleanup is set to **Archive**, verify the mirror is renamed with an `archived-` prefix and marked read-only. If you chose **Delete**, confirm it disappears on the next sync.
+
+## Nice-to-haves
+
+- Add a `README.md` in the Gitea org homepage explaining your tagging rules.
+- Pair with [Preserve GitHub History](../preserve-github-history/) so you keep metadata, not just code.
+- Use the [Helm deployment](../deploy-with-helm-chart/) if you want the collection available inside your cluster.
+
+## Related playbooks
+
+- [Backup GitHub Repositories](../backup-github-repositories/)
+- [Automate GitHub Backups](../github-backup-automation/)
+
+## FAQ
+
+### Can I mirror only the code or include metadata?
+
+Yes. Use the starred content selector to choose code-only or include issues, releases, pull requests, and wikis.
+
+### What happens when I unstar a repository?
+
+Enable Handle orphaned repositories automatically and choose Archive (recommended) to preserve history read-only, or Delete for a strict mirror.
+
+### Can others browse my collection safely?
+
+Create a read-only Gitea user or org members with no write permissions, then share the organization URL behind HTTPS.

www/src/pages/use-cases/sync-github-to-self-hosted-gitea.mdx

@@ -0,0 +1,97 @@
+---
+layout: ../../layouts/UseCaseLayout.astro
+title: "Sync GitHub to Your Self-Hosted Gitea"
+description: "Keep a homelab Gitea instance continuously updated with GitHub by using Gitea Mirror's discovery, scheduling, and metadata sync."
+canonical: "https://gitea-mirror.com/use-cases/sync-github-to-self-hosted-gitea/"
+---
+
+# Sync GitHub to Your Self-Hosted Gitea
+
+## Keep SaaS and self-hosted in lockstep
+
+You may still collaborate on GitHub every day, yet want a LAN Gitea copy you control. Gitea Mirror bridges the two: it tracks owners, auto-discovers repos, mirrors metadata, and keeps a local instance only minutes behind upstream without hand-written cron jobs.
+
+## Requirements
+
+- Gitea Mirror deployed (Docker, Proxmox LXC, or Helm)
+- GitHub PAT with `repo` enabled (add the `read:org` checkbox under `admin:org` to mirror organizations; leave write/admin unchecked)
+- Gitea API token for the target account/org
+- Stable connectivity between the mirror host and both GitHub + Gitea
+
+## Step-by-step
+
+### 1. Connect accounts in the admin wizard
+
+1. Sign in at `http://<mirror-host>:4321`.
+2. Open **Configuration → Connections**.
+3. Paste the GitHub PAT and choose the owners (user + orgs) you want mirrored.
+4. Add your self-hosted Gitea URL and token; pick the destination org structure (typically **Preserve structure**).
+
+### 2. Import the repository inventory
+
+- In **Configuration → Connections**, click **Import GitHub Data** to pull in every repository, organization, and star you've selected.
+- Enable **Mirror starred repositories** if you want personal favorites mirrored alongside org projects, and set a dedicated starred organization in Gitea.
+- Auto-discovery runs whenever the scheduler is enabled, so new GitHub repositories will appear automatically after you turn on automatic syncing.
+
+### 3. Configure sync cadence
+
+- Head to **Configuration → Automation** and enable **Automatic syncing**.
+- Pick an interval that matches your recovery point objective; `15–30 minutes` keeps an active GitHub org nearly live, while `2–4 hours` is fine for quieter repos.
+- Leave the scheduler running so auto-discovery and repository cleanup keep working in the background.
+
+<figure class="mt-8 flex flex-col items-center">
+  <img
+    src="/assets/dashboard.png"
+    alt="Gitea Mirror dashboard showing overall sync status for GitHub organizations and repositories."
+    class="w-full max-w-5xl rounded-xl border border-muted shadow-sm"
+    loading="lazy"
+  />
+  <figcaption class="mt-3 text-sm text-muted-foreground text-center">
+    Monitor GitHub-to-Gitea sync health from the dashboard while the scheduler keeps repositories aligned automatically.
+  </figcaption>
+</figure>
+
+### 4. Mirror metadata and LFS
+
+In **Configuration → Connections → Content & Data**:
+
+- Enable **Mirror metadata** so issues, pull requests (as enriched issues), labels, milestones, and wikis stay in sync.
+- Enable **Mirror LFS** if your repos store binaries; confirm your Gitea instance has LFS enabled.
+- If you want deleted GitHub repos archived or removed locally, enable **Handle orphaned repositories automatically** in the Automation tab and choose the action (Archive or Delete) that matches your retention policy.
+
+### 5. Validate the local mirror
+
+- Select a repository in the dashboard and use the **Sync Repository** action.
+- In Gitea, verify commit history, tags, issues, and releases match GitHub.
+- Run a quick diff: `git remote add gitea http://<gitea>/<owner>/<repo>.git && git fetch gitea` then `git log origin/main..gitea/main` — it should be empty.
+
+## Monitoring & health checks
+
+- Watch the **Activity Log** for failed runs and retry jobs; filter by repository when you need to chase a single mirror.
+- Point Healthchecks.io, Uptime Kuma, or Prometheus at `http://<mirror-host>:4321/api/health` to confirm the service stays responsive.
+- Export `/api/repos/:id/logs` or the global `/api/events` endpoint periodically to archive sync history alongside the repositories themselves.
+
+## Tips for smooth syncing
+
+- Avoid running more than one mirror against the same Gitea target; let Gitea Mirror manage the schedule centrally.
+- When restructuring orgs, temporarily disable automatic syncing, move repos in Gitea, then re-enable the scheduler to avoid churn.
+- Rate limits cropping up? Move the mirror onto a different IP or configure GitHub fine-grained PATs per org.
+
+## Related playbooks
+
+- [Backup GitHub Repositories](../backup-github-repositories/) for the base Docker deployment
+- [Run Gitea Mirror inside a Proxmox LXC](../proxmox-lxc-homelab/) if you want the mirror on a dedicated appliance
+
+## FAQ
+
+### How quickly can the mirror catch up to GitHub?
+
+Intervals of 15–30 minutes keep most orgs near real-time. You can shorten for critical repos, but watch GitHub API rate limits.
+
+### Can I mirror multiple GitHub users and organizations?
+
+Yes. Add each owner in Configuration → Connections, then choose a destination strategy (Preserve structure or a specific org) for Gitea.
+
+### Is it safe to store tokens in Gitea Mirror?
+
+Tokens saved via the Configuration UI are encrypted at rest. Rotate them regularly and monitor dashboard alerts for expirations.

www/src/pages/use-cases/vendor-lock-in-prevention.mdx

@@ -0,0 +1,77 @@
+---
+layout: ../../layouts/UseCaseLayout.astro
+title: "Stay Ready to Leave GitHub"
+description: "Use Gitea Mirror to keep an always-current fallback so policy or pricing changes at GitHub never stall your projects."
+canonical: "https://gitea-mirror.com/use-cases/vendor-lock-in-prevention/"
+---
+
+# Stay Ready to Leave GitHub
+
+## Keep your exit hatch open
+
+GitHub can change pricing, authentication rules, or terms without notice. With Gitea Mirror running, you always have a live copy of code and metadata inside infrastructure you control—so switching to self-hosted Gitea, Forgejo, or something else becomes a DNS change, not a fire drill.
+
+## Requirements
+
+- Production-ready Gitea instance (backed by your usual storage and TLS)
+- Gitea Mirror configured with owner discovery and metadata sync
+- Documentation of your current GitHub org structure (for validation)
+- Optional: reverse proxy + SSO for a smooth cutover experience
+
+## Step-by-step
+
+### 1. Mirror everything continuously
+
+- In **Configuration → Connections**, add every GitHub organization you care about as an owner. Auto-discovery pulls new repositories on the next scheduler run.
+- Set the organization strategy to **Preserve structure** so Gitea mirrors the GitHub org layout.
+- Open **Content & Data** to enable metadata, releases, and Git LFS, ensuring issues, pull requests, and binaries survive the switchover.
+
+### 2. Simulate a cutover
+
+1. Pick a pilot team.
+2. Ask them to work exclusively out of the Gitea mirror for a sprint.
+3. Capture feedback about permissions, webhooks, CI integrations, and adjust.
+
+### 3. Keep integrations dual-homed
+
+- Point your CI (e.g. Woodpecker, Jenkins) at both GitHub and Gitea using mirrored tokens.
+- Maintain matching webhook payloads so automation keeps running post-swap.
+- Mirror secrets (deploy keys, bot accounts) into the Gitea org to remove blockers.
+
+### 4. Document the flip procedure
+
+- Write a runbook: DNS updates, webhook changes, `git remote set-url` commands.
+- Version-control the document inside the mirror so updates stay in sync.
+- Rehearse twice a year; include steps to roll back to GitHub if needed.
+
+### 5. Watch for drift
+
+- Review the repositories dashboard weekly for new projects, teams, or permission mismatches.
+- Check the **Automation** tab—if the scheduler is enabled, auto-discovery keeps owners current.
+- Use the Activity Log and `/api/events` export to alert on failures before your recovery point objective is breached.
+
+## Success criteria
+
+- A developer can change their `origin` remote to Gitea and push without errors.
+- CI pipelines succeed when pointed exclusively at the mirror.
+- All active repos have synced within your SLA (for example, last run < 2 hours ago).
+- The runbook includes contact info, rollback steps, and verification checklists.
+
+## Related playbooks
+
+- [Sync GitHub to Your Self-Hosted Gitea](../sync-github-to-self-hosted-gitea/)
+- [Deploy Gitea Mirror with the Helm Chart](../deploy-with-helm-chart/)
+
+## FAQ
+
+### How do I confirm the mirror is still catching new repositories?
+
+Check the **Configuration → Connections** screen for the `Last imported` timestamp and ensure the scheduler in **Automation** is enabled. Auto-discovery runs with each scheduled sync.
+
+### What interval should I run before a potential cutover?
+
+Keep `Automatic syncing` at 15–30 minutes for active organizations. That keeps the lag well under an hour if you have to pivot suddenly.
+
+### Can I script the cutover?
+
+Yes. Use the `/api/export` configuration JSON and the repositories CSV export to generate runbooks, then pair them with infrastructure-as-code (DNS, reverse proxy, CI) so flipping endpoints becomes repeatable.