chore: sync version to 3.12.5

Bun 1.3.9 crashes with a segfault on CPUs without AVX support due to a
WASM IPInt bug (oven-sh/bun#27340), fixed in 1.3.10 via oven-sh/bun#26922.

- Bump Bun from 1.3.9 to 1.3.10 in Dockerfile, CI workflows, and packageManager
- Skip env config script when no GitHub/Gitea env vars are set
- Make startup scripts (env-config, recovery, repair) fault-tolerant so
  a crash in a non-critical script doesn't abort the entrypoint via set -e

.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": []
-  }
-}

.dockerignore

@@ -15,6 +15,7 @@ dist
 build
 .next
 out
+www
 
 # Environment variables
 .env

.env.example

@@ -47,6 +47,7 @@ DOCKER_TAG=latest
 # SKIP_FORKS=false
 # MIRROR_STARRED=false
 # STARRED_REPOS_ORG=starred  # Organization name for starred repos
+# STARRED_REPOS_MODE=dedicated-org  # dedicated-org | preserve-owner
 
 # Organization Settings
 # MIRROR_ORGANIZATIONS=false
@@ -66,6 +67,7 @@ DOCKER_TAG=latest
 
 # Basic Gitea Settings
 # GITEA_URL=http://gitea:3000
+# GITEA_EXTERNAL_URL=https://gitea.example.com  # Optional: used only for UI links
 # GITEA_TOKEN=your-local-gitea-token
 # GITEA_USERNAME=your-local-gitea-username
 # GITEA_ORGANIZATION=github-mirrors  # Default organization for single-org strategy
@@ -183,4 +185,4 @@ DOCKER_TAG=latest
 # ===========================================
 
 # TLS/SSL Configuration
-# GITEA_SKIP_TLS_VERIFY=false  # WARNING: Only use for testing
+# GITEA_SKIP_TLS_VERIFY=false  # WARNING: Only use for testing

.envrc

@@ -0,0 +1 @@
+use flake

.github/workflows/README.md

@@ -30,17 +30,22 @@ This workflow runs on all branches and pull requests. It:
 
 ### Docker Build and Push (`docker-build.yml`)
 
-This workflow builds and pushes Docker images to GitHub Container Registry (ghcr.io), but only when changes are merged to the main branch.
+This workflow builds Docker images on pushes and pull requests, and pushes to GitHub Container Registry (ghcr.io) when permissions allow (main/tags and same-repo PRs).
 
 **When it runs:**
 - On push to the main branch
 - On tag creation (v*)
+- On pull requests (build + scan; push only for same-repo PRs)
 
 **Key features:**
 - Builds multi-architecture images (amd64 and arm64)
-- Pushes images only on main branch, not for PRs
+- Pushes images for main/tags and same-repo PRs
+- Skips registry push for fork PRs (avoids package write permission failures)
 - Uses build caching to speed up builds
 - Creates multiple tags for each image (latest, semver, sha)
+- Auto-syncs `package.json` version from `v*` tags during release builds
+- Validates release tags use semver format before building
+- After tag builds succeed, writes the same version back to `main/package.json`
 
 ### Docker Security Scan (`docker-scan.yml`)
 

.github/workflows/astro-build-test.yml

@@ -6,11 +6,15 @@ on:
     paths-ignore:
       - 'README.md'
       - 'docs/**'
+      - 'www/**'
+      - 'helm/**'
   pull_request:
     branches: [ '*' ]
     paths-ignore:
       - 'README.md'
       - 'docs/**'
+      - 'www/**'
+      - 'helm/**'
 
 permissions:
   contents: read
@@ -20,6 +24,7 @@ jobs:
   build-and-test:
     name: Build and Test Astro Project
     runs-on: ubuntu-latest
+    timeout-minutes: 25
 
     steps:
       - name: Checkout repository
@@ -28,7 +33,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v1
         with:
-          bun-version: '1.2.16'
+          bun-version: '1.3.10'
 
       - name: Check lockfile and install dependencies
         run: |

.github/workflows/docker-build.yml

@@ -36,6 +36,7 @@ env:
 jobs:
   docker:
     runs-on: ubuntu-latest
+    timeout-minutes: 25
 
     permissions:
       contents: write
@@ -55,6 +56,7 @@ jobs:
           driver-opts: network=host
 
       - name: Log into registry
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
@@ -75,13 +77,34 @@ jobs:
         id: tag_version
         run: |
           if [[ $GITHUB_REF == refs/tags/v* ]]; then
-            echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
-            echo "Using version tag: ${GITHUB_REF#refs/tags/}"
+            TAG_VERSION="${GITHUB_REF#refs/tags/}"
+            if [[ ! "$TAG_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]; then
+              echo "::error::Release tag '${TAG_VERSION}' is invalid. Expected semver tag format like v1.2.3 or v1.2.3-rc.1"
+              exit 1
+            fi
+            APP_VERSION="${TAG_VERSION#v}"
+            echo "VERSION=${TAG_VERSION}" >> $GITHUB_OUTPUT
+            echo "APP_VERSION=${APP_VERSION}" >> $GITHUB_OUTPUT
+            echo "Using version tag: ${TAG_VERSION}"
           else
             echo "VERSION=latest" >> $GITHUB_OUTPUT
+            echo "APP_VERSION=dev" >> $GITHUB_OUTPUT
             echo "No version tag, using 'latest'"
           fi
 
+      # Keep version files aligned automatically for tag-based releases
+      - name: Sync app version from release tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="${{ steps.tag_version.outputs.APP_VERSION }}"
+          echo "Syncing package.json version to ${VERSION}"
+
+          jq --arg version "${VERSION}" '.version = $version' package.json > package.json.tmp
+          mv package.json.tmp package.json
+
+          echo "Version sync diff (package.json):"
+          git --no-pager diff -- package.json
+
       # Extract metadata for Docker
       - name: Extract Docker metadata
         id: meta
@@ -101,36 +124,41 @@ jobs:
       # Build and push Docker image
       - name: Build and push Docker image
         id: build-and-push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           context: .
-          platforms: ${{ github.event_name == 'pull_request' && 'linux/amd64' || 'linux/amd64,linux/arm64' }}
-          push: true
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
+          provenance: false # Disable provenance to avoid unknown/unknown
+          sbom: false       # Disable sbom to avoid unknown/unknown
 
       # Load image locally for security scanning (PRs only)
       - name: Load image for scanning
         if: github.event_name == 'pull_request'
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           context: .
           platforms: linux/amd64
           load: true
           tags: gitea-mirror:scan
           cache-from: type=gha
+          provenance: false # Disable provenance to avoid unknown/unknown
+          sbom: false       # Disable sbom to avoid unknown/unknown
 
       # Wait for image to be available in registry
       - name: Wait for image availability
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
         run: |
           echo "Waiting for image to be available in registry..."
           sleep 5
 
       # Add comment to PR with image details
       - name: Comment PR with image tag
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -149,7 +177,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,13 +190,15 @@ 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.
-            > Production images (\`latest\`, version tags) are multi-platform (\`linux/amd64\`, \`linux/arm64\`).
+            > 💡 **Note:** PR images are tagged as \`pr-<number>\` and built for both \`linux/amd64\` and \`linux/arm64\`.
+            > Production images (\`latest\`, version tags) use the same multi-platform set.
 
             ---
             📦 View in [GitHub Packages](https://github.com/${{ github.repository }}/pkgs/container/gitea-mirror)`;
@@ -219,9 +253,49 @@ jobs:
 
       # Upload security scan results to GitHub Security tab
       - name: Upload Docker Scout scan results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@v3
+        uses: github/codeql-action/upload-sarif@v4
         if: always()
         continue-on-error: true
         with:
           sarif_file: scout-results.sarif
 
+  sync-version-main:
+    name: Sync package.json version back to main
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    needs: docker
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout default branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+
+      - name: Update package.json version on main
+        env:
+          TAG_VERSION: ${{ github.ref_name }}
+          TARGET_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          if [[ ! "$TAG_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]; then
+            echo "::error::Release tag '${TAG_VERSION}' is invalid. Expected semver tag format like v1.2.3 or v1.2.3-rc.1"
+            exit 1
+          fi
+
+          APP_VERSION="${TAG_VERSION#v}"
+          echo "Syncing ${TARGET_BRANCH}/package.json to ${APP_VERSION}"
+
+          jq --arg version "${APP_VERSION}" '.version = $version' package.json > package.json.tmp
+          mv package.json.tmp package.json
+
+          if git diff --quiet -- package.json; then
+            echo "package.json on ${TARGET_BRANCH} already at ${APP_VERSION}; nothing to commit."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add package.json
+          git commit -m "chore: sync version to ${APP_VERSION}"
+          git push origin "HEAD:${TARGET_BRANCH}"

.github/workflows/e2e-tests.yml

@@ -0,0 +1,285 @@
+name: E2E Integration Tests
+
+on:
+  push:
+    branches: ["*"]
+    paths-ignore:
+      - "README.md"
+      - "docs/**"
+      - "CHANGELOG.md"
+      - "LICENSE"
+      - "www/**"
+      - "helm/**"
+  pull_request:
+    branches: ["*"]
+    paths-ignore:
+      - "README.md"
+      - "docs/**"
+      - "CHANGELOG.md"
+      - "LICENSE"
+      - "www/**"
+      - "helm/**"
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        description: "Enable debug logging"
+        required: false
+        default: "false"
+        type: boolean
+
+permissions:
+  contents: read
+  actions: read
+
+concurrency:
+  group: e2e-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  GITEA_PORT: 3333
+  FAKE_GITHUB_PORT: 4580
+  GIT_SERVER_PORT: 4590
+  APP_PORT: 4321
+  BUN_VERSION: "1.3.10"
+
+jobs:
+  e2e-tests:
+    name: E2E Integration Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        run: |
+          bun install
+          echo "✓ Dependencies installed"
+
+      - name: Install Playwright
+        run: |
+          npx playwright install chromium
+          npx playwright install-deps chromium
+          echo "✓ Playwright ready"
+
+      - name: Create test git repositories
+        run: |
+          echo "Creating bare git repos for E2E testing..."
+          bun run tests/e2e/create-test-repos.ts --output-dir tests/e2e/git-repos
+
+          if [ ! -f tests/e2e/git-repos/manifest.json ]; then
+            echo "ERROR: Test git repos were not created (manifest.json missing)"
+            exit 1
+          fi
+
+          echo "✓ Test repos created:"
+          cat tests/e2e/git-repos/manifest.json | jq -r '.repos[] | "  • \(.owner)/\(.name) — \(.description)"'
+
+      - name: Start Gitea and git-server containers
+        run: |
+          echo "Starting containers via docker compose..."
+          docker compose -f tests/e2e/docker-compose.e2e.yml up -d
+
+          # Wait for git-server
+          echo "Waiting for git HTTP server..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:${{ env.GIT_SERVER_PORT }}/manifest.json > /dev/null 2>&1; then
+              echo "✓ Git HTTP server is ready"
+              break
+            fi
+            if [ $i -eq 30 ]; then
+              echo "ERROR: Git HTTP server did not start"
+              docker compose -f tests/e2e/docker-compose.e2e.yml logs git-server
+              exit 1
+            fi
+            sleep 1
+          done
+
+          # Wait for Gitea
+          echo "Waiting for Gitea to be ready..."
+          for i in $(seq 1 60); do
+            if curl -sf http://localhost:${{ env.GITEA_PORT }}/api/v1/version > /dev/null 2>&1; then
+              version=$(curl -sf http://localhost:${{ env.GITEA_PORT }}/api/v1/version | jq -r '.version // "unknown"')
+              echo "✓ Gitea is ready (version: $version)"
+              break
+            fi
+            if [ $i -eq 60 ]; then
+              echo "ERROR: Gitea did not become healthy within 120s"
+              docker compose -f tests/e2e/docker-compose.e2e.yml logs gitea-e2e --tail=30
+              exit 1
+            fi
+            sleep 2
+          done
+
+      - name: Initialize database
+        run: |
+          bun run manage-db init
+          echo "✓ Database initialized"
+
+      - name: Build application
+        env:
+          GH_API_URL: http://localhost:4580
+          BETTER_AUTH_SECRET: e2e-test-secret
+        run: |
+          bun run build
+          echo "✓ Build complete"
+
+      - name: Start fake GitHub API server
+        run: |
+          # Start with GIT_SERVER_URL pointing to the git-server container name
+          # (Gitea will resolve it via Docker networking)
+          PORT=${{ env.FAKE_GITHUB_PORT }} GIT_SERVER_URL="http://git-server" \
+            npx tsx tests/e2e/fake-github-server.ts &
+          echo $! > /tmp/fake-github.pid
+
+          echo "Waiting for fake GitHub API..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:${{ env.FAKE_GITHUB_PORT }}/___mgmt/health > /dev/null 2>&1; then
+              echo "✓ Fake GitHub API is ready"
+              break
+            fi
+            if [ $i -eq 30 ]; then
+              echo "ERROR: Fake GitHub API did not start"
+              exit 1
+            fi
+            sleep 1
+          done
+
+          # Ensure clone URLs are set for the git-server container
+          curl -sf -X POST http://localhost:${{ env.FAKE_GITHUB_PORT }}/___mgmt/set-clone-url \
+            -H "Content-Type: application/json" \
+            -d '{"url": "http://git-server"}' || true
+          echo "✓ Clone URLs configured for git-server container"
+
+      - name: Start gitea-mirror application
+        env:
+          GH_API_URL: http://localhost:4580
+          BETTER_AUTH_SECRET: e2e-test-secret
+          BETTER_AUTH_URL: http://localhost:4321
+          DATABASE_URL: file:data/gitea-mirror.db
+          HOST: 0.0.0.0
+          PORT: ${{ env.APP_PORT }}
+          NODE_ENV: production
+          PRE_SYNC_BACKUP_ENABLED: "false"
+          ENCRYPTION_SECRET: "e2e-encryption-secret-32char!!"
+        run: |
+          # Re-init DB in case build step cleared it
+          bun run manage-db init 2>/dev/null || true
+
+          bun run start &
+          echo $! > /tmp/app.pid
+
+          echo "Waiting for gitea-mirror app..."
+          for i in $(seq 1 90); do
+            if curl -sf http://localhost:${{ env.APP_PORT }}/api/health > /dev/null 2>&1 || \
+               curl -sf -o /dev/null -w "%{http_code}" http://localhost:${{ env.APP_PORT }}/ 2>/dev/null | grep -q "^[23]"; then
+              echo "✓ gitea-mirror app is ready"
+              break
+            fi
+            if ! kill -0 $(cat /tmp/app.pid) 2>/dev/null; then
+              echo "ERROR: App process died"
+              exit 1
+            fi
+            if [ $i -eq 90 ]; then
+              echo "ERROR: gitea-mirror app did not start within 180s"
+              exit 1
+            fi
+            sleep 2
+          done
+
+      - name: Run E2E tests
+        env:
+          APP_URL: http://localhost:${{ env.APP_PORT }}
+          GITEA_URL: http://localhost:${{ env.GITEA_PORT }}
+          FAKE_GITHUB_URL: http://localhost:${{ env.FAKE_GITHUB_PORT }}
+          GIT_SERVER_URL: http://localhost:${{ env.GIT_SERVER_PORT }}
+          CI: true
+        run: |
+          mkdir -p tests/e2e/test-results
+          npx playwright test \
+            --config tests/e2e/playwright.config.ts \
+            --reporter=github,html
+
+      - name: Diagnostic info on failure
+        if: failure()
+        run: |
+          echo "═══════════════════════════════════════════════════════════"
+          echo " Diagnostic Information"
+          echo "═══════════════════════════════════════════════════════════"
+
+          echo ""
+          echo "── Git server status ──"
+          curl -sf http://localhost:${{ env.GIT_SERVER_PORT }}/manifest.json 2>/dev/null | jq . || echo "(unreachable)"
+
+          echo ""
+          echo "── Gitea status ──"
+          curl -sf http://localhost:${{ env.GITEA_PORT }}/api/v1/version 2>/dev/null || echo "(unreachable)"
+
+          echo ""
+          echo "── Fake GitHub status ──"
+          curl -sf http://localhost:${{ env.FAKE_GITHUB_PORT }}/___mgmt/health 2>/dev/null | jq . || echo "(unreachable)"
+
+          echo ""
+          echo "── App status ──"
+          curl -sf http://localhost:${{ env.APP_PORT }}/api/health 2>/dev/null || echo "(unreachable)"
+
+          echo ""
+          echo "── Docker containers ──"
+          docker compose -f tests/e2e/docker-compose.e2e.yml ps 2>/dev/null || true
+
+          echo ""
+          echo "── Gitea container logs (last 50 lines) ──"
+          docker compose -f tests/e2e/docker-compose.e2e.yml logs gitea-e2e --tail=50 2>/dev/null || echo "(no container)"
+
+          echo ""
+          echo "── Git server logs (last 20 lines) ──"
+          docker compose -f tests/e2e/docker-compose.e2e.yml logs git-server --tail=20 2>/dev/null || echo "(no container)"
+
+          echo ""
+          echo "── Running processes ──"
+          ps aux | grep -E "(fake-github|astro|bun|node)" | grep -v grep || true
+
+      - name: Upload Playwright report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: e2e-playwright-report
+          path: tests/e2e/playwright-report/
+          retention-days: 14
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: e2e-test-results
+          path: tests/e2e/test-results/
+          retention-days: 14
+
+      - name: Cleanup
+        if: always()
+        run: |
+          # Stop background processes
+          if [ -f /tmp/fake-github.pid ]; then
+            kill $(cat /tmp/fake-github.pid) 2>/dev/null || true
+            rm -f /tmp/fake-github.pid
+          fi
+          if [ -f /tmp/app.pid ]; then
+            kill $(cat /tmp/app.pid) 2>/dev/null || true
+            rm -f /tmp/app.pid
+          fi
+
+          # Stop containers
+          docker compose -f tests/e2e/docker-compose.e2e.yml down --volumes --remove-orphans 2>/dev/null || true
+
+          echo "✓ Cleanup complete"

.github/workflows/helm-test.yml

@@ -21,6 +21,7 @@ jobs:
   yamllint:
     name: Lint YAML
     runs-on: ubuntu-latest
+    timeout-minutes: 25
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -35,6 +36,7 @@ jobs:
   helm-template:
     name: Helm lint & template
     runs-on: ubuntu-latest
+    timeout-minutes: 25
     steps:
       - uses: actions/checkout@v4
       - name: Setup Helm

.github/workflows/nix-build.yml

@@ -0,0 +1,50 @@
+name: Nix Flake Check
+
+on:
+  push:
+    branches: [main, nix]
+    tags:
+      - 'v*'
+    paths:
+      - 'flake.nix'
+      - 'flake.lock'
+      - 'bun.nix'
+      - '.github/workflows/nix-build.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'flake.nix'
+      - 'flake.lock'
+      - 'bun.nix'
+      - '.github/workflows/nix-build.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      NIX_CONFIG: |
+        accept-flake-config = true
+        access-tokens = github.com=${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@main
+
+      - name: Setup Nix Cache
+        uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - name: Check flake
+        run: nix flake check --accept-flake-config
+
+      - name: Show flake info
+        run: nix flake show --accept-flake-config
+
+      - name: Build package
+        if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
+        run: nix build --print-build-logs --accept-flake-config

.gitignore

@@ -32,3 +32,23 @@ certs/*.pem
 certs/*.cer
 !certs/README.md
 
+# Nix build artifacts
+result
+result-*
+.direnv/
+
+# E2E test artifacts
+tests/e2e/test-results/
+tests/e2e/playwright-report/
+tests/e2e/.auth/
+tests/e2e/e2e-storage-state.json
+tests/e2e/.fake-github.pid
+tests/e2e/.app.pid
+tests/e2e/git-repos/
+
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+/playwright/.auth/

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

Dockerfile

@@ -1,36 +1,41 @@
 # syntax=docker/dockerfile:1.4
 
-FROM oven/bun:1.2.23-alpine AS base
+FROM oven/bun:1.3.10-debian AS base
 WORKDIR /app
-RUN apk add --no-cache libc6-compat python3 make g++ gcc wget sqlite openssl ca-certificates
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  python3 make g++ gcc wget sqlite3 openssl ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
 
 # ----------------------------
-FROM base AS deps
+FROM base AS builder
 COPY package.json ./
 COPY bun.lock* ./
 RUN bun install --frozen-lockfile
 
-# ----------------------------
-FROM deps AS builder
 COPY . .
 RUN bun run build
 RUN mkdir -p dist/scripts && \
-    for script in scripts/*.ts; do \
-      bun build "$script" --target=bun --outfile=dist/scripts/$(basename "${script%.ts}.js"); \
-    done
+  for script in scripts/*.ts; do \
+  bun build "$script" --target=bun --outfile=dist/scripts/$(basename "${script%.ts}.js"); \
+  done
 
 # ----------------------------
-FROM deps AS pruner
-RUN bun install --production --frozen-lockfile
+FROM base AS pruner
+COPY package.json ./
+COPY bun.lock* ./
+RUN bun install --production --omit=peer --frozen-lockfile
 
 # ----------------------------
-FROM base AS runner
+FROM oven/bun:1.3.10-debian AS runner
 WORKDIR /app
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  git git-lfs wget sqlite3 openssl ca-certificates \
+  && git lfs install \
+  && rm -rf /var/lib/apt/lists/*
 COPY --from=pruner /app/node_modules ./node_modules
 COPY --from=builder /app/dist ./dist
 COPY --from=builder /app/package.json ./package.json
 COPY --from=builder /app/docker-entrypoint.sh ./docker-entrypoint.sh
-COPY --from=builder /app/scripts ./scripts
 COPY --from=builder /app/drizzle ./drizzle
 
 ENV NODE_ENV=production
@@ -40,12 +45,13 @@ ENV DATABASE_URL=file:data/gitea-mirror.db
 
 # Create directories and setup permissions
 RUN mkdir -p /app/certs && \
-    chmod +x ./docker-entrypoint.sh && \
-    mkdir -p /app/data && \
-    addgroup --system --gid 1001 nodejs && \
-    adduser --system --uid 1001 gitea-mirror && \
-    chown -R gitea-mirror:nodejs /app/data && \
-    chown -R gitea-mirror:nodejs /app/certs
+  chmod +x ./docker-entrypoint.sh && \
+  mkdir -p /app/data && \
+  groupadd --system --gid 1001 nodejs && \
+  useradd --system --uid 1001 --gid 1001 --create-home --home-dir /home/gitea-mirror gitea-mirror && \
+  chown -R gitea-mirror:nodejs /app/data && \
+  chown -R gitea-mirror:nodejs /app/certs && \
+  chown -R gitea-mirror:nodejs /home/gitea-mirror
 
 USER gitea-mirror
 
@@ -55,4 +61,4 @@ EXPOSE 4321
 HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
   CMD wget --no-verbose --tries=1 --spider http://localhost:4321/api/health || exit 1
 
-ENTRYPOINT ["./docker-entrypoint.sh"]
+ENTRYPOINT ["./docker-entrypoint.sh"]

NIX.md

@@ -0,0 +1,189 @@
+# Nix Deployment Quick Reference
+
+## TL;DR
+
+```bash
+# From GitHub (no clone needed!)
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Or from local clone
+nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror
+```
+
+Secrets auto-generate, database auto-initializes, and the web UI starts at http://localhost:4321.
+
+**Note:** If you have flakes enabled in your nix config, you can omit `--extra-experimental-features 'nix-command flakes'`
+
+---
+
+## Installation Options
+
+### 1. Run Without Installing (from GitHub)
+```bash
+# Latest version from main branch
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Pin to specific version
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+```
+
+### 2. Install to Profile
+```bash
+# Install from GitHub
+nix profile install --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Run the installed binary
+gitea-mirror
+```
+
+### 3. Use Local Clone
+```bash
+# Clone and run
+git clone https://github.com/RayLabsHQ/gitea-mirror.git
+cd gitea-mirror
+nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror
+```
+
+### 4. NixOS System Service
+```nix
+# configuration.nix
+{
+  inputs.gitea-mirror.url = "github:RayLabsHQ/gitea-mirror";
+
+  services.gitea-mirror = {
+    enable = true;
+    betterAuthUrl = "https://mirror.example.com";  # For production
+    openFirewall = true;
+  };
+}
+```
+
+### 5. Development (Local Clone)
+```bash
+nix develop --extra-experimental-features 'nix-command flakes'
+# or
+direnv allow  # Handles experimental features automatically
+```
+
+---
+
+## Enable Flakes Permanently (Recommended)
+
+To avoid typing `--extra-experimental-features` every time, add to `~/.config/nix/nix.conf`:
+```
+experimental-features = nix-command flakes
+```
+
+---
+
+## What Gets Auto-Generated?
+
+On first run, the wrapper automatically:
+
+1. Creates `~/.local/share/gitea-mirror/` (or `$DATA_DIR`)
+2. Generates `BETTER_AUTH_SECRET` → `.better_auth_secret`
+3. Generates `ENCRYPTION_SECRET` → `.encryption_secret`
+4. Initializes SQLite database
+5. Runs startup recovery and repair scripts
+6. Starts the application
+
+---
+
+## Key Commands
+
+```bash
+# Database management
+gitea-mirror-db init      # Initialize database
+gitea-mirror-db check     # Health check
+gitea-mirror-db fix       # Fix issues
+
+# Development (add --extra-experimental-features 'nix-command flakes' if needed)
+nix develop               # Enter dev shell
+nix build                 # Build package
+nix flake check           # Validate flake
+nix flake update          # Update dependencies
+```
+
+---
+
+## Environment Variables
+
+All vars from `docker-compose.alt.yml` are supported:
+
+```bash
+DATA_DIR="$HOME/.local/share/gitea-mirror"
+PORT=4321
+HOST="0.0.0.0"
+BETTER_AUTH_URL="http://localhost:4321"
+
+# Secrets (auto-generated if not set)
+BETTER_AUTH_SECRET=auto-generated
+ENCRYPTION_SECRET=auto-generated
+
+# Concurrency (for perfect ordering, set both to 1)
+MIRROR_ISSUE_CONCURRENCY=3
+MIRROR_PULL_REQUEST_CONCURRENCY=5
+```
+
+---
+
+## NixOS Module Options
+
+```nix
+services.gitea-mirror = {
+  enable = true;
+  package = ...;                        # Override package
+  dataDir = "/var/lib/gitea-mirror";   # Data location
+  user = "gitea-mirror";               # Service user
+  group = "gitea-mirror";              # Service group
+  host = "0.0.0.0";                    # Bind address
+  port = 4321;                         # Listen port
+  betterAuthUrl = "http://...";        # External URL
+  betterAuthTrustedOrigins = "...";    # CORS origins
+  mirrorIssueConcurrency = 3;          # Concurrency
+  mirrorPullRequestConcurrency = 5;    # Concurrency
+  environmentFile = null;              # Optional secrets file
+  openFirewall = true;                 # Open firewall
+};
+```
+
+---
+
+## Comparison: Docker vs Nix
+
+| Feature | Docker | Nix |
+|---------|--------|-----|
+| **Config Required** | BETTER_AUTH_SECRET | None (auto-generated) |
+| **Startup** | `docker-compose up` | `nix run .#gitea-mirror` |
+| **Service** | Docker daemon | systemd (NixOS) |
+| **Updates** | `docker pull` | `nix flake update` |
+| **Reproducible** | Image-based | Hash-based |
+
+---
+
+## Full Documentation
+
+- **[docs/NIX_DEPLOYMENT.md](docs/NIX_DEPLOYMENT.md)** - Complete deployment guide
+  - NixOS module configuration
+  - Home Manager integration
+  - Production deployment examples
+  - Migration from Docker
+  - Troubleshooting guide
+
+- **[docs/NIX_DISTRIBUTION.md](docs/NIX_DISTRIBUTION.md)** - Distribution guide for maintainers
+  - How users consume the package
+  - CI build caching
+  - Releasing new versions
+  - Submitting to nixpkgs
+
+---
+
+## Key Features
+
+- **Zero-config deployment** - Runs immediately without setup
+- **Auto-secret generation** - Secure secrets created and persisted
+- **Startup recovery** - Handles interrupted jobs automatically
+- **Graceful shutdown** - Proper signal handling
+- **Health checks** - Built-in monitoring support
+- **Security hardening** - NixOS module includes systemd protections
+- **Docker parity** - Same behavior as `docker-compose.alt.yml`

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
@@ -44,6 +40,7 @@ First user signup becomes admin. Configure GitHub and Gitea through the web inte
 - 🔄 **Auto-discovery** - Automatically import new GitHub repositories (v3.4.0+)
 - 🧹 **Repository cleanup** - Auto-remove repos deleted from GitHub (v3.4.0+)
 - 🎯 **Proper mirror intervals** - Respects configured sync intervals (v3.4.0+)
+- 🛡️ **[Force-push protection](docs/FORCE_PUSH_PROTECTION.md)** - Smart detection with backup-on-demand or block-and-approve modes (Beta)
 - 🗑️ Automatic database cleanup with configurable retention
 - 🐳 Dockerized with multi-arch support (AMD64/ARM64)
 
@@ -116,7 +113,7 @@ docker compose up -d
 #### Using Pre-built Image Directly
 
 ```bash
-docker pull ghcr.io/raylabshq/gitea-mirror:v3.1.1
+docker pull ghcr.io/raylabshq/gitea-mirror:latest
 ```
 
 ### Configuration Options
@@ -154,6 +151,38 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/Proxmo
 
 See the [Proxmox VE Community Scripts](https://community-scripts.github.io/ProxmoxVE/scripts?id=gitea-mirror) for more details.
 
+### Nix/NixOS
+
+Zero-configuration deployment with Nix:
+
+```bash
+# Run immediately - no setup needed!
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Or build and run locally
+nix build --extra-experimental-features 'nix-command flakes'
+./result/bin/gitea-mirror
+
+# Or install to profile
+nix profile install --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+gitea-mirror
+```
+
+**NixOS users** - add to your configuration:
+```nix
+{
+  inputs.gitea-mirror.url = "github:RayLabsHQ/gitea-mirror";
+
+  services.gitea-mirror = {
+    enable = true;
+    betterAuthUrl = "https://mirror.example.com";
+    openFirewall = true;
+  };
+}
+```
+
+Secrets auto-generate, database auto-initializes. See [NIX.md](NIX.md) for quick reference or [docs/NIX_DEPLOYMENT.md](docs/NIX_DEPLOYMENT.md) for full documentation.
+
 ### Manual Installation
 
 ```bash
@@ -181,7 +210,7 @@ bun run dev
 3. **Customization**
    - Click edit buttons on organization cards to set custom destinations
    - Override individual repository destinations in the table view
-   - Starred repositories automatically go to a dedicated organization
+   - Starred repositories can go to a dedicated org or preserve source owner/org paths
 
 ## Advanced Features
 
@@ -254,13 +283,16 @@ CLEANUP_DRY_RUN=false                 # Set to true to test without changes
 **Important Notes**:
 - **Auto-Start**: When `SCHEDULE_ENABLED=true` or `GITEA_MIRROR_INTERVAL` is set, the service automatically imports all GitHub repositories and mirrors them on startup. No manual "Import" or "Mirror" button clicks required!
 - The scheduler checks every minute for tasks to run. The `GITEA_MIRROR_INTERVAL` determines how often each repository is actually synced. For example, with `8h`, each repo syncs every 8 hours from its last successful sync.
+- **Large repo bootstrap**: For first-time mirroring of large repositories (especially with metadata/LFS), avoid very short intervals (for example `5m`). Start with a longer interval (`1h` to `8h`) or temporarily disable scheduling during the initial import/mirror run, then enable your regular interval after the first pass completes.
+- **Why this matters**: If your Gitea instance takes a long time to complete migrations/imports, aggressive schedules can cause repeated retries and duplicate-looking mirror attempts.
 
 **🛡️ Backup Protection Features**:
 - **No Accidental Deletions**: Repository cleanup is automatically skipped if GitHub is inaccessible (account deleted, banned, or API errors)
 - **Archive Never Deletes Data**: The `archive` action preserves all repository data:
   - Regular repositories: Made read-only using Gitea's archive feature
-  - Mirror repositories: Renamed with `[ARCHIVED]` prefix (Gitea API limitation prevents archiving mirrors)
+  - Mirror repositories: Renamed with `archived-` prefix (Gitea API limitation prevents archiving mirrors)
   - Failed operations: Repository remains fully accessible even if marking as archived fails
+- **Manual Sync on Demand**: Archived mirrors stay in Gitea with automatic syncs disabled; trigger `Manual Sync` from the Repositories page whenever you need fresh data.
 - **The Whole Point of Backups**: Your Gitea mirrors are preserved even when GitHub sources disappear - that's why you have backups!
 - **Strongly Recommended**: Always use `CLEANUP_ORPHANED_REPO_ACTION=archive` (default) instead of `delete`
 
@@ -270,6 +302,40 @@ CLEANUP_DRY_RUN=false                 # Set to true to test without changes
 
 If using a reverse proxy (e.g., nginx proxy manager) and experiencing issues with JavaScript files not loading properly, try enabling HTTP/2 support in your proxy configuration. While not required by the application, some proxy configurations may have better compatibility with HTTP/2 enabled. See [issue #43](https://github.com/RayLabsHQ/gitea-mirror/issues/43) for reference.
 
+### Mirror Token Rotation (GitHub Token Changed)
+
+For existing pull-mirror repositories, changing the GitHub token in Gitea Mirror does not always update stored mirror credentials in Gitea/Forgejo for already-created repositories.
+
+If sync logs show authentication failures (for example `terminal prompts disabled`), do one of the following:
+
+1. In Gitea/Forgejo, open repository **Settings → Mirror Settings** and update the mirror authorization password/token.
+2. Or delete and re-mirror the repository from Gitea Mirror so it is recreated with current credentials.
+
+### Re-sync Metadata After Changing Mirror Options
+
+If you enable metadata options (issues/PRs/labels/milestones/releases) after repositories were already mirrored:
+
+1. Go to **Repositories**, select the repositories, and click **Sync** to run a fresh sync pass.
+2. For a full metadata refresh, use **Re-run Metadata** on selected repositories. This clears metadata sync state for those repos and immediately starts Sync.
+3. If some repositories still miss metadata, reset metadata sync state in SQLite and sync again:
+
+```bash
+sqlite3 data/gitea-mirror.db "UPDATE repositories SET metadata = NULL;"
+```
+
+This clears per-repository metadata completion flags so the next sync can re-run metadata import steps.
+
+### Mirror Interval vs Gitea/Forgejo `MIN_INTERVAL`
+
+Gitea Mirror treats the interval configured in **Configuration** (or `GITEA_MIRROR_INTERVAL`) as the source of truth and applies it to mirrored repositories during sync.
+
+If your Gitea/Forgejo server has `mirror.MIN_INTERVAL` set to a higher value (for example `24h`) and Gitea Mirror is set lower (for example `8h`), sync/mirror operations can fail when updating mirror settings.
+
+To avoid this:
+
+1. Set Gitea Mirror interval to a value greater than or equal to your server `MIN_INTERVAL`.
+2. Do not rely on manual per-repository mirror interval edits in Gitea/Forgejo, because Gitea Mirror will overwrite them on sync.
+
 ## Development
 
 ```bash
@@ -306,6 +372,20 @@ bun run build
 - Never stored in plaintext
 - Secure cookie-based session management
 
+### Admin Password Recovery (CLI)
+If email delivery is not configured, an admin with server access can reset a user password from the command line:
+
+```bash
+bun run reset-password -- --email=user@example.com --new-password='new-secure-password'
+```
+
+What this does:
+- Updates the credential password hash for the matching user
+- Creates a credential account if one does not already exist
+- Invalidates all active sessions for that user (forces re-login)
+
+Use this only from trusted server/admin environments.
+
 ## Authentication
 
 Gitea Mirror supports multiple authentication methods. **Email/password authentication is the default and always enabled.**
@@ -329,6 +409,8 @@ Enable users to sign in with external identity providers like Google, Azure AD,
 https://your-domain.com/api/auth/sso/callback/{provider-id}
 ```
 
+Need help? The [SSO & OIDC guide](docs/SSO-OIDC-SETUP.md) now includes a working Authentik walkthrough plus troubleshooting tips. If you upgraded from a version earlier than v3.8.10 and see `TypeError … url.startsWith` after the callback, delete the old provider and add it again using the Discover button (see [#73](https://github.com/RayLabsHQ/gitea-mirror/issues/73) and [#122](https://github.com/RayLabsHQ/gitea-mirror/issues/122)).
+
 ### 3. Header Authentication (Reverse Proxy)
 Perfect for automatic authentication when using reverse proxies like Authentik, Authelia, or Traefik Forward Auth.
 
@@ -402,22 +484,23 @@ Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTIN
 
 ## License
 
-GNU General Public License v3.0 - see [LICENSE](LICENSE) file for details.
+GNU Affero General Public License v3.0 (AGPL-3.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>
 
 ## Support
 
 - 📖 [Documentation](https://github.com/RayLabsHQ/gitea-mirror/tree/main/docs)
-- 🔐 [Custom CA Certificates](docs/CA_CERTIFICATES.md)
+- 🔐 [Environment Variables](docs/ENVIRONMENT_VARIABLES.md)
+- 🛡️ [Force-Push Protection](docs/FORCE_PUSH_PROTECTION.md)
 - 🐛 [Report Issues](https://github.com/RayLabsHQ/gitea-mirror/issues)
 - 💬 [Discussions](https://github.com/RayLabsHQ/gitea-mirror/discussions)
 - 🔧 [Proxmox VE Script](https://community-scripts.github.io/ProxmoxVE/scripts?id=gitea-mirror)

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

astro.config.mjs

@@ -14,9 +14,9 @@ export default defineConfig({
     plugins: [tailwindcss()],
     build: {
       rollupOptions: {
-        external: ['bun']
-      }
-    }
+        external: ['bun', 'bun:*'],
+      },
+    },
   },
   integrations: [react()]
-});
+});

bunfig.toml

@@ -3,4 +3,7 @@
 timeout = 5000
 
 # Preload the setup file
-preload = ["./src/tests/setup.bun.ts"]
+preload = ["./src/tests/setup.bun.ts"]
+
+# Only run tests in src/ directory (excludes tests/e2e/ which are Playwright tests)
+root = "./src/"

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"]
@@ -54,4 +58,4 @@ services:
 #    - Auto-import settings
 #    - Cleanup preferences
 #
-# That's it! Everything else can be configured via the web interface.
+# That's it! Everything else can be configured via the web interface.

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:-}

docker-entrypoint.sh

@@ -139,16 +139,29 @@ fi
 
 # Initialize configuration from environment variables if provided
 echo "Checking for environment configuration..."
-if [ -f "dist/scripts/startup-env-config.js" ]; then
-  echo "Loading configuration from environment variables..."
-  bun dist/scripts/startup-env-config.js
-  ENV_CONFIG_EXIT_CODE=$?
-elif [ -f "scripts/startup-env-config.ts" ]; then
-  echo "Loading configuration from environment variables..."
-  bun scripts/startup-env-config.ts
-  ENV_CONFIG_EXIT_CODE=$?
+
+# Only run the env config script if relevant env vars are set
+# This avoids spawning a heavy Bun process on memory-constrained systems
+HAS_ENV_CONFIG=false
+if [ -n "$GITHUB_USERNAME" ] || [ -n "$GITHUB_TOKEN" ] || [ -n "$GITEA_URL" ] || [ -n "$GITEA_USERNAME" ] || [ -n "$GITEA_TOKEN" ]; then
+  HAS_ENV_CONFIG=true
+fi
+
+if [ "$HAS_ENV_CONFIG" = "true" ]; then
+  if [ -f "dist/scripts/startup-env-config.js" ]; then
+    echo "Loading configuration from environment variables..."
+    bun dist/scripts/startup-env-config.js || ENV_CONFIG_EXIT_CODE=$?
+    ENV_CONFIG_EXIT_CODE=${ENV_CONFIG_EXIT_CODE:-0}
+  elif [ -f "scripts/startup-env-config.ts" ]; then
+    echo "Loading configuration from environment variables..."
+    bun scripts/startup-env-config.ts || ENV_CONFIG_EXIT_CODE=$?
+    ENV_CONFIG_EXIT_CODE=${ENV_CONFIG_EXIT_CODE:-0}
+  else
+    echo "Environment configuration script not found. Skipping."
+    ENV_CONFIG_EXIT_CODE=0
+  fi
 else
-  echo "Environment configuration script not found. Skipping."
+  echo "No GitHub/Gitea environment variables found, skipping env config initialization."
   ENV_CONFIG_EXIT_CODE=0
 fi
 
@@ -161,17 +174,15 @@ fi
 
 # Run startup recovery to handle any interrupted jobs
 echo "Running startup recovery..."
+RECOVERY_EXIT_CODE=0
 if [ -f "dist/scripts/startup-recovery.js" ]; then
   echo "Running startup recovery using compiled script..."
-  bun dist/scripts/startup-recovery.js --timeout=30000
-  RECOVERY_EXIT_CODE=$?
+  bun dist/scripts/startup-recovery.js --timeout=30000 || RECOVERY_EXIT_CODE=$?
 elif [ -f "scripts/startup-recovery.ts" ]; then
   echo "Running startup recovery using TypeScript script..."
-  bun scripts/startup-recovery.ts --timeout=30000
-  RECOVERY_EXIT_CODE=$?
+  bun scripts/startup-recovery.ts --timeout=30000 || RECOVERY_EXIT_CODE=$?
 else
   echo "Warning: Startup recovery script not found. Skipping recovery."
-  RECOVERY_EXIT_CODE=0
 fi
 
 # Log recovery result
@@ -185,17 +196,15 @@ fi
 
 # Run repository status repair to fix any inconsistent mirroring states
 echo "Running repository status repair..."
+REPAIR_EXIT_CODE=0
 if [ -f "dist/scripts/repair-mirrored-repos.js" ]; then
   echo "Running repository repair using compiled script..."
-  bun dist/scripts/repair-mirrored-repos.js --startup
-  REPAIR_EXIT_CODE=$?
+  bun dist/scripts/repair-mirrored-repos.js --startup || REPAIR_EXIT_CODE=$?
 elif [ -f "scripts/repair-mirrored-repos.ts" ]; then
   echo "Running repository repair using TypeScript script..."
-  bun scripts/repair-mirrored-repos.ts --startup
-  REPAIR_EXIT_CODE=$?
+  bun scripts/repair-mirrored-repos.ts --startup || REPAIR_EXIT_CODE=$?
 else
   echo "Warning: Repository repair script not found. Skipping repair."
-  REPAIR_EXIT_CODE=0
 fi
 
 # Log repair result

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
@@ -311,26 +310,25 @@ bunx tsc --noEmit
 
 ## Release Process
 
-1. **Update version**:
-```bash
-npm version patch  # or minor/major
-```
+1. **Choose release version** (`X.Y.Z`) and update `CHANGELOG.md`
 
-2. **Update CHANGELOG.md**
-
-3. **Build and test**:
+2. **Build and test**:
 ```bash
 bun run build
 bun test
 ```
 
-4. **Create release**:
+3. **Create release tag** (semver format required):
 ```bash
-git tag v2.23.0
-git push origin v2.23.0
+git tag vX.Y.Z
+git push origin vX.Y.Z
 ```
 
-5. **Create GitHub release**
+4. **Create GitHub release**
+
+5. **CI version sync (automatic)**:
+- On `v*` tags, release CI updates `package.json` version in the build context from the tag (`vX.Y.Z` -> `X.Y.Z`), so Docker release images always report the correct app version.
+- After the release build succeeds, CI commits the same `package.json` version back to `main` automatically.
 
 ## Contributing
 
@@ -350,6 +348,6 @@ git push origin v2.23.0
 
 ## Getting Help
 
-- Check existing [issues](https://github.com/yourusername/gitea-mirror/issues)
-- Join [discussions](https://github.com/yourusername/gitea-mirror/discussions)
-- Read the [FAQ](./FAQ.md)
+- Check existing [issues](https://github.com/RayLabsHQ/gitea-mirror/issues)
+- Join [discussions](https://github.com/RayLabsHQ/gitea-mirror/discussions)
+- Review project docs in [docs/README.md](./README.md)

docs/ENVIRONMENT_VARIABLES.md

@@ -62,6 +62,7 @@ Settings for connecting to and configuring GitHub repository sources.
 | `SKIP_FORKS` | Skip forked repositories | `false` | `true`, `false` |
 | `MIRROR_STARRED` | Mirror starred repositories | `false` | `true`, `false` |
 | `STARRED_REPOS_ORG` | Organization name for starred repos | `starred` | Any string |
+| `STARRED_REPOS_MODE` | How starred repos are mirrored | `dedicated-org` | `dedicated-org`, `preserve-owner` |
 
 ### Organization Settings
 
@@ -77,6 +78,7 @@ Settings for connecting to and configuring GitHub repository sources.
 | Variable | Description | Default | Options |
 |----------|-------------|---------|---------|
 | `SKIP_STARRED_ISSUES` | Enable lightweight mode for starred repos (skip issues) | `false` | `true`, `false` |
+| `AUTO_MIRROR_STARRED` | Automatically mirror starred repos during scheduled syncs and "Mirror All". When `false`, starred repos are imported for browsing but must be mirrored individually. | `false` | `true`, `false` |
 
 ## Gitea Configuration
 
@@ -87,6 +89,7 @@ Settings for the destination Gitea instance.
 | Variable | Description | Default | Options |
 |----------|-------------|---------|---------|
 | `GITEA_URL` | Gitea instance URL | - | Valid URL |
+| `GITEA_EXTERNAL_URL` | Optional external/browser URL used for dashboard links. API and mirroring still use `GITEA_URL`. | - | Valid URL |
 | `GITEA_TOKEN` | Gitea access token | - | - |
 | `GITEA_USERNAME` | Gitea username | - | - |
 | `GITEA_ORGANIZATION` | Default organization for single-org strategy | `github-mirrors` | Any string |
@@ -141,6 +144,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
 
@@ -229,7 +236,7 @@ Configure automatic cleanup of old events and data.
 | `CLEANUP_DELETE_FROM_GITEA` | Delete repositories from Gitea | `false` | `true`, `false` |
 | `CLEANUP_DELETE_IF_NOT_IN_GITHUB` | Delete repos not found in GitHub (automatically enables cleanup) | `true` | `true`, `false` |
 | `CLEANUP_ORPHANED_REPO_ACTION` | Action for orphaned repositories. **Note**: `archive` is recommended to preserve backups | `archive` | `skip`, `archive`, `delete` |
-| `CLEANUP_DRY_RUN` | Test mode without actual deletion | `true` | `true`, `false` |
+| `CLEANUP_DRY_RUN` | Test mode without actual deletion | `false` | `true`, `false` |
 | `CLEANUP_PROTECTED_REPOS` | Comma-separated list of protected repository names | - | Comma-separated strings |
 
 **🛡️ Safety Features (Backup Protection)**:
@@ -242,10 +249,11 @@ Configure automatic cleanup of old events and data.
 - **Regular repositories**: Uses Gitea's native archive feature (PATCH `/repos/{owner}/{repo}` with `archived: true`)
   - Makes repository read-only while preserving all data
 - **Mirror repositories**: Uses rename strategy (Gitea API returns 422 for archiving mirrors)
-  - Renamed with `[ARCHIVED]` prefix for clear identification
+  - Renamed with `archived-` prefix for clear identification
   - Description updated with preservation notice and timestamp
   - Mirror interval set to 8760h (1 year) to minimize sync attempts
   - Repository remains fully accessible and cloneable
+- **Manual Sync Option**: Archived mirrors are still available on the Repositories page with automatic syncs disabled—use the `Manual Sync` action to refresh them on demand.
 
 ### Execution Settings
 

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/FORCE_PUSH_PROTECTION.md

@@ -0,0 +1,179 @@
+# Force-Push Protection
+
+This document describes the smart force-push protection system introduced in gitea-mirror v3.11.0+.
+
+## The Problem
+
+GitHub repositories can be force-pushed at any time — rewriting history, deleting branches, or replacing commits entirely. When gitea-mirror syncs a force-pushed repo, the old history in Gitea is silently overwritten. Files, commits, and branches disappear with no way to recover them.
+
+The original workaround (`backupBeforeSync: true`) created a full git bundle backup before **every** sync. This doesn't scale — a user with 100+ GiB of mirrors would need up to 2 TB of backup storage with default retention settings, even though force-pushes are rare.
+
+## Solution: Smart Detection
+
+Instead of backing up everything every time, the system detects force-pushes **before** they happen and only acts when needed.
+
+### How Detection Works
+
+Before each sync, the app compares branch SHAs between Gitea (the mirror) and GitHub (the source):
+
+1. **Fetch branches from both sides** — lightweight API calls to get branch names and their latest commit SHAs
+2. **Compare each branch**:
+   - SHAs match → nothing changed, no action needed
+   - SHAs differ → check if the change is a normal push or a force-push
+3. **Ancestry check** — for branches with different SHAs, call GitHub's compare API to determine if the new SHA is a descendant of the old one:
+   - **Fast-forward** (new SHA descends from old) → normal push, safe to sync
+   - **Diverged** (histories split) → force-push detected
+   - **404** (old SHA doesn't exist on GitHub anymore) → history was rewritten, force-push detected
+   - **Branch deleted on GitHub** → flagged as destructive change
+
+### What Happens on Detection
+
+Depends on the configured strategy (see below):
+- **Backup strategies** (`always`, `on-force-push`): create a git bundle snapshot, then sync
+- **Block strategy** (`block-on-force-push`): halt the sync, mark the repo as `pending-approval`, wait for user action
+
+### Fail-Open Design
+
+If detection itself fails (GitHub rate limits, network errors, API outages), sync proceeds normally. Detection never blocks a sync due to its own failure. Individual branch check failures are skipped — one flaky branch doesn't affect the others.
+
+## Backup Strategies
+
+Configure via **Settings → GitHub Configuration → Destructive Update Protection**.
+
+| Strategy | What It Does | Storage Cost | Best For |
+|---|---|---|---|
+| **Disabled** | No detection, no backups | Zero | Repos you don't care about losing |
+| **Always Backup** | Snapshot before every sync (original behavior) | High | Small mirror sets, maximum safety |
+| **Smart** (default) | Detect force-pushes, backup only when found | Near-zero normally | Most users — efficient protection |
+| **Block & Approve** | Detect force-pushes, block sync until approved | Zero | Critical repos needing manual review |
+
+### Strategy Details
+
+#### Disabled
+
+Syncs proceed without any detection or backup. If a force-push happens on GitHub, the mirror silently overwrites.
+
+#### Always Backup
+
+Creates a git bundle snapshot before every sync regardless of whether a force-push occurred. This is the legacy behavior (equivalent to the old `backupBeforeSync: true`). Safe but expensive for large mirror sets.
+
+#### Smart (`on-force-push`) — Recommended
+
+Runs the force-push detection before each sync. On normal days (no force-pushes), syncs proceed without any backup overhead. When a force-push is detected, a snapshot is created before the sync runs.
+
+This gives you protection when it matters with near-zero cost when it doesn't.
+
+#### Block & Approve (`block-on-force-push`)
+
+Runs detection and, when a force-push is found, **blocks the sync entirely**. The repository is marked as `pending-approval` and excluded from future scheduled syncs until you take action:
+
+- **Approve**: creates a backup first, then syncs (safe)
+- **Dismiss**: clears the flag and resumes normal syncing (no backup)
+
+Use this for repos where you want manual control over destructive changes.
+
+## Additional Settings
+
+These appear when any non-disabled strategy is selected:
+
+### Snapshot Retention Count
+
+How many backup snapshots to keep per repository. Oldest snapshots are deleted when this limit is exceeded. Default: **20**.
+
+### Snapshot Directory
+
+Where git bundle backups are stored. Default: **`data/repo-backups`**. Bundles are organized as `<directory>/<owner>/<repo>/<timestamp>.bundle`.
+
+### Block Sync on Snapshot Failure
+
+Available for **Always Backup** and **Smart** strategies. When enabled, if the snapshot creation fails (disk full, permissions error, etc.), the sync is also blocked. When disabled, sync continues even if the snapshot couldn't be created.
+
+Recommended: **enabled** if you rely on backups for recovery.
+
+## Backward Compatibility
+
+The old `backupBeforeSync` boolean is still recognized:
+
+| Old Setting | New Equivalent |
+|---|---|
+| `backupBeforeSync: true` | `backupStrategy: "always"` |
+| `backupBeforeSync: false` | `backupStrategy: "disabled"` |
+| Neither set | `backupStrategy: "on-force-push"` (new default) |
+
+Existing configurations are automatically mapped. The old field is deprecated but will continue to work.
+
+## Environment Variables
+
+No new environment variables are required. The backup strategy is configured through the web UI and stored in the database alongside other config.
+
+## API
+
+### Approve/Dismiss Blocked Repos
+
+When using the `block-on-force-push` strategy, repos that are blocked can be managed via the API:
+
+```bash
+# Approve sync (creates backup first, then syncs)
+curl -X POST http://localhost:4321/api/job/approve-sync \
+  -H "Content-Type: application/json" \
+  -H "Cookie: <session>" \
+  -d '{"repositoryIds": ["<id>"], "action": "approve"}'
+
+# Dismiss (clear the block, resume normal syncing)
+curl -X POST http://localhost:4321/api/job/approve-sync \
+  -H "Content-Type: application/json" \
+  -H "Cookie: <session>" \
+  -d '{"repositoryIds": ["<id>"], "action": "dismiss"}'
+```
+
+Blocked repos also show an **Approve** / **Dismiss** button in the repository table UI.
+
+## Architecture
+
+### Key Files
+
+| File | Purpose |
+|---|---|
+| `src/lib/utils/force-push-detection.ts` | Core detection: fetch branches, compare SHAs, check ancestry |
+| `src/lib/repo-backup.ts` | Strategy resolver, backup decision logic, bundle creation |
+| `src/lib/gitea-enhanced.ts` | Sync flow integration (calls detection + backup before mirror-sync) |
+| `src/pages/api/job/approve-sync.ts` | Approve/dismiss API endpoint |
+| `src/components/config/GitHubConfigForm.tsx` | Strategy selector UI |
+| `src/components/repositories/RepositoryTable.tsx` | Pending-approval badge + action buttons |
+
+### Detection Flow
+
+```
+syncGiteaRepoEnhanced()
+  │
+  ├─ Resolve backup strategy (config → backupStrategy → backupBeforeSync → default)
+  │
+  ├─ If strategy needs detection ("on-force-push" or "block-on-force-push"):
+  │    │
+  │    ├─ fetchGiteaBranches() — GET /api/v1/repos/{owner}/{repo}/branches
+  │    ├─ fetchGitHubBranches() — octokit.paginate(repos.listBranches)
+  │    │
+  │    └─ For each Gitea branch where SHA differs:
+  │         └─ checkAncestry() — octokit.repos.compareCommits()
+  │              ├─ "ahead" or "identical" → fast-forward (safe)
+  │              ├─ "diverged" or "behind" → force-push detected
+  │              └─ 404/422 → old SHA gone → force-push detected
+  │
+  ├─ If "block-on-force-push" + detected:
+  │    └─ Set repo status to "pending-approval", return early
+  │
+  ├─ If backup needed (always, or on-force-push + detected):
+  │    └─ Create git bundle snapshot
+  │
+  └─ Proceed to mirror-sync
+```
+
+## Troubleshooting
+
+**Repos stuck in "pending-approval"**: Use the Approve or Dismiss buttons in the repository table, or call the approve-sync API endpoint.
+
+**Detection always skipped**: Check the activity log for skip reasons. Common causes: Gitea repo not yet mirrored (first sync), GitHub API rate limits, network errors. All are fail-open by design.
+
+**Backups consuming too much space**: Lower the retention count, or switch from "Always Backup" to "Smart" which only creates backups on actual force-pushes.
+
+**False positives**: The detection compares branch-by-branch. A rebase (which is a force-push) will correctly trigger detection. If you routinely rebase branches, consider using "Smart" instead of "Block & Approve" to avoid constant approval prompts.

docs/NIX_DEPLOYMENT.md

@@ -0,0 +1,486 @@
+# Nix Deployment Guide
+
+This guide covers deploying Gitea Mirror using Nix flakes. The Nix deployment follows the same minimal configuration philosophy as `docker-compose.alt.yml` - secrets are auto-generated, and everything else can be configured via the web UI.
+
+## Prerequisites
+
+- Nix 2.4+ installed
+- For NixOS module: NixOS 23.05+
+
+### Enable Flakes (Recommended)
+
+To enable flakes permanently and avoid typing flags, add to `/etc/nix/nix.conf` or `~/.config/nix/nix.conf`:
+```
+experimental-features = nix-command flakes
+```
+
+**Note:** If you don't enable flakes globally, add `--extra-experimental-features 'nix-command flakes'` to all nix commands shown below.
+
+## Quick Start (Zero Configuration!)
+
+### Run Immediately - No Setup Required
+
+```bash
+# Run directly from the flake (local)
+nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror
+
+# Or from GitHub (once published)
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# If you have flakes enabled globally, simply:
+nix run .#gitea-mirror
+```
+
+That's it! On first run:
+- Secrets (`BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET`) are auto-generated
+- Database is automatically created and initialized
+- Startup recovery and repair scripts run automatically
+- Access the web UI at http://localhost:4321
+
+Everything else (GitHub credentials, Gitea settings, mirror options) is configured through the web interface after signup.
+
+### Development Environment
+
+```bash
+# Enter development shell with all dependencies
+nix develop --extra-experimental-features 'nix-command flakes'
+
+# Or use direnv for automatic environment loading (handles flags automatically)
+echo "use flake" > .envrc
+direnv allow
+```
+
+### Build and Install
+
+```bash
+# Build the package
+nix build --extra-experimental-features 'nix-command flakes'
+
+# Run the built package
+./result/bin/gitea-mirror
+
+# Install to your profile
+nix profile install --extra-experimental-features 'nix-command flakes' .#gitea-mirror
+```
+
+## What Happens on First Run?
+
+Following the same pattern as the Docker deployment, the Nix package automatically:
+
+1. **Creates data directory**: `~/.local/share/gitea-mirror` (or `$DATA_DIR`)
+2. **Generates secrets** (stored securely in data directory):
+   - `BETTER_AUTH_SECRET` - Session authentication (32-char hex)
+   - `ENCRYPTION_SECRET` - Token encryption (48-char base64)
+3. **Initializes database**: SQLite database with Drizzle migrations
+4. **Runs startup scripts**:
+   - Environment configuration loader
+   - Crash recovery for interrupted jobs
+   - Repository status repair
+5. **Starts the application** with graceful shutdown handling
+
+## NixOS Module - Minimal Deployment
+
+### Simplest Possible Configuration
+
+Add to your NixOS configuration (`/etc/nixos/configuration.nix`):
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    gitea-mirror.url = "github:RayLabsHQ/gitea-mirror";
+  };
+
+  outputs = { nixpkgs, gitea-mirror, ... }: {
+    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        gitea-mirror.nixosModules.default
+        {
+          # That's it! Just enable the service
+          services.gitea-mirror.enable = true;
+        }
+      ];
+    };
+  };
+}
+```
+
+Apply with:
+```bash
+sudo nixos-rebuild switch
+```
+
+Access at http://localhost:4321, sign up (first user is admin), and configure everything via the web UI.
+
+### Production Configuration
+
+For production with custom domain and firewall:
+
+```nix
+{
+  services.gitea-mirror = {
+    enable = true;
+    host = "0.0.0.0";
+    port = 4321;
+    betterAuthUrl = "https://mirror.example.com";
+    betterAuthTrustedOrigins = "https://mirror.example.com";
+    openFirewall = true;
+  };
+
+  # Optional: Use with nginx reverse proxy
+  services.nginx = {
+    enable = true;
+    virtualHosts."mirror.example.com" = {
+      locations."/" = {
+        proxyPass = "http://127.0.0.1:4321";
+        proxyWebsockets = true;
+      };
+      enableACME = true;
+      forceSSL = true;
+    };
+  };
+}
+```
+
+### Advanced: Manual Secret Management
+
+If you prefer to manage secrets manually (e.g., with sops-nix or agenix):
+
+1. Create a secrets file:
+```bash
+# /var/lib/gitea-mirror/secrets.env
+BETTER_AUTH_SECRET=your-32-character-minimum-secret-key-here
+ENCRYPTION_SECRET=your-encryption-secret-here
+```
+
+2. Reference it in your configuration:
+```nix
+{
+  services.gitea-mirror = {
+    enable = true;
+    environmentFile = "/var/lib/gitea-mirror/secrets.env";
+  };
+}
+```
+
+### Full Configuration Options
+
+```nix
+{
+  services.gitea-mirror = {
+    enable = true;
+    package = gitea-mirror.packages.x86_64-linux.default;  # Override package
+    dataDir = "/var/lib/gitea-mirror";
+    user = "gitea-mirror";
+    group = "gitea-mirror";
+    host = "0.0.0.0";
+    port = 4321;
+    betterAuthUrl = "https://mirror.example.com";
+    betterAuthTrustedOrigins = "https://mirror.example.com";
+
+    # Concurrency controls (match docker-compose.alt.yml)
+    mirrorIssueConcurrency = 3;  # Set to 1 for perfect chronological order
+    mirrorPullRequestConcurrency = 5;  # Set to 1 for perfect chronological order
+
+    environmentFile = null;  # Optional secrets file
+    openFirewall = true;
+  };
+}
+```
+
+## Service Management (NixOS)
+
+```bash
+# Start the service
+sudo systemctl start gitea-mirror
+
+# Stop the service
+sudo systemctl stop gitea-mirror
+
+# Restart the service
+sudo systemctl restart gitea-mirror
+
+# Check status
+sudo systemctl status gitea-mirror
+
+# View logs
+sudo journalctl -u gitea-mirror -f
+
+# Health check
+curl http://localhost:4321/api/health
+```
+
+## Environment Variables
+
+All variables from `docker-compose.alt.yml` are supported:
+
+```bash
+# === AUTO-GENERATED (Don't set unless you want specific values) ===
+BETTER_AUTH_SECRET          # Auto-generated, stored in data dir
+ENCRYPTION_SECRET           # Auto-generated, stored in data dir
+
+# === CORE SETTINGS (Have good defaults) ===
+DATA_DIR="$HOME/.local/share/gitea-mirror"
+DATABASE_URL="file:$DATA_DIR/gitea-mirror.db"
+HOST="0.0.0.0"
+PORT="4321"
+NODE_ENV="production"
+
+# === BETTER AUTH (Override for custom domains) ===
+BETTER_AUTH_URL="http://localhost:4321"
+BETTER_AUTH_TRUSTED_ORIGINS="http://localhost:4321"
+PUBLIC_BETTER_AUTH_URL="http://localhost:4321"
+
+# === CONCURRENCY CONTROLS ===
+MIRROR_ISSUE_CONCURRENCY=3           # Default: 3 (set to 1 for perfect order)
+MIRROR_PULL_REQUEST_CONCURRENCY=5    # Default: 5 (set to 1 for perfect order)
+
+# === CONFIGURE VIA WEB UI (Not needed at startup) ===
+# GitHub credentials, Gitea settings, mirror options, scheduling, etc.
+# All configured after signup through the web interface
+```
+
+## Database Management
+
+The Nix package includes a database management helper:
+
+```bash
+# Initialize database (done automatically on first run)
+gitea-mirror-db init
+
+# Check database health
+gitea-mirror-db check
+
+# Fix database issues
+gitea-mirror-db fix
+
+# Reset users
+gitea-mirror-db reset-users
+```
+
+## Home Manager Integration
+
+For single-user deployments:
+
+```nix
+{ config, pkgs, ... }:
+let
+  gitea-mirror = (import (fetchTarball "https://github.com/RayLabsHQ/gitea-mirror/archive/main.tar.gz")).packages.${pkgs.system}.default;
+in {
+  home.packages = [ gitea-mirror ];
+
+  # Optional: Run as user service
+  systemd.user.services.gitea-mirror = {
+    Unit = {
+      Description = "Gitea Mirror Service";
+      After = [ "network.target" ];
+    };
+
+    Service = {
+      Type = "simple";
+      ExecStart = "${gitea-mirror}/bin/gitea-mirror";
+      Restart = "always";
+      Environment = [
+        "DATA_DIR=%h/.local/share/gitea-mirror"
+        "HOST=127.0.0.1"
+        "PORT=4321"
+      ];
+    };
+
+    Install = {
+      WantedBy = [ "default.target" ];
+    };
+  };
+}
+```
+
+## Docker Image from Nix (Optional)
+
+You can also use Nix to create a Docker image:
+
+```nix
+# Add to flake.nix packages section
+dockerImage = pkgs.dockerTools.buildLayeredImage {
+  name = "gitea-mirror";
+  tag = "latest";
+  contents = [ self.packages.${system}.default pkgs.cacert pkgs.openssl ];
+  config = {
+    Cmd = [ "${self.packages.${system}.default}/bin/gitea-mirror" ];
+    ExposedPorts = { "4321/tcp" = {}; };
+    Env = [
+      "DATA_DIR=/data"
+      "DATABASE_URL=file:/data/gitea-mirror.db"
+    ];
+    Volumes = { "/data" = {}; };
+  };
+};
+```
+
+Build and load:
+```bash
+nix build --extra-experimental-features 'nix-command flakes' .#dockerImage
+docker load < result
+docker run -p 4321:4321 -v gitea-mirror-data:/data gitea-mirror:latest
+```
+
+## Comparison: Docker vs Nix
+
+Both deployment methods follow the same philosophy:
+
+| Feature | Docker Compose | Nix |
+|---------|---------------|-----|
+| **Configuration** | Minimal (only BETTER_AUTH_SECRET) | Zero config (auto-generated) |
+| **Secret Generation** | Auto-generated & persisted | Auto-generated & persisted |
+| **Database Init** | Automatic on first run | Automatic on first run |
+| **Startup Scripts** | Runs recovery/repair/env-config | Runs recovery/repair/env-config |
+| **Graceful Shutdown** | Signal handling in entrypoint | Signal handling in wrapper |
+| **Health Check** | Docker healthcheck | systemd timer (optional) |
+| **Updates** | `docker pull` | `nix flake update && nixos-rebuild` |
+
+## Troubleshooting
+
+### Check Auto-Generated Secrets
+```bash
+# For standalone
+cat ~/.local/share/gitea-mirror/.better_auth_secret
+cat ~/.local/share/gitea-mirror/.encryption_secret
+
+# For NixOS service
+sudo cat /var/lib/gitea-mirror/.better_auth_secret
+sudo cat /var/lib/gitea-mirror/.encryption_secret
+```
+
+### Database Issues
+```bash
+# Check if database exists
+ls -la ~/.local/share/gitea-mirror/gitea-mirror.db
+
+# Reinitialize (deletes all data!)
+rm ~/.local/share/gitea-mirror/gitea-mirror.db
+gitea-mirror-db init
+```
+
+### Permission Issues (NixOS)
+```bash
+sudo chown -R gitea-mirror:gitea-mirror /var/lib/gitea-mirror
+sudo chmod 700 /var/lib/gitea-mirror
+```
+
+### Port Already in Use
+```bash
+# Change port
+export PORT=8080
+gitea-mirror
+
+# Or in NixOS config
+services.gitea-mirror.port = 8080;
+```
+
+### View Startup Logs
+```bash
+# Standalone (verbose output on console)
+gitea-mirror
+
+# NixOS service
+sudo journalctl -u gitea-mirror -f --since "5 minutes ago"
+```
+
+## Updating
+
+### Standalone Installation
+```bash
+# Update flake lock
+nix flake update --extra-experimental-features 'nix-command flakes'
+
+# Rebuild
+nix build --extra-experimental-features 'nix-command flakes'
+
+# Or update profile
+nix profile upgrade --extra-experimental-features 'nix-command flakes' gitea-mirror
+```
+
+### NixOS
+```bash
+# Update input
+sudo nix flake lock --update-input gitea-mirror --extra-experimental-features 'nix-command flakes'
+
+# Rebuild system
+sudo nixos-rebuild switch --flake .#your-hostname
+```
+
+## Migration from Docker
+
+To migrate from Docker to Nix while keeping your data:
+
+1. **Stop Docker container:**
+   ```bash
+   docker-compose -f docker-compose.alt.yml down
+   ```
+
+2. **Copy data directory:**
+   ```bash
+   # For standalone
+   cp -r ./data ~/.local/share/gitea-mirror
+
+   # For NixOS
+   sudo cp -r ./data /var/lib/gitea-mirror
+   sudo chown -R gitea-mirror:gitea-mirror /var/lib/gitea-mirror
+   ```
+
+3. **Copy secrets (if you want to keep them):**
+   ```bash
+   # Extract from Docker volume
+   docker run --rm -v gitea-mirror_data:/data alpine \
+     cat /data/.better_auth_secret > better_auth_secret
+   docker run --rm -v gitea-mirror_data:/data alpine \
+     cat /data/.encryption_secret > encryption_secret
+
+   # Copy to new location
+   cp better_auth_secret ~/.local/share/gitea-mirror/.better_auth_secret
+   cp encryption_secret ~/.local/share/gitea-mirror/.encryption_secret
+   chmod 600 ~/.local/share/gitea-mirror/.*_secret
+   ```
+
+4. **Start Nix version:**
+   ```bash
+   gitea-mirror
+   ```
+
+## CI/CD Integration
+
+Example GitHub Actions workflow (see `.github/workflows/nix-build.yml`):
+
+```yaml
+name: Nix Build
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v4
+    - uses: DeterminateSystems/nix-installer-action@main
+    - uses: DeterminateSystems/magic-nix-cache-action@main
+    - run: nix flake check
+    - run: nix build --print-build-logs
+```
+
+This uses:
+- **Determinate Nix Installer** - Fast, reliable Nix installation with flakes enabled by default
+- **Magic Nix Cache** - Free caching using GitHub Actions cache (no account needed)
+
+## Resources
+
+- [Nix Manual](https://nixos.org/manual/nix/stable/)
+- [NixOS Options Search](https://search.nixos.org/options)
+- [Nix Pills Tutorial](https://nixos.org/guides/nix-pills/)
+- [Project Documentation](../README.md)
+- [Docker Deployment](../docker-compose.alt.yml) - Equivalent minimal config

docs/NIX_DISTRIBUTION.md

@@ -0,0 +1,322 @@
+# Nix Package Distribution Guide
+
+This guide explains how Gitea Mirror is distributed via Nix and how users can consume it.
+
+## Distribution Methods
+
+### Method 1: Direct GitHub Usage (Zero Infrastructure)
+
+**No CI, releases, or setup needed!** Users can consume directly from GitHub:
+
+```bash
+# Latest from main branch
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Pin to specific commit
+nix run github:RayLabsHQ/gitea-mirror/abc123def
+
+# Pin to git tag
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+```
+
+**How it works:**
+1. Nix fetches the repository from GitHub
+2. Nix reads `flake.nix` and `flake.lock`
+3. Nix builds the package locally on the user's machine
+4. Package is cached in `/nix/store` for reuse
+
+**Pros:**
+- Zero infrastructure needed
+- Works immediately after pushing code
+- Users always get reproducible builds
+
+**Cons:**
+- Users must build from source (slower first time)
+- Requires build dependencies (Bun, etc.)
+
+---
+
+### Method 2: CI Build Caching
+
+The GitHub Actions workflow uses **Magic Nix Cache** (by Determinate Systems) to cache builds:
+
+- **Zero configuration required** - no accounts or tokens needed
+- **Automatic** - CI workflow handles everything
+- **Uses GitHub Actions cache** - fast, reliable, free
+
+#### How It Works:
+
+1. GitHub Actions builds the package on each push/PR
+2. Build artifacts are cached in GitHub Actions cache
+3. Subsequent builds reuse cached dependencies (faster CI)
+
+Note: This caches CI builds. Users still build locally, but the flake.lock ensures reproducibility.
+
+---
+
+### Method 3: nixpkgs Submission (Official Distribution)
+
+Submit to the official Nix package repository for maximum visibility.
+
+#### Process:
+
+1. **Prepare package** (already done with `flake.nix`)
+2. **Test thoroughly**
+3. **Submit PR to nixpkgs:** https://github.com/NixOS/nixpkgs
+
+#### User Experience:
+
+```bash
+# After acceptance into nixpkgs
+nix run nixpkgs#gitea-mirror
+
+# NixOS configuration
+environment.systemPackages = [ pkgs.gitea-mirror ];
+```
+
+**Pros:**
+- Maximum discoverability (official repo)
+- Trusted by Nix community
+- Included in NixOS search
+- Binary caching by cache.nixos.org
+
+**Cons:**
+- Submission/review process
+- Must follow nixpkgs guidelines
+- Updates require PRs
+
+---
+
+## Current Distribution Strategy
+
+### Phase 1: Direct GitHub (Immediate) ✅
+
+Already working! Users can:
+
+```bash
+nix run github:RayLabsHQ/gitea-mirror
+```
+
+### Phase 2: CI Build Validation ✅
+
+GitHub Actions workflow validates builds on every push/PR:
+
+- Uses Magic Nix Cache for fast CI builds
+- Tests on both Linux and macOS
+- No setup required - works automatically
+
+### Phase 3: Version Releases (Optional)
+
+Tag releases for version pinning:
+
+```bash
+git tag vX.Y.Z
+git push origin vX.Y.Z
+
+# Users can then pin:
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+```
+
+### Phase 4: nixpkgs Submission (Long Term)
+
+Once package is stable and well-tested, submit to nixpkgs.
+
+---
+
+## User Documentation
+
+### For Users: How to Install
+
+Add this to your `docs/NIX_DEPLOYMENT.md`:
+
+#### Option 1: Direct Install (No Configuration)
+
+```bash
+# Run immediately
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Install to profile
+nix profile install --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+```
+
+#### Option 2: Pin to Specific Version
+
+```bash
+# Pin to git tag
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+
+# Pin to commit
+nix run github:RayLabsHQ/gitea-mirror/abc123def
+
+# Lock in flake.nix
+inputs.gitea-mirror.url = "github:RayLabsHQ/gitea-mirror/vX.Y.Z";
+```
+
+#### Option 3: NixOS Configuration
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    gitea-mirror.url = "github:RayLabsHQ/gitea-mirror";
+    # Or pin to version:
+    # gitea-mirror.url = "github:RayLabsHQ/gitea-mirror/vX.Y.Z";
+  };
+
+  outputs = { nixpkgs, gitea-mirror, ... }: {
+    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
+      modules = [
+        gitea-mirror.nixosModules.default
+        {
+          services.gitea-mirror = {
+            enable = true;
+            betterAuthUrl = "https://mirror.example.com";
+            openFirewall = true;
+          };
+        }
+      ];
+    };
+  };
+}
+```
+
+---
+
+## Maintaining the Distribution
+
+### Releasing New Versions
+
+```bash
+# 1. Update version in package.json
+vim package.json  # Update version field
+
+# 2. Update flake.nix version (line 17)
+vim flake.nix  # Update version = "X.Y.Z";
+
+# 3. Commit changes
+git add package.json flake.nix
+git commit -m "chore: bump version to vX.Y.Z"
+
+# 4. Create git tag
+git tag vX.Y.Z
+git push origin main
+git push origin vX.Y.Z
+
+# 5. GitHub Actions builds and caches automatically
+```
+
+Users can then pin to the new version:
+```bash
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+```
+
+### Updating Flake Lock
+
+The `flake.lock` file pins all dependencies. Update it periodically:
+
+```bash
+# Update all inputs
+nix flake update
+
+# Update specific input
+nix flake lock --update-input nixpkgs
+
+# Test after update
+nix build
+nix flake check
+
+# Commit the updated lock file
+git add flake.lock
+git commit -m "chore: update flake dependencies"
+git push
+```
+
+---
+
+## Troubleshooting Distribution Issues
+
+### Users Report Build Failures
+
+1. **Check GitHub Actions:** Ensure CI is passing
+2. **Test locally:** `nix flake check`
+3. **Check flake.lock:** May need update if dependencies changed
+
+### CI Cache Not Working
+
+1. **Check workflow logs:** Review GitHub Actions for errors
+2. **Clear cache:** GitHub Actions → Caches → Delete relevant cache
+3. **Verify flake.lock:** May need `nix flake update` if dependencies changed
+
+### Version Pinning Not Working
+
+```bash
+# Verify tag exists
+git tag -l
+
+# Ensure tag is pushed
+git ls-remote --tags origin
+
+# Test specific tag
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+```
+
+---
+
+## Advanced: Custom Binary Cache
+
+If you prefer self-hosting instead of Cachix:
+
+### Option 1: S3-Compatible Storage
+
+```nix
+# Generate signing key
+nix-store --generate-binary-cache-key cache.example.com cache-priv-key.pem cache-pub-key.pem
+
+# Push to S3
+nix copy --to s3://my-nix-cache?region=us-east-1 $(nix-build)
+```
+
+Users configure:
+```nix
+substituters = https://my-bucket.s3.amazonaws.com/nix-cache
+trusted-public-keys = cache.example.com:BASE64_PUBLIC_KEY
+```
+
+### Option 2: Self-Hosted Nix Store
+
+Run `nix-serve` on your server:
+
+```bash
+# On server
+nix-serve -p 8080
+
+# Behind nginx/caddy
+proxy_pass http://localhost:8080;
+```
+
+Users configure:
+```nix
+substituters = https://cache.example.com
+trusted-public-keys = YOUR_KEY
+```
+
+---
+
+## Comparison: Distribution Methods
+
+| Method | Setup Time | User Speed | Cost | Discoverability |
+|--------|-----------|------------|------|-----------------|
+| Direct GitHub | 0 min | Slow (build) | Free | Low |
+| nixpkgs | Hours/days | Fast (binary) | Free | High |
+| Self-hosted cache | 30+ min | Fast (binary) | Server cost | Low |
+
+**Current approach:** Direct GitHub consumption with CI validation using Magic Nix Cache. Users build locally (reproducible via flake.lock). Consider **nixpkgs** submission for maximum reach once the package is mature.
+
+---
+
+## Resources
+
+- [Nix Flakes Documentation](https://nixos.wiki/wiki/Flakes)
+- [Magic Nix Cache](https://github.com/DeterminateSystems/magic-nix-cache-action)
+- [nixpkgs Contributing Guide](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md)
+- [Nix Binary Cache Setup](https://nixos.org/manual/nix/stable/package-management/binary-cache-substituter.html)

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.
+- **[NIX_DEPLOYMENT.md](./NIX_DEPLOYMENT.md)** – User-facing deployment guide for Nix and NixOS.
+- **[NIX_DISTRIBUTION.md](./NIX_DISTRIBUTION.md)** – Maintainer notes for packaging, releases, and distribution strategy.
 
-- **[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
-
-## 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.
+- 🎯 Contribution guide: [../CONTRIBUTING.md](../CONTRIBUTING.md)
+- 🐞 Issues & feature requests: <https://github.com/RayLabsHQ/gitea-mirror/issues>
+- 💬 Discussions: <https://github.com/RayLabsHQ/gitea-mirror/discussions>
+- 🔐 Security policy & advisories: <https://github.com/RayLabsHQ/gitea-mirror/security>

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/SSO-OIDC-SETUP.md

@@ -81,6 +81,26 @@ Replace `{provider-id}` with your chosen Provider ID.
    - Client Secret: [Your Okta Client Secret]
    - Click "Discover" to auto-fill endpoints
 
+### Example: Authentik SSO Setup
+
+Working Authentik deployments (see [#134](https://github.com/RayLabsHQ/gitea-mirror/issues/134)) follow these steps:
+
+1. In Authentik, create a new **Application** and OIDC **Provider** (implicit flow works well for testing).
+2. Start creating an SSO provider inside Gitea Mirror so you can copy the redirect URL shown (`https://your-domain.com/api/auth/sso/callback/authentik` if you pick `authentik` as your Provider ID).
+3. Paste that redirect URL into the Authentik Provider configuration and finish creating the provider.
+4. Copy the Authentik issuer URL, client ID, and client secret.
+5. Back in Gitea Mirror:
+   - Issuer URL: the exact value from Authentik (keep any trailing slash Authentik shows).
+   - Provider ID: match the one you used in step 2.
+   - Click **Discover** so Gitea Mirror stores the authorization, token, and JWKS endpoints (Authentik publishes them via discovery).
+   - Domain: enter the email domain you expect to match (e.g. `example.com`).
+6. Save the provider and test the login flow.
+
+Notes:
+- Make sure `BETTER_AUTH_URL` and (if you serve the UI from multiple origins) `BETTER_AUTH_TRUSTED_ORIGINS` point at the public URL users reach. A mismatch can surface as 500 errors after redirect.
+- Authentik must report the user’s email as verified (default behavior) so Gitea Mirror can auto-link accounts.
+- If you created an Authentik provider before v3.8.10 you should delete it and re-add it after upgrading; older versions saved incomplete endpoint data which leads to the `url.startsWith` error explained in the Troubleshooting section.
+
 ## Setting up OIDC Provider
 
 The OIDC Provider feature allows other applications to use Gitea Mirror as their authentication provider.
@@ -165,6 +185,7 @@ When an application requests authentication:
 1. **"Invalid origin" error**: Check that your Gitea Mirror URL matches the configured redirect URI
 2. **"Provider not found" error**: Ensure the provider is properly configured and enabled
 3. **Redirect loop**: Verify the redirect URI in both Gitea Mirror and the SSO provider match exactly
+4. **`TypeError: undefined is not an object (evaluating 'url.startsWith')`**: This indicates the stored provider configuration is missing OIDC endpoints. Delete the provider from Gitea Mirror and re-register it using the **Discover** button so authorization/token URLs are saved (see [#73](https://github.com/RayLabsHQ/gitea-mirror/issues/73) and [#122](https://github.com/RayLabsHQ/gitea-mirror/issues/122) for examples).
 
 ### OIDC Provider Issues
 
@@ -202,4 +223,4 @@ This immediately prevents the application from authenticating new users.
 If migrating from the previous JWT-based authentication:
 - Existing users remain unaffected
 - Users can continue using email/password authentication
-- SSO can be added as an additional authentication method
+- SSO can be added as an additional authentication method

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

drizzle/0006_military_la_nuit.sql

@@ -0,0 +1,4 @@
+ALTER TABLE `accounts` ADD `id_token` text;--> statement-breakpoint
+ALTER TABLE `accounts` ADD `access_token_expires_at` integer;--> statement-breakpoint
+ALTER TABLE `accounts` ADD `refresh_token_expires_at` integer;--> statement-breakpoint
+ALTER TABLE `accounts` ADD `scope` text;

drizzle/0007_whole_hellion.sql

@@ -0,0 +1,18 @@
+ALTER TABLE `organizations` ADD `normalized_name` text NOT NULL DEFAULT '';--> statement-breakpoint
+UPDATE `organizations` SET `normalized_name` = lower(trim(`name`));--> statement-breakpoint
+DELETE FROM `organizations`
+WHERE rowid NOT IN (
+  SELECT MIN(rowid)
+  FROM `organizations`
+  GROUP BY `user_id`, `normalized_name`
+);--> statement-breakpoint
+CREATE UNIQUE INDEX `uniq_organizations_user_normalized_name` ON `organizations` (`user_id`,`normalized_name`);--> statement-breakpoint
+ALTER TABLE `repositories` ADD `normalized_full_name` text NOT NULL DEFAULT '';--> statement-breakpoint
+UPDATE `repositories` SET `normalized_full_name` = lower(trim(`full_name`));--> statement-breakpoint
+DELETE FROM `repositories`
+WHERE rowid NOT IN (
+  SELECT MIN(rowid)
+  FROM `repositories`
+  GROUP BY `user_id`, `normalized_full_name`
+);--> statement-breakpoint
+CREATE UNIQUE INDEX `uniq_repositories_user_normalized_full_name` ON `repositories` (`user_id`,`normalized_full_name`);

drizzle/0008_serious_thena.sql

@@ -0,0 +1 @@
+ALTER TABLE `repositories` ADD `metadata` text;

drizzle/meta/_journal.json

@@ -43,6 +43,27 @@
       "when": 1757786449446,
       "tag": "0005_polite_preak",
       "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "6",
+      "when": 1761483928546,
+      "tag": "0006_military_la_nuit",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "6",
+      "when": 1761534391115,
+      "tag": "0007_whole_hellion",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "6",
+      "when": 1761802056073,
+      "tag": "0008_serious_thena",
+      "breakpoints": true
     }
   ]
 }

flake.lock

@@ -0,0 +1,170 @@
+{
+  "nodes": {
+    "bun2nix": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "import-tree": "import-tree",
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "systems": "systems",
+        "treefmt-nix": "treefmt-nix"
+      },
+      "locked": {
+        "lastModified": 1770895533,
+        "narHash": "sha256-v3QaK9ugy9bN9RXDnjw0i2OifKmz2NnKM82agtqm/UY=",
+        "owner": "nix-community",
+        "repo": "bun2nix",
+        "rev": "c843f477b15f51151f8c6bcc886954699440a6e1",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "bun2nix",
+        "type": "github"
+      }
+    },
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1769996383,
+        "narHash": "sha256-AnYjnFWgS49RlqX7LrC4uA+sCCDBj0Ry/WOJ5XWAsa0=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "57928607ea566b5db3ad13af0e57e921e6b12381",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems_2"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "import-tree": {
+      "locked": {
+        "lastModified": 1763762820,
+        "narHash": "sha256-ZvYKbFib3AEwiNMLsejb/CWs/OL/srFQ8AogkebEPF0=",
+        "owner": "vic",
+        "repo": "import-tree",
+        "rev": "3c23749d8013ec6daa1d7255057590e9ca726646",
+        "type": "github"
+      },
+      "original": {
+        "owner": "vic",
+        "repo": "import-tree",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1761672384,
+        "narHash": "sha256-o9KF3DJL7g7iYMZq9SWgfS1BFlNbsm6xplRjVlOCkXI=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "08dacfca559e1d7da38f3cf05f1f45ee9bfd213c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-lib": {
+      "locked": {
+        "lastModified": 1769909678,
+        "narHash": "sha256-cBEymOf4/o3FD5AZnzC3J9hLbiZ+QDT/KDuyHXVJOpM=",
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "rev": "72716169fe93074c333e8d0173151350670b824c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "bun2nix": "bun2nix",
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "systems_2": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "treefmt-nix": {
+      "inputs": {
+        "nixpkgs": [
+          "bun2nix",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1770228511,
+        "narHash": "sha256-wQ6NJSuFqAEmIg2VMnLdCnUc0b7vslUohqqGGD+Fyxk=",
+        "owner": "numtide",
+        "repo": "treefmt-nix",
+        "rev": "337a4fe074be1042a35086f15481d763b8ddc0e7",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "treefmt-nix",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,468 @@
+{
+  description = "Gitea Mirror - Self-hosted GitHub to Gitea mirroring service";
+
+  nixConfig = {
+    extra-substituters = [
+      "https://nix-community.cachix.org"
+    ];
+    extra-trusted-public-keys = [
+      "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
+    ];
+  };
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+    bun2nix = {
+      url = "github:nix-community/bun2nix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = { self, nixpkgs, flake-utils, bun2nix }:
+    let
+      forEachSystem = flake-utils.lib.eachDefaultSystem;
+    in
+    (forEachSystem (system:
+      let
+        pkgs = nixpkgs.legacyPackages.${system};
+        b2n = bun2nix.packages.${system}.default;
+
+        # Build the application
+        gitea-mirror = pkgs.stdenv.mkDerivation {
+          pname = "gitea-mirror";
+          version = "3.9.6";
+
+          src = ./.;
+
+          nativeBuildInputs = [
+            pkgs.bun
+            b2n.hook
+          ];
+
+          buildInputs = with pkgs; [
+            sqlite
+            openssl
+          ];
+
+          bunDeps = b2n.fetchBunDeps {
+            bunNix = ./bun.nix;
+          };
+
+          # bun2nix defaults to isolated installs on Linux, which can be
+          # very slow in CI for larger dependency trees and may appear stuck.
+          # Use hoisted linker and fail fast on lockfile drift.
+          bunInstallFlags = if pkgs.stdenv.hostPlatform.isDarwin then [
+            "--linker=hoisted"
+            "--backend=copyfile"
+            "--frozen-lockfile"
+            "--no-progress"
+          ] else [
+            "--linker=hoisted"
+            "--frozen-lockfile"
+            "--no-progress"
+          ];
+
+          # Let the bun2nix hook handle dependency installation via the
+          # pre-fetched cache, but skip its default build/check/install
+          # phases since we have custom ones.
+          dontUseBunBuild = true;
+          dontUseBunCheck = true;
+          dontUseBunInstall = true;
+
+          buildPhase = ''
+            runHook preBuild
+            export HOME=$TMPDIR
+
+            # The bun2nix cache is in the read-only Nix store, but bunx/astro
+            # may try to write to it at build time. Copy the cache to a
+            # writable location.
+            if [ -n "$BUN_INSTALL_CACHE_DIR" ] && [ -d "$BUN_INSTALL_CACHE_DIR" ]; then
+              WRITABLE_CACHE="$TMPDIR/bun-cache"
+              cp -rL "$BUN_INSTALL_CACHE_DIR" "$WRITABLE_CACHE" 2>/dev/null || true
+              chmod -R u+w "$WRITABLE_CACHE" 2>/dev/null || true
+              export BUN_INSTALL_CACHE_DIR="$WRITABLE_CACHE"
+            fi
+
+            # Build the Astro application
+            bun run build
+
+            runHook postBuild
+          '';
+
+          installPhase = ''
+            runHook preInstall
+
+            mkdir -p $out/lib/gitea-mirror
+            mkdir -p $out/bin
+
+            # Copy the built application
+            cp -r dist $out/lib/gitea-mirror/
+            cp -r node_modules $out/lib/gitea-mirror/
+            cp -r scripts $out/lib/gitea-mirror/
+            cp -r src $out/lib/gitea-mirror/
+            cp -r drizzle $out/lib/gitea-mirror/
+            cp package.json $out/lib/gitea-mirror/
+            cp tsconfig.json $out/lib/gitea-mirror/
+
+            # Create entrypoint script that matches Docker behavior
+            cat > $out/bin/gitea-mirror <<'EOF'
+#!${pkgs.bash}/bin/bash
+set -e
+
+# === DEFAULT CONFIGURATION ===
+# These match docker-compose.alt.yml defaults
+export DATA_DIR=''${DATA_DIR:-"$HOME/.local/share/gitea-mirror"}
+export DATABASE_URL=''${DATABASE_URL:-"file:$DATA_DIR/gitea-mirror.db"}
+export HOST=''${HOST:-"0.0.0.0"}
+export PORT=''${PORT:-"4321"}
+export NODE_ENV=''${NODE_ENV:-"production"}
+
+# Better Auth configuration
+export BETTER_AUTH_URL=''${BETTER_AUTH_URL:-"http://localhost:4321"}
+export BETTER_AUTH_TRUSTED_ORIGINS=''${BETTER_AUTH_TRUSTED_ORIGINS:-"http://localhost:4321"}
+export PUBLIC_BETTER_AUTH_URL=''${PUBLIC_BETTER_AUTH_URL:-"http://localhost:4321"}
+
+# Concurrency settings (match docker-compose.alt.yml)
+export MIRROR_ISSUE_CONCURRENCY=''${MIRROR_ISSUE_CONCURRENCY:-3}
+export MIRROR_PULL_REQUEST_CONCURRENCY=''${MIRROR_PULL_REQUEST_CONCURRENCY:-5}
+
+# Create data directory
+mkdir -p "$DATA_DIR"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+APP_DIR="$SCRIPT_DIR/../lib/gitea-mirror"
+
+# The app uses process.cwd()/data for the database, but the Nix store
+# is read-only. Create a writable working directory with symlinks to
+# the app files and a real data directory.
+WORK_DIR="$DATA_DIR/.workdir"
+mkdir -p "$WORK_DIR"
+for item in dist node_modules scripts src drizzle package.json tsconfig.json; do
+  ln -sfn "$APP_DIR/$item" "$WORK_DIR/$item"
+done
+ln -sfn "$DATA_DIR" "$WORK_DIR/data"
+cd "$WORK_DIR"
+
+# === AUTO-GENERATE SECRETS ===
+BETTER_AUTH_SECRET_FILE="$DATA_DIR/.better_auth_secret"
+ENCRYPTION_SECRET_FILE="$DATA_DIR/.encryption_secret"
+
+# Generate BETTER_AUTH_SECRET if not provided
+if [ -z "$BETTER_AUTH_SECRET" ]; then
+  if [ -f "$BETTER_AUTH_SECRET_FILE" ]; then
+    echo "Using previously generated BETTER_AUTH_SECRET"
+    export BETTER_AUTH_SECRET=$(cat "$BETTER_AUTH_SECRET_FILE")
+  else
+    echo "Generating a secure random BETTER_AUTH_SECRET"
+    GENERATED_SECRET=$(${pkgs.openssl}/bin/openssl rand -hex 32)
+    export BETTER_AUTH_SECRET="$GENERATED_SECRET"
+    echo "$GENERATED_SECRET" > "$BETTER_AUTH_SECRET_FILE"
+    chmod 600 "$BETTER_AUTH_SECRET_FILE"
+    echo "✅ BETTER_AUTH_SECRET generated and saved to $BETTER_AUTH_SECRET_FILE"
+  fi
+fi
+
+# Generate ENCRYPTION_SECRET if not provided
+if [ -z "$ENCRYPTION_SECRET" ]; then
+  if [ -f "$ENCRYPTION_SECRET_FILE" ]; then
+    echo "Using previously generated ENCRYPTION_SECRET"
+    export ENCRYPTION_SECRET=$(cat "$ENCRYPTION_SECRET_FILE")
+  else
+    echo "Generating a secure random ENCRYPTION_SECRET"
+    GENERATED_ENCRYPTION_SECRET=$(${pkgs.openssl}/bin/openssl rand -base64 36)
+    export ENCRYPTION_SECRET="$GENERATED_ENCRYPTION_SECRET"
+    echo "$GENERATED_ENCRYPTION_SECRET" > "$ENCRYPTION_SECRET_FILE"
+    chmod 600 "$ENCRYPTION_SECRET_FILE"
+    echo "✅ ENCRYPTION_SECRET generated and saved to $ENCRYPTION_SECRET_FILE"
+  fi
+fi
+
+# === DATABASE INITIALIZATION ===
+DB_PATH=$(echo "$DATABASE_URL" | ${pkgs.gnused}/bin/sed 's|^file:||')
+if [ ! -f "$DB_PATH" ]; then
+  echo "Database not found. It will be created and initialized via Drizzle migrations on first app startup..."
+  touch "$DB_PATH"
+else
+  echo "Database already exists, Drizzle will check for pending migrations on startup..."
+fi
+
+# === STARTUP SCRIPTS ===
+# Initialize configuration from environment variables
+echo "Checking for environment configuration..."
+if [ -f "scripts/startup-env-config.ts" ]; then
+  echo "Loading configuration from environment variables..."
+  ${pkgs.bun}/bin/bun scripts/startup-env-config.ts && \
+    echo "✅ Environment configuration loaded successfully" || \
+    echo "⚠️  Environment configuration loading completed with warnings"
+fi
+
+# Run startup recovery
+echo "Running startup recovery..."
+if [ -f "scripts/startup-recovery.ts" ]; then
+  ${pkgs.bun}/bin/bun scripts/startup-recovery.ts --timeout=30000 && \
+    echo "✅ Startup recovery completed successfully" || \
+    echo "⚠️  Startup recovery completed with warnings"
+fi
+
+# Run repository status repair
+echo "Running repository status repair..."
+if [ -f "scripts/repair-mirrored-repos.ts" ]; then
+  ${pkgs.bun}/bin/bun scripts/repair-mirrored-repos.ts --startup && \
+    echo "✅ Repository status repair completed successfully" || \
+    echo "⚠️  Repository status repair completed with warnings"
+fi
+
+# === SIGNAL HANDLING ===
+shutdown_handler() {
+  echo "🛑 Received shutdown signal, forwarding to application..."
+  if [ ! -z "$APP_PID" ]; then
+    kill -TERM "$APP_PID" 2>/dev/null || true
+    wait "$APP_PID" 2>/dev/null || true
+  fi
+  exit 0
+}
+
+trap 'shutdown_handler' TERM INT HUP
+
+# === START APPLICATION ===
+echo "Starting Gitea Mirror..."
+echo "Access the web interface at $BETTER_AUTH_URL"
+${pkgs.bun}/bin/bun dist/server/entry.mjs &
+APP_PID=$!
+
+wait "$APP_PID"
+EOF
+            chmod +x $out/bin/gitea-mirror
+
+            # Create database management helper
+            cat > $out/bin/gitea-mirror-db <<'EOF'
+#!${pkgs.bash}/bin/bash
+export DATA_DIR=''${DATA_DIR:-"$HOME/.local/share/gitea-mirror"}
+mkdir -p "$DATA_DIR"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$SCRIPT_DIR/../lib/gitea-mirror"
+exec ${pkgs.bun}/bin/bun scripts/manage-db.ts "$@"
+EOF
+            chmod +x $out/bin/gitea-mirror-db
+
+            runHook postInstall
+          '';
+
+          meta = with pkgs.lib; {
+            description = "Self-hosted GitHub to Gitea mirroring service";
+            homepage = "https://github.com/RayLabsHQ/gitea-mirror";
+            license = licenses.mit;
+            maintainers = [ ];
+            platforms = platforms.linux ++ platforms.darwin;
+          };
+        };
+
+      in
+      {
+        packages = {
+          default = gitea-mirror;
+          gitea-mirror = gitea-mirror;
+        };
+
+        # Development shell
+        devShells.default = pkgs.mkShell {
+          buildInputs = with pkgs; [
+            bun
+            sqlite
+            openssl
+            b2n
+          ];
+
+          shellHook = ''
+            echo "🚀 Gitea Mirror development environment"
+            echo ""
+            echo "Quick start:"
+            echo "  bun install       # Install dependencies"
+            echo "  bun run dev       # Start development server"
+            echo "  bun run build     # Build for production"
+            echo ""
+            echo "Nix packaging:"
+            echo "  bun2nix -o bun.nix  # Regenerate bun.nix after dependency changes"
+            echo "  nix build           # Build the package"
+            echo ""
+            echo "Database:"
+            echo "  bun run manage-db init   # Initialize database"
+            echo "  bun run db:studio        # Open Drizzle Studio"
+          '';
+        };
+
+      }
+    )) // {
+      nixosModules.default = { config, lib, pkgs, ... }:
+        with lib;
+        let
+          cfg = config.services.gitea-mirror;
+        in {
+          options.services.gitea-mirror = {
+            enable = mkEnableOption "Gitea Mirror service";
+
+            package = mkOption {
+              type = types.package;
+              default = self.packages.${pkgs.system}.default;
+              description = "The Gitea Mirror package to use";
+            };
+
+            dataDir = mkOption {
+              type = types.path;
+              default = "/var/lib/gitea-mirror";
+              description = "Directory to store data and database";
+            };
+
+            user = mkOption {
+              type = types.str;
+              default = "gitea-mirror";
+              description = "User account under which Gitea Mirror runs";
+            };
+
+            group = mkOption {
+              type = types.str;
+              default = "gitea-mirror";
+              description = "Group under which Gitea Mirror runs";
+            };
+
+            host = mkOption {
+              type = types.str;
+              default = "0.0.0.0";
+              description = "Host to bind to";
+            };
+
+            port = mkOption {
+              type = types.port;
+              default = 4321;
+              description = "Port to listen on";
+            };
+
+            betterAuthUrl = mkOption {
+              type = types.str;
+              default = "http://localhost:4321";
+              description = "Better Auth URL (external URL of the service)";
+            };
+
+            betterAuthTrustedOrigins = mkOption {
+              type = types.str;
+              default = "http://localhost:4321";
+              description = "Comma-separated list of trusted origins for Better Auth";
+            };
+
+            mirrorIssueConcurrency = mkOption {
+              type = types.int;
+              default = 3;
+              description = "Number of concurrent issue mirror operations (set to 1 for perfect ordering)";
+            };
+
+            mirrorPullRequestConcurrency = mkOption {
+              type = types.int;
+              default = 5;
+              description = "Number of concurrent PR mirror operations (set to 1 for perfect ordering)";
+            };
+
+            environmentFile = mkOption {
+              type = types.nullOr types.path;
+              default = null;
+              description = ''
+                Path to file containing environment variables.
+                Only needed if you want to set BETTER_AUTH_SECRET or ENCRYPTION_SECRET manually.
+                Otherwise, secrets will be auto-generated and stored in the data directory.
+
+                Example:
+                  BETTER_AUTH_SECRET=your-32-character-secret-here
+                  ENCRYPTION_SECRET=your-encryption-secret-here
+              '';
+            };
+
+            openFirewall = mkOption {
+              type = types.bool;
+              default = false;
+              description = "Open the firewall for the specified port";
+            };
+          };
+
+          config = mkIf cfg.enable {
+            users.users.${cfg.user} = {
+              isSystemUser = true;
+              group = cfg.group;
+              home = cfg.dataDir;
+              createHome = true;
+            };
+
+            users.groups.${cfg.group} = {};
+
+            systemd.services.gitea-mirror = {
+              description = "Gitea Mirror - GitHub to Gitea mirroring service";
+              after = [ "network.target" ];
+              wantedBy = [ "multi-user.target" ];
+
+              environment = {
+                DATA_DIR = cfg.dataDir;
+                DATABASE_URL = "file:${cfg.dataDir}/gitea-mirror.db";
+                HOST = cfg.host;
+                PORT = toString cfg.port;
+                NODE_ENV = "production";
+                BETTER_AUTH_URL = cfg.betterAuthUrl;
+                BETTER_AUTH_TRUSTED_ORIGINS = cfg.betterAuthTrustedOrigins;
+                PUBLIC_BETTER_AUTH_URL = cfg.betterAuthUrl;
+                MIRROR_ISSUE_CONCURRENCY = toString cfg.mirrorIssueConcurrency;
+                MIRROR_PULL_REQUEST_CONCURRENCY = toString cfg.mirrorPullRequestConcurrency;
+              };
+
+              serviceConfig = {
+                Type = "simple";
+                User = cfg.user;
+                Group = cfg.group;
+                ExecStart = "${cfg.package}/bin/gitea-mirror";
+                Restart = "always";
+                RestartSec = "10s";
+
+                # Security hardening
+                NoNewPrivileges = true;
+                PrivateTmp = true;
+                ProtectSystem = "strict";
+                ProtectHome = true;
+                ReadWritePaths = [ cfg.dataDir ];
+
+                # Graceful shutdown
+                TimeoutStopSec = "30s";
+                KillMode = "mixed";
+                KillSignal = "SIGTERM";
+              } // optionalAttrs (cfg.environmentFile != null) {
+                EnvironmentFile = cfg.environmentFile;
+              };
+            };
+
+            # Health check timer (optional monitoring)
+            systemd.timers.gitea-mirror-healthcheck = {
+              description = "Gitea Mirror health check timer";
+              wantedBy = [ "timers.target" ];
+              timerConfig = {
+                OnBootSec = "5min";
+                OnUnitActiveSec = "5min";
+              };
+            };
+
+            systemd.services.gitea-mirror-healthcheck = {
+              description = "Gitea Mirror health check";
+              after = [ "gitea-mirror.service" ];
+              serviceConfig = {
+                Type = "oneshot";
+                ExecStart = "${pkgs.bash}/bin/bash -c '${pkgs.curl}/bin/curl -f http://127.0.0.1:${toString cfg.port}/api/health || true'";
+                User = "nobody";
+              };
+            };
+
+            networking.firewall = mkIf cfg.openFirewall {
+              allowedTCPPorts = [ cfg.port ];
+            };
+          };
+        };
+
+      # Overlay for adding to nixpkgs
+      overlays.default = final: prev: {
+        gitea-mirror = self.packages.${final.system}.default;
+      };
+    };
+}

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.5",
+  "version": "3.12.5",
   "engines": {
     "bun": ">=1.2.9"
   },
@@ -16,6 +16,7 @@
     "check-db": "bun scripts/manage-db.ts check",
     "fix-db": "bun scripts/manage-db.ts fix",
     "reset-users": "bun scripts/manage-db.ts reset-users",
+    "reset-password": "bun scripts/manage-db.ts reset-password",
     "db:generate": "bun drizzle-kit generate",
     "db:migrate": "bun drizzle-kit migrate",
     "db:push": "bun drizzle-kit push",
@@ -35,80 +36,88 @@
     "test": "bun test",
     "test:watch": "bun test --watch",
     "test:coverage": "bun test --coverage",
+    "test:e2e": "bash tests/e2e/run-e2e.sh",
+    "test:e2e:ci": "bash tests/e2e/run-e2e.sh --ci",
+    "test:e2e:keep": "bash tests/e2e/run-e2e.sh --keep",
+    "test:e2e:cleanup": "bash tests/e2e/cleanup.sh",
     "astro": "bunx --bun astro"
   },
   "overrides": {
-    "@esbuild-kit/esm-loader": "npm:tsx@^4.20.5",
-    "devalue": "^5.3.2"
+    "@esbuild-kit/esm-loader": "npm:tsx@^4.21.0",
+    "devalue": "^5.5.0"
   },
   "dependencies": {
-    "@astrojs/check": "^0.9.5",
-    "@astrojs/mdx": "4.3.7",
-    "@astrojs/node": "9.5.0",
-    "@astrojs/react": "^4.4.0",
-    "@better-auth/sso": "^1.3.28",
-    "@octokit/plugin-throttling": "^11.0.2",
-    "@octokit/rest": "^22.0.0",
+    "@astrojs/check": "^0.9.6",
+    "@astrojs/mdx": "4.3.13",
+    "@astrojs/node": "9.5.4",
+    "@astrojs/react": "^4.4.2",
+    "@better-auth/sso": "1.4.19",
+    "@octokit/plugin-throttling": "^11.0.3",
+    "@octokit/rest": "^22.0.1",
     "@radix-ui/react-accordion": "^1.2.12",
-    "@radix-ui/react-avatar": "^1.1.10",
+    "@radix-ui/react-avatar": "^1.1.11",
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-collapsible": "^1.1.12",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-hover-card": "^1.1.15",
-    "@radix-ui/react-label": "^2.1.7",
+    "@radix-ui/react-label": "^2.1.8",
     "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-progress": "^1.1.7",
+    "@radix-ui/react-progress": "^1.1.8",
     "@radix-ui/react-radio-group": "^1.3.8",
     "@radix-ui/react-scroll-area": "^1.2.10",
     "@radix-ui/react-select": "^2.2.6",
-    "@radix-ui/react-separator": "^1.1.7",
-    "@radix-ui/react-slot": "^1.2.3",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-switch": "^1.2.6",
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-tooltip": "^1.2.8",
-    "@tailwindcss/vite": "^4.1.15",
-    "@tanstack/react-virtual": "^3.13.12",
+    "@tailwindcss/vite": "^4.2.1",
+    "@tanstack/react-virtual": "^3.13.19",
     "@types/canvas-confetti": "^1.9.0",
-    "@types/react": "^19.2.2",
-    "@types/react-dom": "^19.2.2",
-    "astro": "^5.14.8",
-    "bcryptjs": "^3.0.2",
-    "better-auth": "^1.3.28",
-    "canvas-confetti": "^1.9.3",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "astro": "^5.18.0",
+    "bcryptjs": "^3.0.3",
+    "better-auth": "1.4.19",
+    "buffer": "^6.0.3",
+    "canvas-confetti": "^1.9.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
-    "dotenv": "^17.2.3",
-    "drizzle-orm": "^0.44.6",
+    "dotenv": "^17.3.1",
+    "drizzle-orm": "^0.45.1",
     "fuse.js": "^7.1.0",
-    "jsonwebtoken": "^9.0.2",
-    "lucide-react": "^0.546.0",
+    "jsonwebtoken": "^9.0.3",
+    "lucide-react": "^0.575.0",
+    "nanoid": "^3.3.11",
     "next-themes": "^0.4.6",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "react-icons": "^5.5.0",
     "sonner": "^2.0.7",
-    "tailwind-merge": "^3.3.1",
-    "tailwindcss": "^4.1.15",
+    "tailwind-merge": "^3.5.0",
+    "tailwindcss": "^4.2.1",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.9.3",
     "uuid": "^13.0.0",
     "vaul": "^1.1.2",
-    "zod": "^4.1.12"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@playwright/test": "^1.58.2",
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.0",
+    "@testing-library/react": "^16.3.2",
     "@types/bcryptjs": "^3.0.0",
-    "@types/bun": "^1.3.0",
+    "@types/bun": "^1.3.9",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/uuid": "^10.0.0",
-    "@vitejs/plugin-react": "^5.0.4",
-    "drizzle-kit": "^0.31.5",
-    "jsdom": "^26.1.0",
-    "tsx": "^4.20.6",
-    "vitest": "^3.2.4"
+    "@types/node": "^25.3.2",
+    "@types/uuid": "^11.0.0",
+    "@vitejs/plugin-react": "^5.1.4",
+    "drizzle-kit": "^0.31.9",
+    "jsdom": "^28.1.0",
+    "tsx": "^4.21.0",
+    "vitest": "^4.0.18"
   },
-  "packageManager": "bun@1.3.0"
+  "packageManager": "bun@1.3.10"
 }

scripts/manage-db.ts

@@ -4,9 +4,9 @@ import { Database } from "bun:sqlite";
 import { drizzle } from "drizzle-orm/bun-sqlite";
 import { migrate } from "drizzle-orm/bun-sqlite/migrator";
 import { v4 as uuidv4 } from "uuid";
-import { users, configs, repositories, organizations, mirrorJobs, events } from "../src/lib/db/schema";
-import bcrypt from "bcryptjs";
-import { eq } from "drizzle-orm";
+import { users, configs, repositories, organizations, mirrorJobs, events, accounts, sessions } from "../src/lib/db/schema";
+import { and, eq } from "drizzle-orm";
+import { hashPassword } from "better-auth/crypto";
 
 // Command line arguments
 const args = process.argv.slice(2);
@@ -194,6 +194,92 @@ async function fixDatabase() {
   console.log("✅ Database location fixed");
 }
 
+/**
+ * Reset a single user's password (admin recovery flow)
+ */
+async function resetPassword() {
+  const emailArg = args.find((arg) => arg.startsWith("--email="));
+  const passwordArg = args.find((arg) => arg.startsWith("--new-password="));
+  const email = emailArg?.split("=")[1]?.trim().toLowerCase();
+  const newPassword = passwordArg?.split("=")[1];
+
+  if (!email || !newPassword) {
+    console.log("❌ Missing required arguments");
+    console.log("Usage:");
+    console.log("  bun run manage-db reset-password --email=user@example.com --new-password='new-secure-password'");
+    process.exit(1);
+  }
+
+  if (newPassword.length < 8) {
+    console.log("❌ Password must be at least 8 characters");
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(dbPath)) {
+    console.log("❌ Database does not exist");
+    process.exit(1);
+  }
+
+  const sqlite = new Database(dbPath);
+  const db = drizzle({ client: sqlite });
+
+  try {
+    const user = await db.query.users.findFirst({
+      where: eq(users.email, email),
+    });
+
+    if (!user) {
+      console.log(`❌ No user found for email: ${email}`);
+      sqlite.close();
+      process.exit(1);
+    }
+
+    const hashedPassword = await hashPassword(newPassword);
+    const now = new Date();
+
+    const credentialAccount = await db.query.accounts.findFirst({
+      where: and(
+        eq(accounts.userId, user.id),
+        eq(accounts.providerId, "credential"),
+      ),
+    });
+
+    if (credentialAccount) {
+      await db
+        .update(accounts)
+        .set({
+          password: hashedPassword,
+          updatedAt: now,
+        })
+        .where(eq(accounts.id, credentialAccount.id));
+    } else {
+      await db.insert(accounts).values({
+        id: uuidv4(),
+        accountId: user.id,
+        userId: user.id,
+        providerId: "credential",
+        password: hashedPassword,
+        createdAt: now,
+        updatedAt: now,
+      });
+    }
+
+    const deletedSessions = await db
+      .delete(sessions)
+      .where(eq(sessions.userId, user.id))
+      .returning({ id: sessions.id });
+
+    console.log(`✅ Password reset for ${email}`);
+    console.log(`🔒 Cleared ${deletedSessions.length} active session(s)`);
+
+    sqlite.close();
+  } catch (error) {
+    console.error("❌ Error resetting password:", error);
+    sqlite.close();
+    process.exit(1);
+  }
+}
+
 /**
  * Auto mode - check and initialize if needed
  */
@@ -224,6 +310,9 @@ switch (command) {
   case "cleanup":
     await cleanupDatabase();
     break;
+  case "reset-password":
+    await resetPassword();
+    break;
   case "auto":
     await autoMode();
     break;
@@ -233,7 +322,8 @@ switch (command) {
     console.log("  check        - Check database status");
     console.log("  fix          - Fix database location issues");
     console.log("  reset-users  - Remove all users and related data");
+    console.log("  reset-password - Reset one user's password and clear sessions");
     console.log("  cleanup      - Remove all database files");
     console.log("  auto         - Auto initialize if needed");
     process.exit(1);
-}
+}

scripts/setup-authentik-test.sh

@@ -114,10 +114,10 @@ EOF
         echo "======================================"
         echo "1. Access Authentik at http://localhost:9000"
         echo "2. Login with akadmin / admin-password"
-        echo "3. Create OAuth2 Provider for Gitea Mirror:"
+        echo "3. Create an Authentik OIDC Provider for Gitea Mirror:"
         echo "   - Name: gitea-mirror"
-        echo "   - Redirect URIs:"
-        echo "     http://localhost:4321/api/auth/callback/sso-provider"
+        echo "   - Redirect URI:"
+        echo "     http://localhost:4321/api/auth/sso/callback/authentik"
         echo "   - Scopes: openid, profile, email"
         echo ""
         echo "4. Create Application:"
@@ -131,10 +131,14 @@ EOF
         echo "6. Configure SSO in Gitea Mirror:"
         echo "   - Go to Settings → Authentication & SSO"
         echo "   - Add provider with:"
+        echo "     - Provider ID: authentik"
         echo "     - Issuer URL: http://localhost:9000/application/o/gitea-mirror/"
+        echo "     - Click Discover to pull Authentik endpoints"
         echo "     - Client ID: (from Authentik provider)"
         echo "     - Client Secret: (from Authentik provider)"
         echo ""
+        echo "If you previously registered this provider on a version earlier than v3.8.10, delete it and re-add it after upgrading to avoid missing endpoint data."
+        echo ""
         ;;
         
     stop)
@@ -177,4 +181,4 @@ EOF
         echo "  status - Show service status"
         exit 1
         ;;
-esac
+esac

src/components/config/AutomationSettings.tsx

@@ -9,6 +9,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
 import {
   Clock,
   Database,
@@ -16,7 +17,8 @@ import {
   Calendar,
   Activity,
   Zap,
-  Info
+  Info,
+  Archive,
 } from "lucide-react";
 import {
   Tooltip,
@@ -120,13 +122,13 @@ export function AutomationSettings({
         </CardTitle>
       </CardHeader>
       
-      <CardContent className="space-y-6">
-        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-          {/* Automatic Syncing Section */}
-          <div className="space-y-4 p-4 border border-border rounded-lg bg-card/50">
-            <div className="flex items-center justify-between">
-              <h3 className="text-sm font-medium flex items-center gap-2">
-                <RefreshCw className="h-4 w-4 text-primary" />
+  <CardContent className="space-y-6">
+    <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+      {/* Automatic Syncing Section */}
+      <div className="space-y-4 p-4 border border-border rounded-lg bg-card/50">
+        <div className="flex items-center justify-between">
+          <h3 className="text-sm font-medium flex items-center gap-2">
+            <RefreshCw className="h-4 w-4 text-primary" />
                 Automatic Syncing
               </h3>
               {isAutoSavingSchedule && (
@@ -139,6 +141,7 @@ export function AutomationSettings({
                 <Checkbox
                   id="enable-auto-mirror"
                   checked={scheduleConfig.enabled}
+                  className="mt-1.25"
                   onCheckedChange={(checked) =>
                     onScheduleChange({ ...scheduleConfig, enabled: !!checked })
                   }
@@ -218,17 +221,17 @@ export function AutomationSettings({
                     Enable automatic syncing to schedule periodic repository updates
                   </div>
                 )}
-              </div>
-            </div>
           </div>
+        </div>
+      </div>
 
-          {/* Database Cleanup Section */}
-          <div className="space-y-4 p-4 border border-border rounded-lg bg-card/50">
-            <div className="flex items-center justify-between">
-              <h3 className="text-sm font-medium flex items-center gap-2">
-                <Database className="h-4 w-4 text-primary" />
-                Database Maintenance
-              </h3>
+      {/* Database Cleanup Section */}
+      <div className="space-y-4 p-4 border border-border rounded-lg bg-card/50">
+        <div className="flex items-center justify-between">
+          <h3 className="text-sm font-medium flex items-center gap-2">
+            <Database className="h-4 w-4 text-primary" />
+            Database Maintenance
+          </h3>
               {isAutoSavingCleanup && (
                 <Activity className="h-4 w-4 animate-spin text-muted-foreground" />
               )}
@@ -239,6 +242,7 @@ export function AutomationSettings({
                 <Checkbox
                   id="enable-auto-cleanup"
                   checked={cleanupConfig.enabled}
+                  className="mt-1.25"
                   onCheckedChange={(checked) =>
                     onCleanupChange({ ...cleanupConfig, enabled: !!checked })
                   }
@@ -257,8 +261,8 @@ export function AutomationSettings({
               </div>
 
               {cleanupConfig.enabled && (
-                <div className="ml-6 space-y-3">
-                  <div>
+                <div className="ml-6 space-y-5">
+                  <div className="space-y-2">
                     <Label htmlFor="retention-period" className="text-sm flex items-center gap-2">
                       Data retention period
                       <TooltipProvider>
@@ -275,35 +279,36 @@ export function AutomationSettings({
                         </Tooltip>
                       </TooltipProvider>
                     </Label>
-                    <Select
-                      value={cleanupConfig.retentionDays.toString()}
-                      onValueChange={(value) =>
-                        onCleanupChange({
-                          ...cleanupConfig,
-                          retentionDays: parseInt(value, 10),
-                        })
-                      }
-                    >
-                      <SelectTrigger id="retention-period" className="mt-1.5">
-                        <SelectValue />
-                      </SelectTrigger>
-                      <SelectContent>
-                        {retentionPeriods.map((option) => (
-                          <SelectItem
-                            key={option.value}
-                            value={option.value.toString()}
-                          >
-                            {option.label}
-                          </SelectItem>
-                        ))}
-                      </SelectContent>
-                    </Select>
-                    {cleanupConfig.enabled && (
-                      <p className="text-xs text-muted-foreground mt-1">
+                    <div className="flex items-center gap-3 mt-1.5">
+                      <Select
+                        value={cleanupConfig.retentionDays.toString()}
+                        onValueChange={(value) =>
+                          onCleanupChange({
+                            ...cleanupConfig,
+                            retentionDays: parseInt(value, 10),
+                          })
+                        }
+                      >
+                        <SelectTrigger id="retention-period" className="w-40">
+                          <SelectValue />
+                        </SelectTrigger>
+                        <SelectContent>
+                          {retentionPeriods.map((option) => (
+                            <SelectItem
+                              key={option.value}
+                              value={option.value.toString()}
+                            >
+                              {option.label}
+                            </SelectItem>
+                          ))}
+                        </SelectContent>
+                      </Select>
+                      <p className="text-xs text-muted-foreground">
                         Cleanup runs {getCleanupFrequencyText(cleanupConfig.retentionDays)}
                       </p>
-                    )}
+                    </div>
                   </div>
+
                 </div>
               )}
 
@@ -334,13 +339,108 @@ export function AutomationSettings({
                 ) : (
                   <div className="text-xs text-muted-foreground">
                     Enable automatic cleanup to optimize database storage
-                  </div>
-                )}
               </div>
-            </div>
+            )}
           </div>
         </div>
-      </CardContent>
+      </div>
+
+      {/* Repository Cleanup Section */}
+      <div className="space-y-4 p-4 border border-border rounded-lg bg-card/50 md:col-span-2">
+        <div className="flex items-center justify-between">
+          <h3 className="text-sm font-medium flex items-center gap-2">
+            <Archive className="h-4 w-4 text-primary" />
+            Repository Cleanup (orphaned mirrors)
+          </h3>
+          {isAutoSavingCleanup && (
+            <Activity className="h-4 w-4 animate-spin text-muted-foreground" />
+          )}
+        </div>
+
+        <div className="space-y-4">
+          <div className="flex items-start space-x-3">
+            <Checkbox
+              id="cleanup-handle-orphans"
+              checked={Boolean(cleanupConfig.deleteIfNotInGitHub)}
+              className="mt-1.25"
+              onCheckedChange={(checked) =>
+                onCleanupChange({
+                  ...cleanupConfig,
+                  deleteIfNotInGitHub: Boolean(checked),
+                })
+              }
+            />
+            <div className="space-y-0.5 flex-1">
+              <Label
+                htmlFor="cleanup-handle-orphans"
+                className="text-sm font-normal cursor-pointer"
+              >
+                Handle orphaned repositories automatically
+              </Label>
+              <p className="text-xs text-muted-foreground">
+                Keep your Gitea backups when GitHub repos disappear. Archive is the safest option—it preserves data and disables automatic syncs.
+              </p>
+            </div>
+          </div>
+
+          {cleanupConfig.deleteIfNotInGitHub && (
+            <div className="space-y-3 ml-6">
+              <div className="space-y-1">
+                <Label htmlFor="cleanup-orphaned-action" className="text-sm font-medium">
+                  Action for orphaned repositories
+                </Label>
+                <Select
+                  value={cleanupConfig.orphanedRepoAction ?? "archive"}
+                  onValueChange={(value) =>
+                    onCleanupChange({
+                      ...cleanupConfig,
+                      orphanedRepoAction: value as DatabaseCleanupConfig["orphanedRepoAction"],
+                    })
+                  }
+                >
+                  <SelectTrigger id="cleanup-orphaned-action">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="archive">Archive (preserve data)</SelectItem>
+                    <SelectItem value="skip">Skip (leave as-is)</SelectItem>
+                    <SelectItem value="delete">Delete from Gitea</SelectItem>
+                  </SelectContent>
+                </Select>
+                <p className="text-xs text-muted-foreground">
+                  Archive renames mirror backups with an <code>archived-</code> prefix and disables automatic syncs—use Manual Sync when you want to refresh.
+                </p>
+              </div>
+
+              <div className="flex items-center justify-between">
+                <div className="space-y-0.5">
+                  <Label
+                    htmlFor="cleanup-dry-run"
+                    className="text-sm font-normal cursor-pointer"
+                  >
+                    Dry run (log only)
+                  </Label>
+                  <p className="text-xs text-muted-foreground max-w-xl">
+                    When enabled, cleanup logs the planned action without modifying repositories.
+                  </p>
+                </div>
+                <Switch
+                  id="cleanup-dry-run"
+                  checked={Boolean(cleanupConfig.dryRun)}
+                  onCheckedChange={(checked) =>
+                    onCleanupChange({
+                      ...cleanupConfig,
+                      dryRun: Boolean(checked),
+                    })
+                  }
+                />
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  </CardContent>
     </Card>
   );
-}
+}

src/components/config/ConfigTabs.tsx

@@ -42,12 +42,18 @@ export function ConfigTabs() {
     },
     giteaConfig: {
       url: '',
+      externalUrl: '',
       username: '',
       token: '',
       organization: 'github-mirrors',
       visibility: 'public',
       starredReposOrg: 'starred',
+      starredReposMode: 'dedicated-org',
       preserveOrgStructure: false,
+      backupStrategy: "on-force-push",
+      backupRetentionCount: 20,
+      backupDirectory: 'data/repo-backups',
+      blockSyncOnBackupFailure: true,
     },
     scheduleConfig: {
       enabled: false, // Don't set defaults here - will be loaded from API
@@ -56,6 +62,11 @@ export function ConfigTabs() {
     cleanupConfig: {
       enabled: false, // Don't set defaults here - will be loaded from API  
       retentionDays: 0, // Will be replaced with actual value from API
+      deleteIfNotInGitHub: true,
+      orphanedRepoAction: "archive",
+      dryRun: false,
+      deleteFromGitea: false,
+      protectedRepos: [],
     },
     mirrorOptions: {
       mirrorReleases: false,
@@ -72,6 +83,7 @@ export function ConfigTabs() {
     advancedOptions: {
       skipForks: false,
       starredCodeOnly: false,
+      autoMirrorStarred: false,
     },
   });
   const { user } = useAuth();
@@ -112,19 +124,31 @@ export function ConfigTabs() {
     if (!user?.id) return;
     setIsSyncing(true);
     try {
-      const result = await apiRequest<{ success: boolean; message?: string }>(
+      const result = await apiRequest<{ success: boolean; message?: string; failedOrgs?: string[]; recoveredOrgs?: number }>(
         `/sync?userId=${user.id}`,
         { method: 'POST' },
       );
-      result.success
-        ? toast.success(
-            'GitHub data imported successfully! Head to the Repositories page to start mirroring.',
-          )
-        : toast.error(
-            `Failed to import GitHub data: ${
-              result.message || 'Unknown error'
-            }`,
+      if (result.success) {
+        toast.success(
+          'GitHub data imported successfully! Head to the Repositories page to start mirroring.',
+        );
+        if (result.failedOrgs && result.failedOrgs.length > 0) {
+          toast.warning(
+            `${result.failedOrgs.length} org${result.failedOrgs.length > 1 ? 's' : ''} failed to import (${result.failedOrgs.join(', ')}). Check the Organizations tab for details.`,
           );
+        }
+        if (result.recoveredOrgs && result.recoveredOrgs > 0) {
+          toast.success(
+            `${result.recoveredOrgs} previously failed org${result.recoveredOrgs > 1 ? 's' : ''} recovered successfully.`,
+          );
+        }
+      } else {
+        toast.error(
+          `Failed to import GitHub data: ${
+            result.message || 'Unknown error'
+          }`,
+        );
+      }
     } catch (error) {
       toast.error(
         `Error importing GitHub data: ${
@@ -649,9 +673,20 @@ export function ConfigTabs() {
                       : update,
                 }))
               }
+              giteaConfig={config.giteaConfig}
+              setGiteaConfig={update =>
+                setConfig(prev => ({
+                  ...prev,
+                  giteaConfig:
+                    typeof update === 'function'
+                      ? update(prev.giteaConfig)
+                      : update,
+                }))
+              }
               onAutoSave={autoSaveGitHubConfig}
               onMirrorOptionsAutoSave={autoSaveMirrorOptions}
               onAdvancedOptionsAutoSave={autoSaveAdvancedOptions}
+              onGiteaAutoSave={autoSaveGiteaConfig}
               isAutoSaving={isAutoSavingGitHub}
             />
             <GiteaConfigForm

src/components/config/DatabaseCleanupConfigForm.tsx

@@ -1,201 +0,0 @@
-import { Card, CardContent } from "@/components/ui/card";
-import { Checkbox } from "../ui/checkbox";
-import type { DatabaseCleanupConfig } from "@/types/config";
-import { formatDate } from "@/lib/utils";
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from "../ui/select";
-import { RefreshCw, Database } from "lucide-react";
-
-interface DatabaseCleanupConfigFormProps {
-  config: DatabaseCleanupConfig;
-  setConfig: React.Dispatch<React.SetStateAction<DatabaseCleanupConfig>>;
-  onAutoSave?: (config: DatabaseCleanupConfig) => void;
-  isAutoSaving?: boolean;
-}
-
-
-// Helper to calculate cleanup interval in hours (should match backend logic)
-function calculateCleanupInterval(retentionSeconds: number): number {
-  const retentionDays = retentionSeconds / (24 * 60 * 60);
-  if (retentionDays <= 1) {
-    return 6;
-  } else if (retentionDays <= 3) {
-    return 12;
-  } else if (retentionDays <= 7) {
-    return 24;
-  } else if (retentionDays <= 30) {
-    return 48;
-  } else {
-    return 168;
-  }
-}
-
-export function DatabaseCleanupConfigForm({
-  config,
-  setConfig,
-  onAutoSave,
-  isAutoSaving = false,
-}: DatabaseCleanupConfigFormProps) {
-  // Optimistically update nextRun when enabled or retention changes
-  const handleChange = (
-    e: React.ChangeEvent<HTMLInputElement | HTMLSelectElement>
-  ) => {
-    const { name, value, type } = e.target;
-    let newConfig = {
-      ...config,
-      [name]: type === "checkbox" ? (e.target as HTMLInputElement).checked : value,
-    };
-
-    // If enabling or changing retention, recalculate nextRun
-    if (
-      (name === "enabled" && (e.target as HTMLInputElement).checked) ||
-      (name === "retentionDays" && config.enabled)
-    ) {
-      const now = new Date();
-      const retentionSeconds =
-        name === "retentionDays"
-          ? Number(value)
-          : Number(newConfig.retentionDays);
-      const intervalHours = calculateCleanupInterval(retentionSeconds);
-      const nextRun = new Date(now.getTime() + intervalHours * 60 * 60 * 1000);
-      newConfig = {
-        ...newConfig,
-        nextRun,
-      };
-    }
-    // If disabling, clear nextRun
-    if (name === "enabled" && !(e.target as HTMLInputElement).checked) {
-      newConfig = {
-        ...newConfig,
-        nextRun: undefined,
-      };
-    }
-
-    setConfig(newConfig);
-    if (onAutoSave) {
-      onAutoSave(newConfig);
-    }
-  };
-
-  // Predefined retention periods (in seconds, like schedule intervals)
-  const retentionOptions: { value: number; label: string }[] = [
-    { value: 86400, label: "1 day" },        // 24 * 60 * 60
-    { value: 259200, label: "3 days" },      // 3 * 24 * 60 * 60
-    { value: 604800, label: "7 days" },      // 7 * 24 * 60 * 60
-    { value: 1209600, label: "14 days" },    // 14 * 24 * 60 * 60
-    { value: 2592000, label: "30 days" },    // 30 * 24 * 60 * 60
-    { value: 5184000, label: "60 days" },    // 60 * 24 * 60 * 60
-    { value: 7776000, label: "90 days" },    // 90 * 24 * 60 * 60
-  ];
-
-  return (
-    <Card className="self-start">
-      <CardContent className="pt-6 relative">
-        {isAutoSaving && (
-          <div className="absolute top-4 right-4 flex items-center text-sm text-muted-foreground">
-            <RefreshCw className="h-3 w-3 animate-spin mr-1" />
-            <span className="text-xs">Auto-saving...</span>
-          </div>
-        )}
-        <div className="flex flex-col gap-y-4">
-          <div className="flex items-center">
-            <Checkbox
-              id="cleanup-enabled"
-              name="enabled"
-              checked={config.enabled}
-              onCheckedChange={(checked) =>
-                handleChange({
-                  target: {
-                    name: "enabled",
-                    type: "checkbox",
-                    checked: Boolean(checked),
-                    value: "",
-                  },
-                } as React.ChangeEvent<HTMLInputElement>)
-              }
-            />
-            <label
-              htmlFor="cleanup-enabled"
-              className="select-none ml-2 block text-sm font-medium"
-            >
-              <div className="flex items-center gap-2">
-                <Database className="h-4 w-4" />
-                Enable Automatic Database Cleanup
-              </div>
-            </label>
-          </div>
-
-          {config.enabled && (
-            <div>
-              <label className="block text-sm font-medium mb-2">
-                Data Retention Period
-              </label>
-
-              <Select
-                name="retentionDays"
-                value={String(config.retentionDays)}
-                onValueChange={(value) =>
-                  handleChange({
-                    target: { name: "retentionDays", value },
-                  } as React.ChangeEvent<HTMLInputElement>)
-                }
-              >
-                <SelectTrigger className="w-full border border-input dark:bg-background dark:hover:bg-background">
-                  <SelectValue placeholder="Select retention period" />
-                </SelectTrigger>
-                <SelectContent className="bg-background text-foreground border border-input shadow-sm">
-                  {retentionOptions.map((option) => (
-                    <SelectItem
-                      key={option.value}
-                      value={option.value.toString()}
-                      className="cursor-pointer text-sm px-3 py-2 hover:bg-accent focus:bg-accent focus:text-accent-foreground"
-                    >
-                      {option.label}
-                    </SelectItem>
-                  ))}
-                </SelectContent>
-              </Select>
-
-              <p className="text-xs text-muted-foreground mt-1">
-                Activities and events older than this period will be automatically deleted.
-              </p>
-              <div className="mt-2 p-2 bg-muted/50 rounded-md">
-                <p className="text-xs text-muted-foreground">
-                  <strong>Cleanup Frequency:</strong> The cleanup process runs automatically at optimal intervals:
-                  shorter retention periods trigger more frequent cleanups, longer periods trigger less frequent cleanups.
-                </p>
-              </div>
-            </div>
-          )}
-
-          <div className="flex gap-x-4">
-            <div className="flex-1">
-              <label className="block text-sm font-medium mb-1">Last Cleanup</label>
-              <div className="text-sm">
-                {config.lastRun ? formatDate(config.lastRun) : "Never"}
-              </div>
-            </div>
-
-            {config.enabled && (
-              <div className="flex-1">
-                <label className="block text-sm font-medium mb-1">Next Cleanup</label>
-                <div className="text-sm">
-                  {config.nextRun
-                    ? formatDate(config.nextRun)
-                    : config.enabled
-                      ? "Calculating..."
-                      : "Never"}
-                </div>
-              </div>
-            )}
-          </div>
-        </div>
-      </CardContent>
-    </Card>
-  );
-}

src/components/config/GitHubConfigForm.tsx

@@ -7,10 +7,11 @@ import {
   CardTitle,
 } from "@/components/ui/card";
 import { githubApi } from "@/lib/api";
-import type { GitHubConfig, MirrorOptions, AdvancedOptions } from "@/types/config";
+import type { GitHubConfig, MirrorOptions, AdvancedOptions, GiteaConfig, BackupStrategy } from "@/types/config";
 import { Input } from "../ui/input";
 import { toast } from "sonner";
-import { Info } from "lucide-react";
+import { Info, ShieldAlert } from "lucide-react";
+import { Badge } from "@/components/ui/badge";
 import { GitHubMirrorSettings } from "./GitHubMirrorSettings";
 import { Separator } from "../ui/separator";
 import {
@@ -26,23 +27,29 @@ interface GitHubConfigFormProps {
   setMirrorOptions: React.Dispatch<React.SetStateAction<MirrorOptions>>;
   advancedOptions: AdvancedOptions;
   setAdvancedOptions: React.Dispatch<React.SetStateAction<AdvancedOptions>>;
+  giteaConfig?: GiteaConfig;
+  setGiteaConfig?: React.Dispatch<React.SetStateAction<GiteaConfig>>;
   onAutoSave?: (githubConfig: GitHubConfig) => Promise<void>;
   onMirrorOptionsAutoSave?: (mirrorOptions: MirrorOptions) => Promise<void>;
   onAdvancedOptionsAutoSave?: (advancedOptions: AdvancedOptions) => Promise<void>;
+  onGiteaAutoSave?: (giteaConfig: GiteaConfig) => Promise<void>;
   isAutoSaving?: boolean;
 }
 
 export function GitHubConfigForm({ 
-  config, 
-  setConfig, 
+  config,
+  setConfig,
   mirrorOptions,
   setMirrorOptions,
   advancedOptions,
   setAdvancedOptions,
-  onAutoSave, 
+  giteaConfig,
+  setGiteaConfig,
+  onAutoSave,
   onMirrorOptionsAutoSave,
   onAdvancedOptionsAutoSave,
-  isAutoSaving 
+  onGiteaAutoSave,
+  isAutoSaving
 }: GitHubConfigFormProps) {
   const [isLoading, setIsLoading] = useState(false);
 
@@ -202,7 +209,139 @@ export function GitHubConfigForm({
             if (onAdvancedOptionsAutoSave) onAdvancedOptionsAutoSave(newOptions);
           }}
         />
-        
+
+        {giteaConfig && setGiteaConfig && (
+          <>
+            <Separator />
+
+            <div className="space-y-4">
+              <h3 className="text-sm font-medium flex items-center gap-2">
+                <ShieldAlert className="h-4 w-4 text-primary" />
+                Destructive Update Protection
+                <Badge variant="secondary" className="ml-2 text-[10px] px-1.5 py-0">BETA</Badge>
+              </h3>
+              <p className="text-xs text-muted-foreground">
+                Choose how to handle force-pushes or rewritten upstream history on GitHub.
+              </p>
+
+              <div className="grid grid-cols-2 md:grid-cols-4 gap-2">
+                {([
+                  {
+                    value: "disabled",
+                    label: "Disabled",
+                    desc: "No detection or backups",
+                  },
+                  {
+                    value: "always",
+                    label: "Always Backup",
+                    desc: "Snapshot before every sync",
+                  },
+                  {
+                    value: "on-force-push",
+                    label: "Smart",
+                    desc: "Backup only on force-push",
+                  },
+                  {
+                    value: "block-on-force-push",
+                    label: "Block & Approve",
+                    desc: "Require approval on force-push",
+                  },
+                ] as const).map((opt) => {
+                  const isSelected = (giteaConfig.backupStrategy ?? "on-force-push") === opt.value;
+                  return (
+                    <button
+                      key={opt.value}
+                      type="button"
+                      onClick={() => {
+                        const newConfig = { ...giteaConfig, backupStrategy: opt.value as BackupStrategy };
+                        setGiteaConfig(newConfig);
+                        if (onGiteaAutoSave) onGiteaAutoSave(newConfig);
+                      }}
+                      className={`flex flex-col items-start gap-1 rounded-lg border p-3 text-left text-sm transition-colors ${
+                        isSelected
+                          ? "border-primary bg-primary/5 ring-1 ring-primary"
+                          : "border-input hover:bg-accent hover:text-accent-foreground"
+                      }`}
+                    >
+                      <span className="font-medium">{opt.label}</span>
+                      <span className="text-xs text-muted-foreground">{opt.desc}</span>
+                    </button>
+                  );
+                })}
+              </div>
+
+              {(giteaConfig.backupStrategy ?? "on-force-push") !== "disabled" && (
+                <>
+                  <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+                    <div>
+                      <label htmlFor="backup-retention" className="block text-sm font-medium mb-1.5">
+                        Snapshot retention count
+                      </label>
+                      <input
+                        id="backup-retention"
+                        name="backupRetentionCount"
+                        type="number"
+                        min={1}
+                        value={giteaConfig.backupRetentionCount ?? 20}
+                        onChange={(e) => {
+                          const newConfig = {
+                            ...giteaConfig,
+                            backupRetentionCount: Math.max(1, Number.parseInt(e.target.value, 10) || 20),
+                          };
+                          setGiteaConfig(newConfig);
+                          if (onGiteaAutoSave) onGiteaAutoSave(newConfig);
+                        }}
+                        className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                      />
+                    </div>
+                    <div>
+                      <label htmlFor="backup-directory" className="block text-sm font-medium mb-1.5">
+                        Snapshot directory
+                      </label>
+                      <input
+                        id="backup-directory"
+                        name="backupDirectory"
+                        type="text"
+                        value={giteaConfig.backupDirectory || "data/repo-backups"}
+                        onChange={(e) => {
+                          const newConfig = { ...giteaConfig, backupDirectory: e.target.value };
+                          setGiteaConfig(newConfig);
+                          if (onGiteaAutoSave) onGiteaAutoSave(newConfig);
+                        }}
+                        className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                        placeholder="data/repo-backups"
+                      />
+                    </div>
+                  </div>
+
+                  {((giteaConfig.backupStrategy ?? "on-force-push") === "always" ||
+                    (giteaConfig.backupStrategy ?? "on-force-push") === "on-force-push") && (
+                    <label className="flex items-start gap-3 text-sm">
+                      <input
+                        name="blockSyncOnBackupFailure"
+                        type="checkbox"
+                        checked={Boolean(giteaConfig.blockSyncOnBackupFailure)}
+                        onChange={(e) => {
+                          const newConfig = { ...giteaConfig, blockSyncOnBackupFailure: e.target.checked };
+                          setGiteaConfig(newConfig);
+                          if (onGiteaAutoSave) onGiteaAutoSave(newConfig);
+                        }}
+                        className="mt-0.5 rounded border-input"
+                      />
+                      <span>
+                        Block sync when snapshot fails
+                        <p className="text-xs text-muted-foreground">
+                          Recommended for backup-first behavior. If disabled, sync continues even when snapshot creation fails.
+                        </p>
+                      </span>
+                    </label>
+                  )}
+                </>
+              )}
+            </div>
+          </>
+        )}
+
         {/* Mobile: Show button at bottom */}
         <Button
           type="button"

src/components/config/GitHubMirrorSettings.tsx

@@ -287,6 +287,31 @@ export function GitHubMirrorSettings({
             </div>
           </div>
 
+          {/* Auto-mirror starred repos toggle */}
+          {githubConfig.mirrorStarred && (
+            <div className="mt-4">
+              <div className="flex items-start space-x-3">
+                <Checkbox
+                  id="auto-mirror-starred"
+                  checked={advancedOptions.autoMirrorStarred ?? false}
+                  onCheckedChange={(checked) => handleAdvancedChange('autoMirrorStarred', !!checked)}
+                />
+                <div className="space-y-0.5 flex-1">
+                  <Label
+                    htmlFor="auto-mirror-starred"
+                    className="text-sm font-normal cursor-pointer flex items-center gap-2"
+                  >
+                    <Star className="h-3.5 w-3.5" />
+                    Auto-mirror new starred repositories
+                  </Label>
+                  <p className="text-xs text-muted-foreground">
+                    When disabled, starred repos are imported for browsing but not automatically mirrored. You can still mirror individual repos manually.
+                  </p>
+                </div>
+              </div>
+            </div>
+          )}
+
           {/* Duplicate name handling for starred repos */}
           {githubConfig.mirrorStarred && (
             <div className="mt-4 space-y-2">
@@ -377,14 +402,13 @@ export function GitHubMirrorSettings({
                       id="release-limit"
                       type="number"
                       min="1"
-                      max="100"
                       value={mirrorOptions.releaseLimit || 10}
                       onChange={(e) => {
                         const value = parseInt(e.target.value) || 10;
-                        const clampedValue = Math.min(100, Math.max(1, value));
+                        const clampedValue = Math.max(1, value);
                         handleMirrorChange('releaseLimit', clampedValue);
                       }}
-                      className="w-16 px-2 py-1 text-xs border border-input rounded bg-background text-foreground"
+                      className="w-20 px-2 py-1 text-xs border border-input rounded bg-background text-foreground"
                     />
                     <span className="text-xs text-muted-foreground">releases</span>
                   </div>

src/components/config/GiteaConfigForm.tsx

@@ -100,9 +100,14 @@ export function GiteaConfigForm({ config, setConfig, onAutoSave, isAutoSaving, g
       );
     }
 
+    const normalizedValue =
+      type === "checkbox"
+        ? checked
+        : value;
+
     const newConfig = {
       ...config,
-      [name]: type === "checkbox" ? checked : value,
+      [name]: normalizedValue,
     };
     setConfig(newConfig);
 
@@ -195,6 +200,27 @@ export function GiteaConfigForm({ config, setConfig, onAutoSave, isAutoSaving, g
           />
         </div>
 
+        <div>
+          <label
+            htmlFor="gitea-external-url"
+            className="block text-sm font-medium mb-1.5"
+          >
+            Gitea External URL (optional)
+          </label>
+          <input
+            id="gitea-external-url"
+            name="externalUrl"
+            type="url"
+            value={config.externalUrl || ""}
+            onChange={handleChange}
+            className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+            placeholder="https://gitea.example.com"
+          />
+          <p className="text-xs text-muted-foreground mt-1">
+            Used only for dashboard links. API sync still uses Gitea URL.
+          </p>
+        </div>
+
         <div>
           <label
             htmlFor="gitea-token"
@@ -224,6 +250,7 @@ export function GiteaConfigForm({ config, setConfig, onAutoSave, isAutoSaving, g
           strategy={mirrorStrategy}
           destinationOrg={config.organization}
           starredReposOrg={config.starredReposOrg}
+          starredReposMode={config.starredReposMode}
           onStrategyChange={setMirrorStrategy}
           githubUsername={githubUsername}
           giteaUsername={config.username}
@@ -235,6 +262,7 @@ export function GiteaConfigForm({ config, setConfig, onAutoSave, isAutoSaving, g
           strategy={mirrorStrategy}
           destinationOrg={config.organization}
           starredReposOrg={config.starredReposOrg}
+          starredReposMode={config.starredReposMode}
           personalReposOrg={config.personalReposOrg}
           visibility={config.visibility}
           onDestinationOrgChange={(org) => {
@@ -247,6 +275,11 @@ export function GiteaConfigForm({ config, setConfig, onAutoSave, isAutoSaving, g
             setConfig(newConfig);
             if (onAutoSave) onAutoSave(newConfig);
           }}
+          onStarredReposModeChange={(mode) => {
+            const newConfig = { ...config, starredReposMode: mode };
+            setConfig(newConfig);
+            if (onAutoSave) onAutoSave(newConfig);
+          }}
           onPersonalReposOrgChange={(org) => {
             const newConfig = { ...config, personalReposOrg: org };
             setConfig(newConfig);
@@ -258,7 +291,7 @@ export function GiteaConfigForm({ config, setConfig, onAutoSave, isAutoSaving, g
             if (onAutoSave) onAutoSave(newConfig);
           }}
         />
-        
+
         {/* Mobile: Show button at bottom */}
         <Button
           type="button"

src/components/config/OrganizationConfiguration.tsx

@@ -9,16 +9,18 @@ import {
   TooltipTrigger,
 } from "@/components/ui/tooltip";
 import { cn } from "@/lib/utils";
-import type { MirrorStrategy, GiteaOrgVisibility } from "@/types/config";
+import type { MirrorStrategy, GiteaOrgVisibility, StarredReposMode } from "@/types/config";
 
 interface OrganizationConfigurationProps {
   strategy: MirrorStrategy;
   destinationOrg?: string;
   starredReposOrg?: string;
+  starredReposMode?: StarredReposMode;
   personalReposOrg?: string;
   visibility: GiteaOrgVisibility;
   onDestinationOrgChange: (org: string) => void;
   onStarredReposOrgChange: (org: string) => void;
+  onStarredReposModeChange: (mode: StarredReposMode) => void;
   onPersonalReposOrgChange: (org: string) => void;
   onVisibilityChange: (visibility: GiteaOrgVisibility) => void;
 }
@@ -33,13 +35,19 @@ export const OrganizationConfiguration: React.FC<OrganizationConfigurationProps>
   strategy,
   destinationOrg,
   starredReposOrg,
+  starredReposMode,
   personalReposOrg,
   visibility,
   onDestinationOrgChange,
   onStarredReposOrgChange,
+  onStarredReposModeChange,
   onPersonalReposOrgChange,
   onVisibilityChange,
 }) => {
+  const activeStarredMode = starredReposMode || "dedicated-org";
+  const showStarredReposOrgInput = activeStarredMode === "dedicated-org";
+  const showDestinationOrgInput = strategy === "single-org" || strategy === "mixed";
+
   return (
     <div className="space-y-4">
       <div>
@@ -49,38 +57,94 @@ export const OrganizationConfiguration: React.FC<OrganizationConfigurationProps>
         </h4>
       </div>
 
-      {/* First row - Organization inputs with consistent layout */}
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-        {/* Left column - always shows starred repos org */}
-        <div className="space-y-1">
-          <Label htmlFor="starredReposOrg" className="text-sm font-normal flex items-center gap-2">
-            <Star className="h-3.5 w-3.5" />
-            Starred Repos Organization
-            <TooltipProvider>
-              <Tooltip>
-                <TooltipTrigger>
-                  <Info className="h-3.5 w-3.5 text-muted-foreground" />
-                </TooltipTrigger>
-                <TooltipContent>
-                  <p>Starred repositories will be organized separately in this organization</p>
-                </TooltipContent>
-              </Tooltip>
-            </TooltipProvider>
-          </Label>
-          <Input
-            id="starredReposOrg"
-            value={starredReposOrg || ""}
-            onChange={(e) => onStarredReposOrgChange(e.target.value)}
-            placeholder="starred"
-            className=""
-          />
-          <p className="text-xs text-muted-foreground mt-1">
-            Keep starred repos organized separately
+      <div className="space-y-2">
+        <Label className="text-sm font-normal flex items-center gap-2">
+          Starred Repository Destination
+          <TooltipProvider>
+            <Tooltip>
+              <TooltipTrigger>
+                <Info className="h-3.5 w-3.5 text-muted-foreground" />
+              </TooltipTrigger>
+              <TooltipContent>
+                <p>Choose whether starred repos use one org or keep their source Owner/Org paths</p>
+              </TooltipContent>
+            </Tooltip>
+          </TooltipProvider>
+        </Label>
+        <div className="rounded-lg border bg-muted/20 p-2">
+          <div className="grid grid-cols-1 sm:grid-cols-2 gap-2">
+            <button
+              type="button"
+              onClick={() => onStarredReposModeChange("dedicated-org")}
+              aria-pressed={activeStarredMode === "dedicated-org"}
+              className={cn(
+                "text-left px-3 py-2 rounded-md border text-sm transition-all",
+                activeStarredMode === "dedicated-org"
+                  ? "bg-accent border-accent-foreground/30 ring-1 ring-accent-foreground/20 font-medium shadow-sm"
+                  : "bg-background hover:bg-accent/50 border-input"
+              )}
+            >
+              Dedicated Organization
+            </button>
+            <button
+              type="button"
+              onClick={() => onStarredReposModeChange("preserve-owner")}
+              aria-pressed={activeStarredMode === "preserve-owner"}
+              className={cn(
+                "text-left px-3 py-2 rounded-md border text-sm transition-all",
+                activeStarredMode === "preserve-owner"
+                  ? "bg-accent border-accent-foreground/30 ring-1 ring-accent-foreground/20 font-medium shadow-sm"
+                  : "bg-background hover:bg-accent/50 border-input"
+              )}
+            >
+              Preserve Source Owner/Org
+            </button>
+          </div>
+          <p className="mt-2 px-1 text-xs text-muted-foreground">
+            {
+              activeStarredMode === "dedicated-org"
+                ? "All starred repositories go to a single destination organization."
+                : "Starred repositories keep their original GitHub Owner/Org destination."
+            }
           </p>
         </div>
+      </div>
 
-        {/* Right column - shows destination org for single-org/mixed, personal repos org for preserve, empty div for others */}
-        {strategy === "single-org" || strategy === "mixed" ? (
+      {/* First row - Organization inputs */}
+      {(showStarredReposOrgInput || showDestinationOrgInput) && (
+        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+          {showStarredReposOrgInput ? (
+            <div className="space-y-1">
+              <Label htmlFor="starredReposOrg" className="text-sm font-normal flex items-center gap-2">
+                <Star className="h-3.5 w-3.5" />
+                Starred Repos Organization
+                <TooltipProvider>
+                  <Tooltip>
+                    <TooltipTrigger>
+                      <Info className="h-3.5 w-3.5 text-muted-foreground" />
+                    </TooltipTrigger>
+                    <TooltipContent>
+                      <p>Starred repositories will be organized separately in this organization</p>
+                    </TooltipContent>
+                  </Tooltip>
+                </TooltipProvider>
+              </Label>
+              <Input
+                id="starredReposOrg"
+                value={starredReposOrg || ""}
+                onChange={(e) => onStarredReposOrgChange(e.target.value)}
+                placeholder="starred"
+                className=""
+              />
+              <p className="text-xs text-muted-foreground mt-1">
+                Keep starred repos organized separately
+              </p>
+            </div>
+          ) : (
+            <div className="hidden md:block" />
+          )}
+
+          {showDestinationOrgInput ? (
           <div className="space-y-1">
             <Label htmlFor="destinationOrg" className="text-sm font-normal flex items-center gap-2">
               {strategy === "mixed" ? "Personal Repos Organization" : "Destination Organization"}
@@ -114,10 +178,11 @@ export const OrganizationConfiguration: React.FC<OrganizationConfigurationProps>
               }
             </p>
           </div>
-        ) : (
-          <div className="hidden md:block" />
-        )}
-      </div>
+          ) : (
+            <div className="hidden md:block" />
+          )}
+        </div>
+      )}
 
       {/* Second row - Organization Visibility (always shown) */}
       <div className="space-y-2">
@@ -172,4 +237,3 @@ export const OrganizationConfiguration: React.FC<OrganizationConfigurationProps>
     </div>
   );
 };
-

src/components/config/OrganizationStrategy.tsx

@@ -8,6 +8,7 @@ import {
   HoverCardTrigger,
 } from "@/components/ui/hover-card";
 import { cn } from "@/lib/utils";
+import type { StarredReposMode } from "@/types/config";
 
 export type MirrorStrategy = "preserve" | "single-org" | "flat-user" | "mixed";
 
@@ -15,6 +16,7 @@ interface OrganizationStrategyProps {
   strategy: MirrorStrategy;
   destinationOrg?: string;
   starredReposOrg?: string;
+  starredReposMode?: StarredReposMode;
   onStrategyChange: (strategy: MirrorStrategy) => void;
   githubUsername?: string;
   giteaUsername?: string;
@@ -76,13 +78,18 @@ const MappingPreview: React.FC<{
   config: typeof strategyConfig.preserve;
   destinationOrg?: string;
   starredReposOrg?: string;
+  starredReposMode?: StarredReposMode;
   githubUsername?: string;
   giteaUsername?: string;
-}> = ({ strategy, config, destinationOrg, starredReposOrg, githubUsername, giteaUsername }) => {
+}> = ({ strategy, config, destinationOrg, starredReposOrg, starredReposMode, githubUsername, giteaUsername }) => {
   const displayGithubUsername = githubUsername || "<username>";
   const displayGiteaUsername = giteaUsername || "<username>";
   const isGithubPlaceholder = !githubUsername;
   const isGiteaPlaceholder = !giteaUsername;
+  const starredDestination =
+    (starredReposMode || "dedicated-org") === "preserve-owner"
+      ? "awesome/starred-repo"
+      : `${starredReposOrg || "starred"}/starred-repo`;
   
   if (strategy === "preserve") {
     return (
@@ -122,7 +129,7 @@ const MappingPreview: React.FC<{
             </div>
             <div className={cn("flex items-center gap-2 p-1.5 rounded text-xs", config.repoColors.bg)}>
               <Building2 className={cn("h-3 w-3", config.repoColors.icon)} />
-              <span>{starredReposOrg || "starred"}/starred-repo</span>
+              <span>{starredDestination}</span>
             </div>
           </div>
         </div>
@@ -168,7 +175,7 @@ const MappingPreview: React.FC<{
             </div>
             <div className={cn("flex items-center gap-2 p-1.5 rounded text-xs", config.repoColors.bg)}>
               <Building2 className={cn("h-3 w-3", config.repoColors.icon)} />
-              <span>{starredReposOrg || "starred"}/starred-repo</span>
+              <span>{starredDestination}</span>
             </div>
           </div>
         </div>
@@ -214,7 +221,7 @@ const MappingPreview: React.FC<{
             </div>
             <div className={cn("flex items-center gap-2 p-1.5 rounded text-xs", config.repoColors.bg)}>
               <Building2 className={cn("h-3 w-3", config.repoColors.icon)} />
-              <span>{starredReposOrg || "starred"}/starred-repo</span>
+              <span>{starredDestination}</span>
             </div>
           </div>
         </div>
@@ -260,7 +267,7 @@ const MappingPreview: React.FC<{
             </div>
             <div className={cn("flex items-center gap-2 p-1.5 rounded text-xs", config.repoColors.bg)}>
               <Building2 className={cn("h-3 w-3", config.repoColors.icon)} />
-              <span>{starredReposOrg || "starred"}/starred-repo</span>
+              <span>{starredDestination}</span>
             </div>
           </div>
         </div>
@@ -275,6 +282,7 @@ export const OrganizationStrategy: React.FC<OrganizationStrategyProps> = ({
   strategy,
   destinationOrg,
   starredReposOrg,
+  starredReposMode,
   onStrategyChange,
   githubUsername,
   giteaUsername,
@@ -339,7 +347,7 @@ export const OrganizationStrategy: React.FC<OrganizationStrategyProps> = ({
                       <span className="text-xs font-medium">Starred Repositories</span>
                     </div>
                     <p className="text-xs text-muted-foreground pl-5">
-                      Always go to the configured starred repos organization and cannot be overridden.
+                      Follow your starred-repo mode and cannot be overridden per repository.
                     </p>
                   </div>
                 </div>
@@ -415,6 +423,7 @@ export const OrganizationStrategy: React.FC<OrganizationStrategyProps> = ({
                                     config={config}
                                     destinationOrg={destinationOrg}
                                     starredReposOrg={starredReposOrg}
+                                    starredReposMode={starredReposMode}
                                     githubUsername={githubUsername}
                                     giteaUsername={giteaUsername}
                                   />
@@ -434,4 +443,4 @@ export const OrganizationStrategy: React.FC<OrganizationStrategyProps> = ({
       </RadioGroup>
     </div>
   );
-};
+};

src/components/config/ScheduleAndCleanupForm.tsx

@@ -1,47 +0,0 @@
-import React from 'react';
-import { ScheduleConfigForm } from './ScheduleConfigForm';
-import { DatabaseCleanupConfigForm } from './DatabaseCleanupConfigForm';
-import { Separator } from '../ui/separator';
-import type { ScheduleConfig, DatabaseCleanupConfig } from '@/types/config';
-
-interface ScheduleAndCleanupFormProps {
-  scheduleConfig: ScheduleConfig;
-  cleanupConfig: DatabaseCleanupConfig;
-  setScheduleConfig: (update: ScheduleConfig | ((prev: ScheduleConfig) => ScheduleConfig)) => void;
-  setCleanupConfig: (update: DatabaseCleanupConfig | ((prev: DatabaseCleanupConfig) => DatabaseCleanupConfig)) => void;
-  onAutoSaveSchedule?: (config: ScheduleConfig) => Promise<void>;
-  onAutoSaveCleanup?: (config: DatabaseCleanupConfig) => Promise<void>;
-  isAutoSavingSchedule?: boolean;
-  isAutoSavingCleanup?: boolean;
-}
-
-export function ScheduleAndCleanupForm({
-  scheduleConfig,
-  cleanupConfig,
-  setScheduleConfig,
-  setCleanupConfig,
-  onAutoSaveSchedule,
-  onAutoSaveCleanup,
-  isAutoSavingSchedule,
-  isAutoSavingCleanup,
-}: ScheduleAndCleanupFormProps) {
-  return (
-    <div className="space-y-6">
-      <ScheduleConfigForm
-        config={scheduleConfig}
-        setConfig={setScheduleConfig}
-        onAutoSave={onAutoSaveSchedule}
-        isAutoSaving={isAutoSavingSchedule}
-      />
-      
-      <Separator />
-      
-      <DatabaseCleanupConfigForm
-        config={cleanupConfig}
-        setConfig={setCleanupConfig}
-        onAutoSave={onAutoSaveCleanup}
-        isAutoSaving={isAutoSavingCleanup}
-      />
-    </div>
-  );
-}

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/components/dashboard/RepositoryList.tsx

@@ -15,7 +15,8 @@ export function RepositoryList({ repositories }: RepositoryListProps) {
 
   // Helper function to construct Gitea repository URL
   const getGiteaRepoUrl = (repository: Repository): string | null => {
-    if (!giteaConfig?.url) {
+    const rawBaseUrl = giteaConfig?.externalUrl || giteaConfig?.url;
+    if (!rawBaseUrl) {
       return null;
     }
 
@@ -38,9 +39,9 @@ export function RepositoryList({ repositories }: RepositoryListProps) {
     }
 
     // Ensure the base URL doesn't have a trailing slash
-    const baseUrl = giteaConfig.url.endsWith('/')
-      ? giteaConfig.url.slice(0, -1)
-      : giteaConfig.url;
+    const baseUrl = rawBaseUrl.endsWith("/")
+      ? rawBaseUrl.slice(0, -1)
+      : rawBaseUrl;
 
     return `${baseUrl}/${repoPath}`;
   };

src/components/layout/MainLayout.tsx

@@ -159,7 +159,7 @@ function AppWithProviders({ page: initialPage }: AppProps) {
             {currentPage === "activity-log" && <ActivityLog />}
           </section>
         </div>
-        <Toaster />
+        <Toaster position="top-center" />
       </main>
     </NavigationContext.Provider>
   );

src/components/organizations/AddOrganizationDialog.tsx

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { Button } from "@/components/ui/button";
 import {
   Dialog,
@@ -20,9 +20,11 @@ interface AddOrganizationDialogProps {
   onAddOrganization: ({
     org,
     role,
+    force,
   }: {
     org: string;
     role: MembershipRole;
+    force?: boolean;
   }) => Promise<void>;
 }
 
@@ -36,6 +38,14 @@ export default function AddOrganizationDialog({
   const [isLoading, setIsLoading] = useState<boolean>(false);
   const [error, setError] = useState<string>("");
 
+  useEffect(() => {
+    if (!isDialogOpen) {
+      setError("");
+      setOrg("");
+      setRole("member");
+    }
+  }, [isDialogOpen]);
+
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
 
@@ -54,7 +64,7 @@ export default function AddOrganizationDialog({
       setRole("member");
       setIsDialogOpen(false);
     } catch (err: any) {
-      setError(err?.message || "Failed to add repository.");
+      setError(err?.message || "Failed to add organization.");
     } finally {
       setIsLoading(false);
     }
@@ -139,7 +149,7 @@ export default function AddOrganizationDialog({
               {isLoading ? (
                 <LoaderCircle className="h-4 w-4 animate-spin" />
               ) : (
-                "Add Repository"
+                "Add Organization"
               )}
             </Button>
           </div>

src/components/organizations/Organization.tsx

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useState } from "react";
 import { Button } from "@/components/ui/button";
-import { Search, RefreshCw, FlipHorizontal, Filter } from "lucide-react";
+import { Search, RefreshCw, FlipHorizontal, Filter, LoaderCircle, Trash2 } from "lucide-react";
 import type { MirrorJob, Organization } from "@/lib/db/schema";
 import { OrganizationList } from "./OrganizationsList";
 import AddOrganizationDialog from "./AddOrganizationDialog";
@@ -37,6 +37,14 @@ import {
   DrawerTitle,
   DrawerTrigger,
 } from "@/components/ui/drawer";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
 
 export function Organization() {
   const [organizations, setOrganizations] = useState<Organization[]>([]);
@@ -52,6 +60,15 @@ export function Organization() {
     status: "",
   });
   const [loadingOrgIds, setLoadingOrgIds] = useState<Set<string>>(new Set()); // this is used when the api actions are performed
+  const [duplicateOrgCandidate, setDuplicateOrgCandidate] = useState<{
+    org: string;
+    role: MembershipRole;
+  } | null>(null);
+  const [isDuplicateOrgDialogOpen, setIsDuplicateOrgDialogOpen] = useState(false);
+  const [isProcessingDuplicateOrg, setIsProcessingDuplicateOrg] = useState(false);
+  const [orgToDelete, setOrgToDelete] = useState<Organization | null>(null);
+  const [isDeleteOrgDialogOpen, setIsDeleteOrgDialogOpen] = useState(false);
+  const [isDeletingOrg, setIsDeletingOrg] = useState(false);
 
   // Create a stable callback using useCallback
   const handleNewMessage = useCallback((data: MirrorJob) => {
@@ -256,19 +273,45 @@ export function Organization() {
   const handleAddOrganization = async ({
     org,
     role,
+    force = false,
   }: {
     org: string;
     role: MembershipRole;
+    force?: boolean;
   }) => {
-    try {
-      if (!user || !user.id) {
-        return;
+    if (!user || !user.id) {
+      return;
+    }
+
+    const trimmedOrg = org.trim();
+    const normalizedOrg = trimmedOrg.toLowerCase();
+
+    if (!trimmedOrg) {
+      toast.error("Please enter a valid organization name.");
+      throw new Error("Invalid organization name");
+    }
+
+    if (!force) {
+      const alreadyExists = organizations.some(
+        (existing) => existing.name?.trim().toLowerCase() === normalizedOrg
+      );
+
+      if (alreadyExists) {
+        toast.warning("Organization already exists.");
+        setDuplicateOrgCandidate({ org: trimmedOrg, role });
+        setIsDuplicateOrgDialogOpen(true);
+        throw new Error("Organization already exists");
       }
+    }
+
+    try {
+      setIsLoading(true);
 
       const reqPayload: AddOrganizationApiRequest = {
         userId: user.id,
-        org,
+        org: trimmedOrg,
         role,
+        force,
       };
 
       const response = await apiRequest<AddOrganizationApiResponse>(
@@ -280,25 +323,100 @@ export function Organization() {
       );
 
       if (response.success) {
-        toast.success(`Organization added successfully`);
-        setOrganizations((prev) => [...prev, response.organization]);
+        const message = force
+          ? "Organization already exists; using existing entry."
+          : "Organization added successfully";
+        toast.success(message);
 
-        await fetchOrganizations();
+        await fetchOrganizations(false);
 
         setFilter((prev) => ({
           ...prev,
-          searchTerm: org,
+          searchTerm: trimmedOrg,
         }));
+
+        if (force) {
+          setIsDuplicateOrgDialogOpen(false);
+          setDuplicateOrgCandidate(null);
+        }
       } else {
         showErrorToast(response.error || "Error adding organization", toast);
       }
     } catch (error) {
       showErrorToast(error, toast);
+      throw error;
     } finally {
       setIsLoading(false);
     }
   };
 
+  const handleConfirmDuplicateOrganization = async () => {
+    if (!duplicateOrgCandidate) {
+      return;
+    }
+
+    setIsProcessingDuplicateOrg(true);
+    try {
+      await handleAddOrganization({
+        org: duplicateOrgCandidate.org,
+        role: duplicateOrgCandidate.role,
+        force: true,
+      });
+      setIsDialogOpen(false);
+      setDuplicateOrgCandidate(null);
+      setIsDuplicateOrgDialogOpen(false);
+    } catch (error) {
+      // Error already surfaced via toast
+    } finally {
+      setIsProcessingDuplicateOrg(false);
+    }
+  };
+
+  const handleCancelDuplicateOrganization = () => {
+    setIsDuplicateOrgDialogOpen(false);
+    setDuplicateOrgCandidate(null);
+  };
+
+  const handleRequestDeleteOrganization = (orgId: string) => {
+    const org = organizations.find((item) => item.id === orgId);
+    if (!org) {
+      toast.error("Organization not found");
+      return;
+    }
+
+    setOrgToDelete(org);
+    setIsDeleteOrgDialogOpen(true);
+  };
+
+  const handleDeleteOrganization = async () => {
+    if (!user || !user.id || !orgToDelete) {
+      return;
+    }
+
+    setIsDeletingOrg(true);
+    try {
+      const response = await apiRequest<{ success: boolean; error?: string }>(
+        `/organizations/${orgToDelete.id}`,
+        {
+          method: "DELETE",
+        }
+      );
+
+      if (response.success) {
+        toast.success(`Removed ${orgToDelete.name} from Gitea Mirror.`);
+        await fetchOrganizations(false);
+      } else {
+        showErrorToast(response.error || "Failed to delete organization", toast);
+      }
+    } catch (error) {
+      showErrorToast(error, toast);
+    } finally {
+      setIsDeletingOrg(false);
+      setIsDeleteOrgDialogOpen(false);
+      setOrgToDelete(null);
+    }
+  };
+
   const handleMirrorAllOrgs = async () => {
     try {
       if (!user || !user.id || organizations.length === 0) {
@@ -711,6 +829,7 @@ export function Organization() {
         onMirror={handleMirrorOrg}
         onIgnore={handleIgnoreOrg}
         onAddOrganization={() => setIsDialogOpen(true)}
+        onDelete={handleRequestDeleteOrganization}
         onRefresh={async () => {
           await fetchOrganizations(false);
         }}
@@ -721,6 +840,68 @@ export function Organization() {
         isDialogOpen={isDialogOpen}
         setIsDialogOpen={setIsDialogOpen}
       />
+
+      <Dialog open={isDuplicateOrgDialogOpen} onOpenChange={(open) => {
+        if (!open) {
+          handleCancelDuplicateOrganization();
+        }
+      }}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Organization already exists</DialogTitle>
+            <DialogDescription>
+              {duplicateOrgCandidate?.org ?? "This organization"} is already synced in Gitea Mirror.
+              Continuing will reuse the existing entry without creating a duplicate. You can remove it later if needed.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button variant="outline" onClick={handleCancelDuplicateOrganization} disabled={isProcessingDuplicateOrg}>
+              Cancel
+            </Button>
+            <Button onClick={handleConfirmDuplicateOrganization} disabled={isProcessingDuplicateOrg}>
+              {isProcessingDuplicateOrg ? (
+                <LoaderCircle className="h-4 w-4 animate-spin" />
+              ) : (
+                "Continue"
+              )}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      <Dialog open={isDeleteOrgDialogOpen} onOpenChange={(open) => {
+        if (!open) {
+          setIsDeleteOrgDialogOpen(false);
+          setOrgToDelete(null);
+        }
+      }}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Remove organization from Gitea Mirror?</DialogTitle>
+            <DialogDescription>
+              {orgToDelete?.name ?? "This organization"} will be deleted from Gitea Mirror only. Nothing will be removed from Gitea; you will need to clean it up manually in Gitea if desired.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => {
+              setIsDeleteOrgDialogOpen(false);
+              setOrgToDelete(null);
+            }} disabled={isDeletingOrg}>
+              Cancel
+            </Button>
+            <Button variant="destructive" onClick={handleDeleteOrganization} disabled={isDeletingOrg}>
+              {isDeletingOrg ? (
+                <LoaderCircle className="h-4 w-4 animate-spin" />
+              ) : (
+                <span className="flex items-center gap-2">
+                  <Trash2 className="h-4 w-4" />
+                  Delete
+                </span>
+              )}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
     </div>
   );
 }

src/components/organizations/OrganizationsList.tsx

@@ -2,7 +2,7 @@ import { useMemo } from "react";
 import { Card } from "@/components/ui/card";
 import { Button } from "@/components/ui/button";
 import { Badge } from "@/components/ui/badge";
-import { Plus, RefreshCw, Building2, Check, AlertCircle, Clock, MoreVertical, Ban } from "lucide-react";
+import { Plus, RefreshCw, Building2, Check, AlertCircle, Clock, MoreVertical, Ban, Trash2 } from "lucide-react";
 import { SiGithub, SiGitea } from "react-icons/si";
 import type { Organization } from "@/lib/db/schema";
 import type { FilterParams } from "@/types/filter";
@@ -30,6 +30,7 @@ interface OrganizationListProps {
   loadingOrgIds: Set<string>;
   onAddOrganization?: () => void;
   onRefresh?: () => Promise<void>;
+  onDelete?: (orgId: string) => void;
 }
 
 // Helper function to get status badge variant and icon
@@ -60,12 +61,14 @@ export function OrganizationList({
   loadingOrgIds,
   onAddOrganization,
   onRefresh,
+  onDelete,
 }: OrganizationListProps) {
   const { giteaConfig } = useGiteaConfig();
 
   // Helper function to construct Gitea organization URL
   const getGiteaOrgUrl = (organization: Organization): string | null => {
-    if (!giteaConfig?.url) {
+    const rawBaseUrl = giteaConfig?.externalUrl || giteaConfig?.url;
+    if (!rawBaseUrl) {
       return null;
     }
 
@@ -82,9 +85,9 @@ export function OrganizationList({
     }
 
     // Ensure the base URL doesn't have a trailing slash
-    const baseUrl = giteaConfig.url.endsWith('/')
-      ? giteaConfig.url.slice(0, -1)
-      : giteaConfig.url;
+    const baseUrl = rawBaseUrl.endsWith("/")
+      ? rawBaseUrl.slice(0, -1)
+      : rawBaseUrl;
 
     return `${baseUrl}/${orgName}`;
   };
@@ -245,6 +248,11 @@ export function OrganizationList({
                 </div>
               </div>
 
+              {/* Error message for failed orgs */}
+              {org.status === "failed" && org.errorMessage && (
+                <p className="text-xs text-destructive line-clamp-2">{org.errorMessage}</p>
+              )}
+
               {/* Destination override section */}
               <div>
                 <MirrorDestinationEditor
@@ -301,6 +309,13 @@ export function OrganizationList({
                 />
               </div>
 
+              {/* Error message for failed orgs */}
+              {org.status === "failed" && org.errorMessage && (
+                <div className="mb-4 p-3 rounded-md bg-destructive/10 border border-destructive/20">
+                  <p className="text-sm text-destructive">{org.errorMessage}</p>
+                </div>
+              )}
+
               {/* Repository statistics */}
               <div className="mb-4">
                 <div className="flex items-center gap-4 text-sm">
@@ -310,7 +325,7 @@ export function OrganizationList({
                       {org.repositoryCount === 1 ? "repository" : "repositories"}
                     </span>
                   </div>
-                  
+
                   {/* Repository breakdown - only show non-zero counts */}
                   {(() => {
                     const counts = [];
@@ -323,7 +338,7 @@ export function OrganizationList({
                     if (org.forkRepositoryCount && org.forkRepositoryCount > 0) {
                       counts.push(`${org.forkRepositoryCount} ${org.forkRepositoryCount === 1 ? 'fork' : 'forks'}`);
                     }
-                    
+
                     return counts.length > 0 ? (
                       <div className="flex items-center gap-3 text-xs text-muted-foreground">
                         {counts.map((count, index) => (
@@ -412,9 +427,9 @@ export function OrganizationList({
                     )}
                   </>
                 )}
-                
+
                 {/* Dropdown menu for additional actions */}
-                {org.status !== "ignored" && org.status !== "mirroring" && (
+                {org.status !== "mirroring" && (
                   <DropdownMenu>
                     <DropdownMenuTrigger asChild>
                       <Button variant="ghost" size="icon" disabled={isLoading} className="h-10 w-10">
@@ -422,17 +437,31 @@ export function OrganizationList({
                       </Button>
                     </DropdownMenuTrigger>
                     <DropdownMenuContent align="end">
-                      <DropdownMenuItem 
-                        onClick={() => org.id && onIgnore && onIgnore({ orgId: org.id, ignore: true })}
-                      >
-                        <Ban className="h-4 w-4 mr-2" />
-                        Ignore Organization
-                      </DropdownMenuItem>
+                      {org.status !== "ignored" && (
+                        <DropdownMenuItem
+                          onClick={() => org.id && onIgnore && onIgnore({ orgId: org.id, ignore: true })}
+                        >
+                          <Ban className="h-4 w-4 mr-2" />
+                          Ignore Organization
+                        </DropdownMenuItem>
+                      )}
+                      {onDelete && (
+                        <>
+                          {org.status !== "ignored" && <DropdownMenuSeparator />}
+                          <DropdownMenuItem
+                            className="text-destructive focus:text-destructive"
+                            onClick={() => org.id && onDelete(org.id)}
+                          >
+                            <Trash2 className="h-4 w-4 mr-2" />
+                            Delete from Mirror
+                          </DropdownMenuItem>
+                        </>
+                      )}
                     </DropdownMenuContent>
                   </DropdownMenu>
                 )}
               </div>
-              
+
               <div className="flex items-center gap-2 justify-center">
                 {(() => {
                   const giteaUrl = getGiteaOrgUrl(org);
@@ -561,7 +590,7 @@ export function OrganizationList({
                 )}
                 
                 {/* Dropdown menu for additional actions */}
-                {org.status !== "ignored" && org.status !== "mirroring" && (
+                {org.status !== "mirroring" && (
                   <DropdownMenu>
                     <DropdownMenuTrigger asChild>
                       <Button variant="ghost" size="icon" disabled={isLoading}>
@@ -569,12 +598,26 @@ export function OrganizationList({
                       </Button>
                     </DropdownMenuTrigger>
                     <DropdownMenuContent align="end">
-                      <DropdownMenuItem 
-                        onClick={() => org.id && onIgnore && onIgnore({ orgId: org.id, ignore: true })}
-                      >
-                        <Ban className="h-4 w-4 mr-2" />
-                        Ignore Organization
-                      </DropdownMenuItem>
+                      {org.status !== "ignored" && (
+                        <DropdownMenuItem 
+                          onClick={() => org.id && onIgnore && onIgnore({ orgId: org.id, ignore: true })}
+                        >
+                          <Ban className="h-4 w-4 mr-2" />
+                          Ignore Organization
+                        </DropdownMenuItem>
+                      )}
+                      {onDelete && (
+                        <>
+                          {org.status !== "ignored" && <DropdownMenuSeparator />}
+                          <DropdownMenuItem
+                            className="text-destructive focus:text-destructive"
+                            onClick={() => org.id && onDelete(org.id)}
+                          >
+                            <Trash2 className="h-4 w-4 mr-2" />
+                            Delete from Mirror
+                          </DropdownMenuItem>
+                        </>
+                      )}
                     </DropdownMenuContent>
                   </DropdownMenu>
                 )}

src/components/repositories/AddRepositoryDialog.tsx

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { Button } from "@/components/ui/button";
 import {
   Dialog,
@@ -17,9 +17,13 @@ interface AddRepositoryDialogProps {
   onAddRepository: ({
     repo,
     owner,
+    force,
+    destinationOrg,
   }: {
     repo: string;
     owner: string;
+    force?: boolean;
+    destinationOrg?: string;
   }) => Promise<void>;
 }
 
@@ -30,9 +34,19 @@ export default function AddRepositoryDialog({
 }: AddRepositoryDialogProps) {
   const [repo, setRepo] = useState<string>("");
   const [owner, setOwner] = useState<string>("");
+  const [destinationOrg, setDestinationOrg] = useState<string>("");
   const [isLoading, setIsLoading] = useState<boolean>(false);
   const [error, setError] = useState<string>("");
 
+  useEffect(() => {
+    if (!isDialogOpen) {
+      setError("");
+      setRepo("");
+      setOwner("");
+      setDestinationOrg("");
+    }
+  }, [isDialogOpen]);
+
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
 
@@ -44,11 +58,16 @@ export default function AddRepositoryDialog({
     try {
       setIsLoading(true);
 
-      await onAddRepository({ repo, owner });
+      await onAddRepository({
+        repo,
+        owner,
+        destinationOrg: destinationOrg.trim() || undefined,
+      });
 
       setError("");
       setRepo("");
       setOwner("");
+      setDestinationOrg("");
       setIsDialogOpen(false);
     } catch (err: any) {
       setError(err?.message || "Failed to add repository.");
@@ -114,6 +133,27 @@ export default function AddRepositoryDialog({
               />
             </div>
 
+            <div>
+              <label
+                htmlFor="destinationOrg"
+                className="block text-sm font-medium mb-1.5"
+              >
+                Target Organization{" "}
+                <span className="text-muted-foreground font-normal">
+                  (optional)
+                </span>
+              </label>
+              <input
+                id="destinationOrg"
+                type="text"
+                value={destinationOrg}
+                onChange={(e) => setDestinationOrg(e.target.value)}
+                className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                placeholder="Gitea org or user (uses default strategy if empty)"
+                autoComplete="off"
+              />
+            </div>
+
             {error && <p className="text-sm text-red-500 mt-1">{error}</p>}
           </div>
 

src/components/repositories/InlineDestinationEditor.tsx

@@ -28,9 +28,16 @@ export function InlineDestinationEditor({
 
   // Determine the default destination based on repository properties and config
   const getDefaultDestination = () => {
-    // Starred repos always go to the configured starredReposOrg
-    if (repository.isStarred && giteaConfig?.starredReposOrg) {
-      return giteaConfig.starredReposOrg;
+    // Starred repos can use either dedicated org or preserved source owner
+    if (repository.isStarred) {
+      const starredReposMode = giteaConfig?.starredReposMode || "dedicated-org";
+      if (starredReposMode === "preserve-owner") {
+        return repository.organization || repository.owner;
+      }
+      if (giteaConfig?.starredReposOrg) {
+        return giteaConfig.starredReposOrg;
+      }
+      return "starred";
     }
     
     // Check mirror strategy
@@ -60,7 +67,7 @@ export function InlineDestinationEditor({
   const defaultDestination = getDefaultDestination();
   const currentDestination = repository.destinationOrg || defaultDestination;
   const hasOverride = repository.destinationOrg && repository.destinationOrg !== defaultDestination;
-  const isStarredRepo = repository.isStarred && giteaConfig?.starredReposOrg;
+  const isStarredRepo = repository.isStarred;
 
   useEffect(() => {
     if (isEditing && inputRef.current) {
@@ -184,4 +191,4 @@ export function InlineDestinationEditor({
       </div>
     </div>
   );
-}
+}

src/components/repositories/Repository.tsx

@@ -18,7 +18,7 @@ import {
   SelectValue,
 } from "../ui/select";
 import { Button } from "@/components/ui/button";
-import { Search, RefreshCw, FlipHorizontal, RotateCcw, X, Filter, Ban, Check } from "lucide-react";
+import { Search, RefreshCw, FlipHorizontal, RotateCcw, X, Filter, Ban, Check, LoaderCircle, Trash2 } from "lucide-react";
 import type { MirrorRepoRequest, MirrorRepoResponse } from "@/types/mirror";
 import {
   Drawer,
@@ -30,12 +30,21 @@ import {
   DrawerTitle,
   DrawerTrigger,
 } from "@/components/ui/drawer";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
 import { useSSE } from "@/hooks/useSEE";
 import { useFilterParams } from "@/hooks/useFilterParams";
 import { toast } from "sonner";
 import type { SyncRepoRequest, SyncRepoResponse } from "@/types/sync";
 import { OwnerCombobox, OrganizationCombobox } from "./RepositoryComboboxes";
 import type { RetryRepoRequest, RetryRepoResponse } from "@/types/retry";
+import type { ResetMetadataRequest, ResetMetadataResponse } from "@/types/reset-metadata";
 import AddRepositoryDialog from "./AddRepositoryDialog";
 
 import { useLiveRefresh } from "@/hooks/useLiveRefresh";
@@ -47,7 +56,7 @@ export default function Repository() {
   const [isInitialLoading, setIsInitialLoading] = useState(true);
   const { user } = useAuth();
   const { registerRefreshCallback, isLiveEnabled } = useLiveRefresh();
-  const { isGitHubConfigured, isFullyConfigured } = useConfigStatus();
+  const { isGitHubConfigured, isFullyConfigured, autoMirrorStarred, githubOwner } = useConfigStatus();
   const { navigationKey } = useNavigation();
   const { filter, setFilter } = useFilterParams({
     searchTerm: "",
@@ -69,6 +78,15 @@ export default function Repository() {
   }, [setFilter]);
 
   const [loadingRepoIds, setLoadingRepoIds] = useState<Set<string>>(new Set()); // this is used when the api actions are performed
+  const [duplicateRepoCandidate, setDuplicateRepoCandidate] = useState<{
+    owner: string;
+    repo: string;
+  } | null>(null);
+  const [isDuplicateRepoDialogOpen, setIsDuplicateRepoDialogOpen] = useState(false);
+  const [isProcessingDuplicateRepo, setIsProcessingDuplicateRepo] = useState(false);
+  const [repoToDelete, setRepoToDelete] = useState<Repository | null>(null);
+  const [isDeleteRepoDialogOpen, setIsDeleteRepoDialogOpen] = useState(false);
+  const [isDeletingRepo, setIsDeletingRepo] = useState(false);
 
   // Create a stable callback using useCallback
   const handleNewMessage = useCallback((data: MirrorJob) => {
@@ -215,10 +233,12 @@ export default function Repository() {
       // Filter out repositories that are already mirroring, mirrored, or ignored
       const eligibleRepos = repositories.filter(
         (repo) =>
-          repo.status !== "mirroring" && 
-          repo.status !== "mirrored" && 
+          repo.status !== "mirroring" &&
+          repo.status !== "mirrored" &&
           repo.status !== "ignored" && // Skip ignored repositories
-          repo.id
+          repo.id &&
+          // Skip starred repos from other owners when autoMirrorStarred is disabled
+          !(repo.isStarred && !autoMirrorStarred && repo.owner !== githubOwner)
       );
 
       if (eligibleRepos.length === 0) {
@@ -274,7 +294,7 @@ export default function Repository() {
     
     const selectedRepos = repositories.filter(repo => repo.id && selectedRepoIds.has(repo.id));
     const eligibleRepos = selectedRepos.filter(
-      repo => repo.status === "imported" || repo.status === "failed"
+      repo => repo.status === "imported" || repo.status === "failed" || repo.status === "pending-approval"
     );
 
     if (eligibleRepos.length === 0) {
@@ -283,7 +303,7 @@ export default function Repository() {
     }
 
     const repoIds = eligibleRepos.map(repo => repo.id as string);
-    
+
     setLoadingRepoIds(prev => {
       const newSet = new Set(prev);
       repoIds.forEach(id => newSet.add(id));
@@ -320,7 +340,7 @@ export default function Repository() {
     
     const selectedRepos = repositories.filter(repo => repo.id && selectedRepoIds.has(repo.id));
     const eligibleRepos = selectedRepos.filter(
-      repo => repo.status === "mirrored" || repo.status === "synced"
+      repo => ["mirrored", "synced", "archived"].includes(repo.status)
     );
 
     if (eligibleRepos.length === 0) {
@@ -361,6 +381,67 @@ export default function Repository() {
     }
   };
 
+  const handleBulkRerunMetadata = async () => {
+    if (selectedRepoIds.size === 0) return;
+
+    const selectedRepos = repositories.filter(repo => repo.id && selectedRepoIds.has(repo.id));
+    const eligibleRepos = selectedRepos.filter(
+      repo => ["mirrored", "synced", "archived"].includes(repo.status)
+    );
+
+    if (eligibleRepos.length === 0) {
+      toast.info("No eligible repositories to re-run metadata in selection");
+      return;
+    }
+
+    const repoIds = eligibleRepos.map(repo => repo.id as string);
+
+    setLoadingRepoIds(prev => {
+      const newSet = new Set(prev);
+      repoIds.forEach(id => newSet.add(id));
+      return newSet;
+    });
+
+    try {
+      const resetPayload: ResetMetadataRequest = {
+        userId: user?.id || "",
+        repositoryIds: repoIds,
+      };
+
+      const resetResponse = await apiRequest<ResetMetadataResponse>("/job/reset-metadata", {
+        method: "POST",
+        data: resetPayload,
+      });
+
+      if (!resetResponse.success) {
+        showErrorToast(resetResponse.error || "Failed to reset metadata state", toast);
+        return;
+      }
+
+      const syncResponse = await apiRequest<SyncRepoResponse>("/job/sync-repo", {
+        method: "POST",
+        data: { userId: user?.id, repositoryIds: repoIds },
+      });
+
+      if (syncResponse.success) {
+        toast.success(`Re-running metadata for ${repoIds.length} repositories`);
+        setRepositories(prevRepos =>
+          prevRepos.map(repo => {
+            const updated = syncResponse.repositories.find(r => r.id === repo.id);
+            return updated ? updated : repo;
+          })
+        );
+        setSelectedRepoIds(new Set());
+      } else {
+        showErrorToast(syncResponse.error || "Error starting metadata re-sync", toast);
+      }
+    } catch (error) {
+      showErrorToast(error, toast);
+    } finally {
+      setLoadingRepoIds(new Set());
+    }
+  };
+
   const handleBulkRetry = async () => {
     if (selectedRepoIds.size === 0) return;
     
@@ -615,22 +696,125 @@ export default function Repository() {
     }
   };
 
+  const handleApproveSyncAction = async ({ repoId }: { repoId: string }) => {
+    try {
+      if (!user || !user.id) return;
+      setLoadingRepoIds((prev) => new Set(prev).add(repoId));
+
+      const response = await apiRequest<{
+        success: boolean;
+        message?: string;
+        error?: string;
+        repositories: Repository[];
+      }>("/job/approve-sync", {
+        method: "POST",
+        data: { repositoryIds: [repoId], action: "approve" },
+      });
+
+      if (response.success) {
+        toast.success("Sync approved — backup + sync started");
+        setRepositories((prevRepos) =>
+          prevRepos.map((repo) => {
+            const updated = response.repositories.find((r) => r.id === repo.id);
+            return updated ? updated : repo;
+          }),
+        );
+      } else {
+        showErrorToast(response.error || "Error approving sync", toast);
+      }
+    } catch (error) {
+      showErrorToast(error, toast);
+    } finally {
+      setLoadingRepoIds((prev) => {
+        const newSet = new Set(prev);
+        newSet.delete(repoId);
+        return newSet;
+      });
+    }
+  };
+
+  const handleDismissSyncAction = async ({ repoId }: { repoId: string }) => {
+    try {
+      if (!user || !user.id) return;
+      setLoadingRepoIds((prev) => new Set(prev).add(repoId));
+
+      const response = await apiRequest<{
+        success: boolean;
+        message?: string;
+        error?: string;
+        repositories: Repository[];
+      }>("/job/approve-sync", {
+        method: "POST",
+        data: { repositoryIds: [repoId], action: "dismiss" },
+      });
+
+      if (response.success) {
+        toast.success("Force-push alert dismissed");
+        setRepositories((prevRepos) =>
+          prevRepos.map((repo) => {
+            const updated = response.repositories.find((r) => r.id === repo.id);
+            return updated ? updated : repo;
+          }),
+        );
+      } else {
+        showErrorToast(response.error || "Error dismissing alert", toast);
+      }
+    } catch (error) {
+      showErrorToast(error, toast);
+    } finally {
+      setLoadingRepoIds((prev) => {
+        const newSet = new Set(prev);
+        newSet.delete(repoId);
+        return newSet;
+      });
+    }
+  };
+
   const handleAddRepository = async ({
     repo,
     owner,
+    force = false,
+    destinationOrg,
   }: {
     repo: string;
     owner: string;
+    force?: boolean;
+    destinationOrg?: string;
   }) => {
-    try {
-      if (!user || !user.id) {
-        return;
-      }
+    if (!user || !user.id) {
+      return;
+    }
 
+    const trimmedRepo = repo.trim();
+    const trimmedOwner = owner.trim();
+
+    if (!trimmedRepo || !trimmedOwner) {
+      toast.error("Please provide both owner and repository name.");
+      throw new Error("Invalid repository details");
+    }
+
+    const normalizedFullName = `${trimmedOwner}/${trimmedRepo}`.toLowerCase();
+
+    if (!force) {
+      const duplicateRepo = repositories.find(
+        (existing) => existing.normalizedFullName?.toLowerCase() === normalizedFullName
+      );
+
+      if (duplicateRepo) {
+        toast.warning("Repository already exists.");
+        setDuplicateRepoCandidate({ repo: trimmedRepo, owner: trimmedOwner });
+        setIsDuplicateRepoDialogOpen(true);
+        throw new Error("Repository already exists");
+      }
+    }
+
+    try {
       const reqPayload: AddRepositoriesApiRequest = {
         userId: user.id,
-        repo,
-        owner,
+        repo: trimmedRepo,
+        owner: trimmedOwner,
+        force,
+        ...(destinationOrg ? { destinationOrg } : {}),
       };
 
       const response = await apiRequest<AddRepositoriesApiResponse>(
@@ -642,20 +826,28 @@ export default function Repository() {
       );
 
       if (response.success) {
-        toast.success(`Repository added successfully`);
-        setRepositories((prevRepos) => [...prevRepos, response.repository]);
+        const message = force
+          ? "Repository already exists; metadata refreshed."
+          : "Repository added successfully";
+        toast.success(message);
 
-        await fetchRepositories(false); // Manual refresh after adding repository
+        await fetchRepositories(false);
 
         setFilter((prev) => ({
           ...prev,
-          searchTerm: repo,
+          searchTerm: trimmedRepo,
         }));
+
+        if (force) {
+          setDuplicateRepoCandidate(null);
+          setIsDuplicateRepoDialogOpen(false);
+        }
       } else {
         showErrorToast(response.error || "Error adding repository", toast);
       }
     } catch (error) {
       showErrorToast(error, toast);
+      throw error;
     }
   };
 
@@ -673,6 +865,71 @@ export default function Repository() {
     )
   ).sort();
 
+  const handleConfirmDuplicateRepository = async () => {
+    if (!duplicateRepoCandidate) {
+      return;
+    }
+
+    setIsProcessingDuplicateRepo(true);
+    try {
+      await handleAddRepository({
+        repo: duplicateRepoCandidate.repo,
+        owner: duplicateRepoCandidate.owner,
+        force: true,
+      });
+      setIsDialogOpen(false);
+    } catch (error) {
+      // Error already shown
+    } finally {
+      setIsProcessingDuplicateRepo(false);
+    }
+  };
+
+  const handleCancelDuplicateRepository = () => {
+    setDuplicateRepoCandidate(null);
+    setIsDuplicateRepoDialogOpen(false);
+  };
+
+  const handleRequestDeleteRepository = (repoId: string) => {
+    const repo = repositories.find((item) => item.id === repoId);
+    if (!repo) {
+      toast.error("Repository not found");
+      return;
+    }
+
+    setRepoToDelete(repo);
+    setIsDeleteRepoDialogOpen(true);
+  };
+
+  const handleDeleteRepository = async () => {
+    if (!user || !user.id || !repoToDelete) {
+      return;
+    }
+
+    setIsDeletingRepo(true);
+    try {
+      const response = await apiRequest<{ success: boolean; error?: string }>(
+        `/repositories/${repoToDelete.id}`,
+        {
+          method: "DELETE",
+        }
+      );
+
+      if (response.success) {
+        toast.success(`Removed ${repoToDelete.fullName} from Gitea Mirror.`);
+        await fetchRepositories(false);
+      } else {
+        showErrorToast(response.error || "Failed to delete repository", toast);
+      }
+    } catch (error) {
+      showErrorToast(error, toast);
+    } finally {
+      setIsDeletingRepo(false);
+      setIsDeleteRepoDialogOpen(false);
+      setRepoToDelete(null);
+    }
+  };
+
   // Determine what actions are available for selected repositories
   const getAvailableActions = () => {
     if (selectedRepoIds.size === 0) return [];
@@ -682,7 +939,7 @@ export default function Repository() {
     const actions = [];
     
     // Check if any selected repos can be mirrored
-    if (selectedRepos.some(repo => repo.status === "imported" || repo.status === "failed")) {
+    if (selectedRepos.some(repo => repo.status === "imported" || repo.status === "failed" || repo.status === "pending-approval")) {
       actions.push('mirror');
     }
     
@@ -690,6 +947,10 @@ export default function Repository() {
     if (selectedRepos.some(repo => repo.status === "mirrored" || repo.status === "synced")) {
       actions.push('sync');
     }
+
+    if (selectedRepos.some(repo => ["mirrored", "synced", "archived"].includes(repo.status))) {
+      actions.push('rerun-metadata');
+    }
     
     // Check if any selected repos are failed
     if (selectedRepos.some(repo => repo.status === "failed")) {
@@ -716,8 +977,9 @@ export default function Repository() {
     const selectedRepos = repositories.filter(repo => repo.id && selectedRepoIds.has(repo.id));
     
     return {
-      mirror: selectedRepos.filter(repo => repo.status === "imported" || repo.status === "failed").length,
+      mirror: selectedRepos.filter(repo => repo.status === "imported" || repo.status === "failed" || repo.status === "pending-approval").length,
       sync: selectedRepos.filter(repo => repo.status === "mirrored" || repo.status === "synced").length,
+      rerunMetadata: selectedRepos.filter(repo => ["mirrored", "synced", "archived"].includes(repo.status)).length,
       retry: selectedRepos.filter(repo => repo.status === "failed").length,
       ignore: selectedRepos.filter(repo => repo.status !== "ignored").length,
       include: selectedRepos.filter(repo => repo.status === "ignored").length,
@@ -1041,6 +1303,18 @@ export default function Repository() {
                     Sync ({actionCounts.sync})
                   </Button>
                 )}
+
+                {availableActions.includes('rerun-metadata') && (
+                  <Button
+                    variant="outline"
+                    size="default"
+                    onClick={handleBulkRerunMetadata}
+                    disabled={loadingRepoIds.size > 0}
+                  >
+                    <RefreshCw className="h-4 w-4 mr-2" />
+                    Re-run Metadata ({actionCounts.rerunMetadata})
+                  </Button>
+                )}
                 
                 {availableActions.includes('retry') && (
                   <Button
@@ -1124,6 +1398,18 @@ export default function Repository() {
               <span className="hidden sm:inline">Sync </span>({actionCounts.sync})
             </Button>
           )}
+
+          {availableActions.includes('rerun-metadata') && (
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={handleBulkRerunMetadata}
+              disabled={loadingRepoIds.size > 0}
+            >
+              <RefreshCw className="h-4 w-4 mr-2" />
+              Re-run Metadata ({actionCounts.rerunMetadata})
+            </Button>
+          )}
           
           {availableActions.includes('retry') && (
             <Button
@@ -1198,6 +1484,9 @@ export default function Repository() {
           onRefresh={async () => {
             await fetchRepositories(false);
           }}
+          onDelete={handleRequestDeleteRepository}
+          onApproveSync={handleApproveSyncAction}
+          onDismissSync={handleDismissSyncAction}
         />
       )}
 
@@ -1206,6 +1495,77 @@ export default function Repository() {
         isDialogOpen={isDialogOpen}
         setIsDialogOpen={setIsDialogOpen}
       />
+
+      <Dialog
+        open={isDuplicateRepoDialogOpen}
+        onOpenChange={(open) => {
+          if (!open) {
+            handleCancelDuplicateRepository();
+          }
+        }}
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Repository already exists</DialogTitle>
+            <DialogDescription>
+              {duplicateRepoCandidate ? `${duplicateRepoCandidate.owner}/${duplicateRepoCandidate.repo}` : "This repository"} is already tracked in Gitea Mirror. Continuing will refresh the existing entry without creating a duplicate.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button variant="outline" onClick={handleCancelDuplicateRepository} disabled={isProcessingDuplicateRepo}>
+              Cancel
+            </Button>
+            <Button onClick={handleConfirmDuplicateRepository} disabled={isProcessingDuplicateRepo}>
+              {isProcessingDuplicateRepo ? (
+                <LoaderCircle className="h-4 w-4 animate-spin" />
+              ) : (
+                "Continue"
+              )}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      <Dialog
+        open={isDeleteRepoDialogOpen}
+        onOpenChange={(open) => {
+          if (!open) {
+            setIsDeleteRepoDialogOpen(false);
+            setRepoToDelete(null);
+          }
+        }}
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Remove repository from Gitea Mirror?</DialogTitle>
+            <DialogDescription>
+              {repoToDelete?.fullName ?? "This repository"} will be deleted from Gitea Mirror only. The mirror on Gitea will remain untouched; remove it manually in Gitea if needed.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button
+              variant="outline"
+              onClick={() => {
+                setIsDeleteRepoDialogOpen(false);
+                setRepoToDelete(null);
+              }}
+              disabled={isDeletingRepo}
+            >
+              Cancel
+            </Button>
+            <Button variant="destructive" onClick={handleDeleteRepository} disabled={isDeletingRepo}>
+              {isDeletingRepo ? (
+                <LoaderCircle className="h-4 w-4 animate-spin" />
+              ) : (
+                <span className="flex items-center gap-2">
+                  <Trash2 className="h-4 w-4" />
+                  Delete
+                </span>
+              )}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
     </div>
   );
 }

src/components/repositories/RepositoryTable.tsx

@@ -1,7 +1,7 @@
 import { useMemo, useRef } from "react";
 import Fuse from "fuse.js";
 import { useVirtualizer } from "@tanstack/react-virtual";
-import { FlipHorizontal, GitFork, RefreshCw, RotateCcw, Star, Lock, Ban, Check, ChevronDown } from "lucide-react";
+import { FlipHorizontal, GitFork, RefreshCw, RotateCcw, Star, Lock, Ban, Check, ChevronDown, Trash2, X } from "lucide-react";
 import { SiGithub, SiGitea } from "react-icons/si";
 import type { Repository } from "@/lib/db/schema";
 import { Button } from "@/components/ui/button";
@@ -23,6 +23,7 @@ import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
+  DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 
@@ -40,6 +41,9 @@ interface RepositoryTableProps {
   selectedRepoIds: Set<string>;
   onSelectionChange: (selectedIds: Set<string>) => void;
   onRefresh?: () => Promise<void>;
+  onDelete?: (repoId: string) => void;
+  onApproveSync?: ({ repoId }: { repoId: string }) => Promise<void>;
+  onDismissSync?: ({ repoId }: { repoId: string }) => Promise<void>;
 }
 
 export default function RepositoryTable({
@@ -56,6 +60,9 @@ export default function RepositoryTable({
   selectedRepoIds,
   onSelectionChange,
   onRefresh,
+  onDelete,
+  onApproveSync,
+  onDismissSync,
 }: RepositoryTableProps) {
   const tableParentRef = useRef<HTMLDivElement>(null);
   const { giteaConfig } = useGiteaConfig();
@@ -90,7 +97,7 @@ export default function RepositoryTable({
     }
 
     // Only provide Gitea links for repositories that have been or are being mirrored
-    const validStatuses = ['mirroring', 'mirrored', 'syncing', 'synced'];
+    const validStatuses = ['mirroring', 'mirrored', 'syncing', 'synced', 'archived'];
     if (!validStatuses.includes(repository.status)) {
       return null;
     }
@@ -236,6 +243,7 @@ export default function RepositoryTable({
                       repo.status === 'failed' ? 'bg-red-500/10 text-red-600 hover:bg-red-500/20 dark:text-red-400' :
                       repo.status === 'ignored' ? 'bg-gray-500/10 text-gray-600 hover:bg-gray-500/20 dark:text-gray-400' :
                       repo.status === 'skipped' ? 'bg-orange-500/10 text-orange-600 hover:bg-orange-500/20 dark:text-orange-400' :
+                      repo.status === 'pending-approval' ? 'bg-amber-500/10 text-amber-600 hover:bg-amber-500/20 dark:text-amber-400' :
                       'bg-muted hover:bg-muted/80'}`}
                   variant="secondary"
                 >
@@ -313,7 +321,40 @@ export default function RepositoryTable({
                   )}
                 </Button>
               )}
-              
+              {repo.status === "pending-approval" && (
+                <div className="flex gap-2 w-full">
+                  <Button
+                    size="default"
+                    variant="default"
+                    onClick={() => repo.id && onApproveSync?.({ repoId: repo.id })}
+                    disabled={isLoading}
+                    className="flex-1 h-10"
+                  >
+                    {isLoading ? (
+                      <>
+                        <Check className="h-4 w-4 mr-2 animate-spin" />
+                        Approving...
+                      </>
+                    ) : (
+                      <>
+                        <Check className="h-4 w-4 mr-2" />
+                        Approve Sync
+                      </>
+                    )}
+                  </Button>
+                  <Button
+                    size="default"
+                    variant="outline"
+                    onClick={() => repo.id && onDismissSync?.({ repoId: repo.id })}
+                    disabled={isLoading}
+                    className="flex-1 h-10"
+                  >
+                    <X className="h-4 w-4 mr-2" />
+                    Dismiss
+                  </Button>
+                </div>
+              )}
+
               {/* Ignore/Include button */}
               {repo.status === "ignored" ? (
                 <Button
@@ -660,6 +701,7 @@ export default function RepositoryTable({
                                 repo.status === 'failed' ? 'bg-red-500/10 text-red-600 hover:bg-red-500/20 dark:text-red-400' :
                                 repo.status === 'ignored' ? 'bg-gray-500/10 text-gray-600 hover:bg-gray-500/20 dark:text-gray-400' :
                                 repo.status === 'skipped' ? 'bg-orange-500/10 text-orange-600 hover:bg-orange-500/20 dark:text-orange-400' :
+                                repo.status === 'pending-approval' ? 'bg-amber-500/10 text-amber-600 hover:bg-amber-500/20 dark:text-amber-400' :
                                 'bg-muted hover:bg-muted/80'}`}
                             variant="secondary"
                           >
@@ -676,6 +718,9 @@ export default function RepositoryTable({
                           onSync={() => onSync({ repoId: repo.id ?? "" })}
                           onRetry={() => onRetry({ repoId: repo.id ?? "" })}
                           onSkip={(skip) => onSkip({ repoId: repo.id ?? "", skip })}
+                          onDelete={onDelete && repo.id ? () => onDelete(repo.id as string) : undefined}
+                          onApproveSync={onApproveSync ? () => onApproveSync({ repoId: repo.id ?? "" }) : undefined}
+                          onDismissSync={onDismissSync ? () => onDismissSync({ repoId: repo.id ?? "" }) : undefined}
                         />
                       </div>
                       {/* Links */}
@@ -786,6 +831,9 @@ function RepoActionButton({
   onSync,
   onRetry,
   onSkip,
+  onDelete,
+  onApproveSync,
+  onDismissSync,
 }: {
   repo: { id: string; status: string };
   isLoading: boolean;
@@ -793,7 +841,37 @@ function RepoActionButton({
   onSync: () => void;
   onRetry: () => void;
   onSkip: (skip: boolean) => void;
+  onDelete?: () => void;
+  onApproveSync?: () => void;
+  onDismissSync?: () => void;
 }) {
+  // For pending-approval repos, show approve/dismiss actions
+  if (repo.status === "pending-approval") {
+    return (
+      <div className="flex gap-1">
+        <Button
+          variant="default"
+          size="sm"
+          disabled={isLoading}
+          onClick={onApproveSync}
+          className="min-w-[70px]"
+        >
+          <Check className="h-4 w-4 mr-1" />
+          Approve
+        </Button>
+        <Button
+          variant="outline"
+          size="sm"
+          disabled={isLoading}
+          onClick={onDismissSync}
+        >
+          <X className="h-4 w-4 mr-1" />
+          Dismiss
+        </Button>
+      </div>
+    );
+  }
+
   // For ignored repos, show an "Include" action
   if (repo.status === "ignored") {
     return (
@@ -820,8 +898,8 @@ function RepoActionButton({
     primaryLabel = "Retry";
     primaryIcon = <RotateCcw className="h-4 w-4" />;
     primaryOnClick = onRetry;
-  } else if (["mirrored", "synced", "syncing"].includes(repo.status)) {
-    primaryLabel = "Sync";
+  } else if (["mirrored", "synced", "syncing", "archived"].includes(repo.status)) {
+    primaryLabel = repo.status === "archived" ? "Manual Sync" : "Sync";
     primaryIcon = <RefreshCw className="h-4 w-4" />;
     primaryOnClick = onSync;
     primaryDisabled ||= repo.status === "syncing";
@@ -849,7 +927,7 @@ function RepoActionButton({
     );
   }
 
-  // Show primary action with dropdown for skip option
+  // Show primary action with dropdown for additional actions
   return (
     <DropdownMenu>
       <div className="flex">
@@ -886,7 +964,19 @@ function RepoActionButton({
           <Ban className="h-4 w-4 mr-2" />
           Ignore Repository
         </DropdownMenuItem>
+        {onDelete && (
+          <>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem
+              className="text-destructive focus:text-destructive"
+              onClick={onDelete}
+            >
+              <Trash2 className="h-4 w-4 mr-2" />
+              Delete from Mirror
+            </DropdownMenuItem>
+          </>
+        )}
       </DropdownMenuContent>
     </DropdownMenu>
   );
-}
+}

src/hooks/useConfigStatus.ts

@@ -9,6 +9,8 @@ interface ConfigStatus {
   isFullyConfigured: boolean;
   isLoading: boolean;
   error: string | null;
+  autoMirrorStarred: boolean;
+  githubOwner: string;
 }
 
 // Cache to prevent duplicate API calls across components
@@ -33,6 +35,8 @@ export function useConfigStatus(): ConfigStatus {
     isFullyConfigured: false,
     isLoading: true,
     error: null,
+    autoMirrorStarred: false,
+    githubOwner: '',
   });
 
   // Track if this hook has already checked config to prevent multiple calls
@@ -46,6 +50,8 @@ export function useConfigStatus(): ConfigStatus {
         isFullyConfigured: false,
         isLoading: false,
         error: 'No user found',
+        autoMirrorStarred: false,
+        githubOwner: '',
       });
       return;
     }
@@ -78,6 +84,8 @@ export function useConfigStatus(): ConfigStatus {
         isFullyConfigured,
         isLoading: false,
         error: null,
+        autoMirrorStarred: configResponse?.advancedOptions?.autoMirrorStarred ?? false,
+        githubOwner: configResponse?.githubConfig?.username ?? '',
       });
       return;
     }
@@ -119,6 +127,8 @@ export function useConfigStatus(): ConfigStatus {
         isFullyConfigured,
         isLoading: false,
         error: null,
+        autoMirrorStarred: configResponse?.advancedOptions?.autoMirrorStarred ?? false,
+        githubOwner: configResponse?.githubConfig?.username ?? '',
       });
 
       hasCheckedRef.current = true;
@@ -129,6 +139,8 @@ export function useConfigStatus(): ConfigStatus {
         isFullyConfigured: false,
         isLoading: false,
         error: error instanceof Error ? error.message : 'Failed to check configuration',
+        autoMirrorStarred: false,
+        githubOwner: '',
       });
       hasCheckedRef.current = true;
     }

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";
@@ -60,4 +61,4 @@ export type Session = BetterAuthSession & {
 };
 export type AuthUser = BetterAuthUser & {
   username?: string | null;
-};
+};

src/lib/auth-guards.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, mock, test } from "bun:test";
+
+const getSessionMock = mock(async () => null);
+
+mock.module("@/lib/auth", () => ({
+  auth: {
+    api: {
+      getSession: getSessionMock,
+    },
+  },
+}));
+
+import { requireAuthenticatedUserId } from "./auth-guards";
+
+describe("requireAuthenticatedUserId", () => {
+  test("returns user id from locals session without calling auth api", async () => {
+    getSessionMock.mockImplementation(async () => {
+      throw new Error("should not be called");
+    });
+
+    const result = await requireAuthenticatedUserId({
+      request: new Request("http://localhost/test"),
+      locals: {
+        session: { userId: "local-user-id" },
+      } as any,
+    });
+
+    expect("userId" in result).toBe(true);
+    if ("userId" in result) {
+      expect(result.userId).toBe("local-user-id");
+    }
+  });
+
+  test("returns user id from auth session when locals are empty", async () => {
+    getSessionMock.mockImplementation(async () => ({
+      user: { id: "session-user-id" },
+      session: { id: "session-id" },
+    }));
+
+    const result = await requireAuthenticatedUserId({
+      request: new Request("http://localhost/test"),
+      locals: {} as any,
+    });
+
+    expect("userId" in result).toBe(true);
+    if ("userId" in result) {
+      expect(result.userId).toBe("session-user-id");
+    }
+  });
+
+  test("returns unauthorized response when auth lookup throws", async () => {
+    getSessionMock.mockImplementation(async () => {
+      throw new Error("session provider unavailable");
+    });
+
+    const result = await requireAuthenticatedUserId({
+      request: new Request("http://localhost/test"),
+      locals: {} as any,
+    });
+
+    expect("response" in result).toBe(true);
+    if ("response" in result) {
+      expect(result.response.status).toBe(401);
+    }
+  });
+});

src/lib/auth-guards.ts

@@ -0,0 +1,45 @@
+import type { APIContext } from "astro";
+import { auth } from "@/lib/auth";
+
+function unauthorizedResponse() {
+  return new Response(
+    JSON.stringify({
+      success: false,
+      error: "Unauthorized",
+    }),
+    {
+      status: 401,
+      headers: { "Content-Type": "application/json" },
+    }
+  );
+}
+
+/**
+ * Ensures request is authenticated and returns the authenticated user ID.
+ * Never trust client-provided userId for authorization decisions.
+ */
+export async function requireAuthenticatedUserId(
+  context: Pick<APIContext, "request" | "locals">
+): Promise<{ userId: string } | { response: Response }> {
+  const localUserId =
+    context.locals?.session?.userId || context.locals?.user?.id;
+
+  if (localUserId) {
+    return { userId: localUserId };
+  }
+
+  let session: Awaited<ReturnType<typeof auth.api.getSession>> | null = null;
+  try {
+    session = await auth.api.getSession({
+      headers: context.request.headers,
+    });
+  } catch {
+    return { response: unauthorizedResponse() };
+  }
+
+  if (!session?.user?.id) {
+    return { response: unauthorizedResponse() };
+  }
+
+  return { userId: session.user.id };
+}

src/lib/auth.ts

@@ -166,9 +166,11 @@ export const auth = betterAuth({
       defaultOverrideUserInfo: true,
       // Allow implicit sign up for new users
       disableImplicitSignUp: false,
+      // Trust email_verified claims from the upstream provider so we can link by matching email
+      trustEmailVerified: true,
     }),
   ],
 });
 
 // Export type for use in other parts of the app
-export type Auth = typeof auth;
+export type Auth = typeof auth;

src/lib/db/schema.ts

@@ -25,15 +25,25 @@ export const githubConfigSchema = z.object({
   includePublic: z.boolean().default(true),
   includeOrganizations: z.array(z.string()).default([]),
   starredReposOrg: z.string().optional(),
+  starredReposMode: z.enum(["dedicated-org", "preserve-owner"]).default("dedicated-org"),
   mirrorStrategy: z.enum(["preserve", "single-org", "flat-user", "mixed"]).default("preserve"),
   defaultOrg: z.string().optional(),
   starredCodeOnly: z.boolean().default(false),
+  autoMirrorStarred: z.boolean().default(false),
   skipStarredIssues: z.boolean().optional(), // Deprecated: kept for backward compatibility, use starredCodeOnly instead
   starredDuplicateStrategy: z.enum(["suffix", "prefix", "owner-org"]).default("suffix").optional(),
 });
 
+export const backupStrategyEnum = z.enum([
+  "disabled",
+  "always",
+  "on-force-push",
+  "block-on-force-push",
+]);
+
 export const giteaConfigSchema = z.object({
   url: z.url(),
+  externalUrl: z.url().optional(),
   token: z.string(),
   defaultOwner: z.string(),
   organization: z.string().optional(),
@@ -54,6 +64,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),
@@ -61,6 +73,11 @@ export const giteaConfigSchema = z.object({
   mirrorPullRequests: z.boolean().default(false),
   mirrorLabels: z.boolean().default(false),
   mirrorMilestones: z.boolean().default(false),
+  backupStrategy: backupStrategyEnum.default("on-force-push"),
+  backupBeforeSync: z.boolean().default(true), // Deprecated: kept for backward compat, use backupStrategy
+  backupRetentionCount: z.number().int().min(1).default(20),
+  backupDirectory: z.string().optional(),
+  blockSyncOnBackupFailure: z.boolean().default(true),
 });
 
 export const scheduleConfigSchema = z.object({
@@ -94,7 +111,7 @@ export const cleanupConfigSchema = z.object({
   deleteFromGitea: z.boolean().default(false),
   deleteIfNotInGitHub: z.boolean().default(true),
   protectedRepos: z.array(z.string()).default([]),
-  dryRun: z.boolean().default(true),
+  dryRun: z.boolean().default(false),
   orphanedRepoAction: z
     .enum(["skip", "archive", "delete"])
     .default("archive"),
@@ -125,6 +142,7 @@ export const repositorySchema = z.object({
   configId: z.string(),
   name: z.string(),
   fullName: z.string(),
+  normalizedFullName: z.string(),
   url: z.url(),
   cloneUrl: z.url(),
   owner: z.string(),
@@ -156,11 +174,13 @@ export const repositorySchema = z.object({
       "syncing",
       "synced",
       "archived",
+      "pending-approval", // Blocked by force-push detection, needs manual approval
     ])
     .default("imported"),
   lastMirrored: z.coerce.date().optional().nullable(),
   errorMessage: z.string().optional().nullable(),
   destinationOrg: z.string().optional().nullable(),
+  metadata: z.string().optional().nullable(), // JSON string for metadata sync state
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
 });
@@ -186,6 +206,7 @@ export const mirrorJobSchema = z.object({
       "syncing",
       "synced",
       "archived",
+      "pending-approval",
     ])
     .default("imported"),
   message: z.string(),
@@ -207,6 +228,7 @@ export const organizationSchema = z.object({
   userId: z.string(),
   configId: z.string(),
   name: z.string(),
+  normalizedName: z.string(),
   avatarUrl: z.string(),
   membershipRole: z.enum(["member", "admin", "owner", "billing_manager"]).default("member"),
   isIncluded: z.boolean().default(true),
@@ -332,6 +354,7 @@ export const repositories = sqliteTable("repositories", {
     .references(() => configs.id),
   name: text("name").notNull(),
   fullName: text("full_name").notNull(),
+  normalizedFullName: text("normalized_full_name").notNull(),
   url: text("url").notNull(),
   cloneUrl: text("clone_url").notNull(),
   owner: text("owner").notNull(),
@@ -371,6 +394,8 @@ export const repositories = sqliteTable("repositories", {
   
   destinationOrg: text("destination_org"),
 
+  metadata: text("metadata"), // JSON string storing metadata sync state (issues, PRs, releases, etc.)
+
   createdAt: integer("created_at", { mode: "timestamp" })
     .notNull()
     .default(sql`(unixepoch())`),
@@ -386,6 +411,7 @@ export const repositories = sqliteTable("repositories", {
   index("idx_repositories_is_fork").on(table.isForked),
   index("idx_repositories_is_starred").on(table.isStarred),
   uniqueIndex("uniq_repositories_user_full_name").on(table.userId, table.fullName),
+  uniqueIndex("uniq_repositories_user_normalized_full_name").on(table.userId, table.normalizedFullName),
 ]);
 
 export const mirrorJobs = sqliteTable("mirror_jobs", {
@@ -436,6 +462,7 @@ export const organizations = sqliteTable("organizations", {
     .notNull()
     .references(() => configs.id),
   name: text("name").notNull(),
+  normalizedName: text("normalized_name").notNull(),
 
   avatarUrl: text("avatar_url").notNull(),
 
@@ -467,6 +494,7 @@ export const organizations = sqliteTable("organizations", {
   index("idx_organizations_config_id").on(table.configId),
   index("idx_organizations_status").on(table.status),
   index("idx_organizations_is_included").on(table.isIncluded),
+  uniqueIndex("uniq_organizations_user_normalized_name").on(table.userId, table.normalizedName),
 ]);
 
 // ===== Better Auth Tables =====
@@ -500,6 +528,10 @@ export const accounts = sqliteTable("accounts", {
   providerUserId: text("provider_user_id"), // Make nullable for email/password auth
   accessToken: text("access_token"),
   refreshToken: text("refresh_token"),
+  idToken: text("id_token"),
+  accessTokenExpiresAt: integer("access_token_expires_at", { mode: "timestamp" }),
+  refreshTokenExpiresAt: integer("refresh_token_expires_at", { mode: "timestamp" }),
+  scope: text("scope"),
   expiresAt: integer("expires_at", { mode: "timestamp" }),
   password: text("password"), // For credential provider
   createdAt: integer("created_at", { mode: "timestamp" })

src/lib/env-config-loader.ts

@@ -22,11 +22,14 @@ interface EnvConfig {
     preserveOrgStructure?: boolean;
     onlyMirrorOrgs?: boolean;
     starredCodeOnly?: boolean;
+    autoMirrorStarred?: boolean;
     starredReposOrg?: string;
+    starredReposMode?: 'dedicated-org' | 'preserve-owner';
     mirrorStrategy?: 'preserve' | 'single-org' | 'flat-user' | 'mixed';
   };
   gitea: {
     url?: string;
+    externalUrl?: string;
     username?: string;
     token?: string;
     organization?: string;
@@ -49,6 +52,9 @@ interface EnvConfig {
     mirrorLabels?: boolean;
     mirrorMilestones?: boolean;
     mirrorMetadata?: boolean;
+    releaseLimit?: number;
+    issueConcurrency?: number;
+    pullRequestConcurrency?: number;
   };
   schedule: {
     enabled?: boolean;
@@ -108,11 +114,14 @@ function parseEnvConfig(): EnvConfig {
       preserveOrgStructure: process.env.PRESERVE_ORG_STRUCTURE === 'true',
       onlyMirrorOrgs: process.env.ONLY_MIRROR_ORGS === 'true',
       starredCodeOnly: process.env.SKIP_STARRED_ISSUES === 'true',
+      autoMirrorStarred: process.env.AUTO_MIRROR_STARRED === 'true',
       starredReposOrg: process.env.STARRED_REPOS_ORG,
+      starredReposMode: process.env.STARRED_REPOS_MODE as 'dedicated-org' | 'preserve-owner',
       mirrorStrategy: process.env.MIRROR_STRATEGY as 'preserve' | 'single-org' | 'flat-user' | 'mixed',
     },
     gitea: {
       url: process.env.GITEA_URL,
+      externalUrl: process.env.GITEA_EXTERNAL_URL,
       username: process.env.GITEA_USERNAME,
       token: process.env.GITEA_TOKEN,
       organization: process.env.GITEA_ORGANIZATION,
@@ -136,6 +145,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' || 
@@ -169,7 +180,7 @@ function parseEnvConfig(): EnvConfig {
       deleteFromGitea: process.env.CLEANUP_DELETE_FROM_GITEA === 'true',
       deleteIfNotInGitHub: process.env.CLEANUP_DELETE_IF_NOT_IN_GITHUB === 'true',
       protectedRepos,
-      dryRun: process.env.CLEANUP_DRY_RUN === 'true',
+      dryRun: process.env.CLEANUP_DRY_RUN === 'true' ? true : process.env.CLEANUP_DRY_RUN === 'false' ? false : false,
       orphanedRepoAction: process.env.CLEANUP_ORPHANED_REPO_ACTION as 'skip' | 'archive' | 'delete',
       batchSize: process.env.CLEANUP_BATCH_SIZE ? parseInt(process.env.CLEANUP_BATCH_SIZE, 10) : undefined,
       pauseBetweenDeletes: process.env.CLEANUP_PAUSE_BETWEEN_DELETES ? parseInt(process.env.CLEANUP_PAUSE_BETWEEN_DELETES, 10) : undefined,
@@ -251,14 +262,17 @@ export async function initializeConfigFromEnv(): Promise<void> {
       includePublic: envConfig.github.publicRepositories ?? existingConfig?.[0]?.githubConfig?.includePublic ?? true,
       includeOrganizations: envConfig.github.mirrorOrganizations ? [] : (existingConfig?.[0]?.githubConfig?.includeOrganizations ?? []),
       starredReposOrg: envConfig.github.starredReposOrg || existingConfig?.[0]?.githubConfig?.starredReposOrg || 'starred',
+      starredReposMode: envConfig.github.starredReposMode || existingConfig?.[0]?.githubConfig?.starredReposMode || 'dedicated-org',
       mirrorStrategy,
       defaultOrg: envConfig.gitea.organization || existingConfig?.[0]?.githubConfig?.defaultOrg || 'github-mirrors',
       starredCodeOnly: envConfig.github.starredCodeOnly ?? existingConfig?.[0]?.githubConfig?.starredCodeOnly ?? false,
+      autoMirrorStarred: envConfig.github.autoMirrorStarred ?? existingConfig?.[0]?.githubConfig?.autoMirrorStarred ?? false,
     };
 
     // Build Gitea config
     const giteaConfig = {
       url: envConfig.gitea.url || existingConfig?.[0]?.giteaConfig?.url || '',
+      externalUrl: envConfig.gitea.externalUrl || existingConfig?.[0]?.giteaConfig?.externalUrl || undefined,
       token: envConfig.gitea.token ? encrypt(envConfig.gitea.token) : existingConfig?.[0]?.giteaConfig?.token || '',
       defaultOwner: envConfig.gitea.username || existingConfig?.[0]?.giteaConfig?.defaultOwner || '',
       organization: envConfig.gitea.organization || existingConfig?.[0]?.giteaConfig?.organization || undefined,
@@ -277,6 +291,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-enhanced.test.ts

@@ -8,7 +8,16 @@ mock.module("@/lib/helpers", () => ({
 }));
 
 const mockMirrorGitHubReleasesToGitea = mock(() => Promise.resolve());
+const mockMirrorGitRepoIssuesToGitea = mock(() => Promise.resolve());
+const mockMirrorGitRepoPullRequestsToGitea = mock(() => Promise.resolve());
+const mockMirrorGitRepoLabelsToGitea = mock(() => Promise.resolve());
+const mockMirrorGitRepoMilestonesToGitea = mock(() => Promise.resolve());
 const mockGetGiteaRepoOwnerAsync = mock(() => Promise.resolve("starred"));
+const mockCreatePreSyncBundleBackup = mock(() =>
+  Promise.resolve({ bundlePath: "/tmp/mock.bundle" })
+);
+let mockShouldCreatePreSyncBackup = false;
+let mockShouldBlockSyncOnBackupFailure = true;
 
 // Mock the database module
 const mockDb = {
@@ -24,8 +33,14 @@ const mockDb = {
 
 mock.module("@/lib/db", () => ({
   db: mockDb,
+  users: {},
+  configs: {},
+  organizations: {},
   mirrorJobs: {},
-  repositories: {}
+  repositories: {},
+  events: {},
+  accounts: {},
+  sessions: {},
 }));
 
 // Mock config encryption
@@ -128,6 +143,36 @@ const mockHttpGet = mock(async (url: string, headers?: any) => {
       headers: new Headers()
     };
   }
+  if (url.includes("/api/v1/repos/starred/metadata-repo")) {
+    return {
+      data: {
+        id: 790,
+        name: "metadata-repo",
+        mirror: true,
+        owner: { login: "starred" },
+        mirror_interval: "8h",
+        private: false,
+      },
+      status: 200,
+      statusText: "OK",
+      headers: new Headers(),
+    };
+  }
+  if (url.includes("/api/v1/repos/starred/already-synced-repo")) {
+    return {
+      data: {
+        id: 791,
+        name: "already-synced-repo",
+        mirror: true,
+        owner: { login: "starred" },
+        mirror_interval: "8h",
+        private: false,
+      },
+      status: 200,
+      statusText: "OK",
+      headers: new Headers(),
+    };
+  }
   if (url.includes("/api/v1/repos/")) {
     throw new MockHttpError("Not Found", 404, "Not Found");
   }
@@ -201,6 +246,12 @@ mock.module("@/lib/http-client", () => ({
   HttpError: MockHttpError
 }));
 
+mock.module("@/lib/repo-backup", () => ({
+  createPreSyncBundleBackup: mockCreatePreSyncBundleBackup,
+  shouldCreatePreSyncBackup: () => mockShouldCreatePreSyncBackup,
+  shouldBlockSyncOnBackupFailure: () => mockShouldBlockSyncOnBackupFailure,
+}));
+
 // Now import the modules we're testing
 import { 
   getGiteaRepoInfo, 
@@ -224,8 +275,21 @@ describe("Enhanced Gitea Operations", () => {
     mockDb.insert.mockClear();
     mockDb.update.mockClear();
     mockMirrorGitHubReleasesToGitea.mockClear();
+    mockMirrorGitRepoIssuesToGitea.mockClear();
+    mockMirrorGitRepoPullRequestsToGitea.mockClear();
+    mockMirrorGitRepoLabelsToGitea.mockClear();
+    mockMirrorGitRepoMilestonesToGitea.mockClear();
     mockGetGiteaRepoOwnerAsync.mockClear();
     mockGetGiteaRepoOwnerAsync.mockImplementation(() => Promise.resolve("starred"));
+    mockHttpGet.mockClear();
+    mockHttpPost.mockClear();
+    mockHttpDelete.mockClear();
+    mockCreatePreSyncBundleBackup.mockClear();
+    mockCreatePreSyncBundleBackup.mockImplementation(() =>
+      Promise.resolve({ bundlePath: "/tmp/mock.bundle" })
+    );
+    mockShouldCreatePreSyncBackup = false;
+    mockShouldBlockSyncOnBackupFailure = true;
     // Reset tracking variables
     orgCheckCount = 0;
     orgTestContext = "";
@@ -426,6 +490,10 @@ describe("Enhanced Gitea Operations", () => {
           {
             getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
             mirrorGitHubReleasesToGitea: mockMirrorGitHubReleasesToGitea,
+            mirrorGitRepoIssuesToGitea: mockMirrorGitRepoIssuesToGitea,
+            mirrorGitRepoPullRequestsToGitea: mockMirrorGitRepoPullRequestsToGitea,
+            mirrorGitRepoLabelsToGitea: mockMirrorGitRepoLabelsToGitea,
+            mirrorGitRepoMilestonesToGitea: mockMirrorGitRepoMilestonesToGitea,
           }
         )
       ).rejects.toThrow("Repository non-mirror-repo is not a mirror. Cannot sync.");
@@ -470,6 +538,10 @@ describe("Enhanced Gitea Operations", () => {
         {
           getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
           mirrorGitHubReleasesToGitea: mockMirrorGitHubReleasesToGitea,
+          mirrorGitRepoIssuesToGitea: mockMirrorGitRepoIssuesToGitea,
+          mirrorGitRepoPullRequestsToGitea: mockMirrorGitRepoPullRequestsToGitea,
+          mirrorGitRepoLabelsToGitea: mockMirrorGitRepoLabelsToGitea,
+          mirrorGitRepoMilestonesToGitea: mockMirrorGitRepoMilestonesToGitea,
         }
       );
 
@@ -482,6 +554,249 @@ describe("Enhanced Gitea Operations", () => {
       expect(releaseCall.config.githubConfig?.token).toBe("github-token");
       expect(releaseCall.octokit).toBeDefined();
     });
+
+    test("blocks sync when pre-sync snapshot fails and blocking is enabled", async () => {
+      mockShouldCreatePreSyncBackup = true;
+      mockShouldBlockSyncOnBackupFailure = true;
+      mockCreatePreSyncBundleBackup.mockImplementation(() =>
+        Promise.reject(new Error("simulated backup failure"))
+      );
+
+      const config: Partial<Config> = {
+        userId: "user123",
+        githubConfig: {
+          username: "testuser",
+          token: "github-token",
+          privateRepositories: false,
+          mirrorStarred: true,
+        },
+        giteaConfig: {
+          url: "https://gitea.example.com",
+          token: "encrypted-token",
+          defaultOwner: "testuser",
+          mirrorReleases: false,
+          backupBeforeSync: true,
+          blockSyncOnBackupFailure: true,
+        },
+      };
+
+      const repository: Repository = {
+        id: "repo456",
+        name: "mirror-repo",
+        fullName: "user/mirror-repo",
+        owner: "user",
+        cloneUrl: "https://github.com/user/mirror-repo.git",
+        isPrivate: false,
+        isStarred: true,
+        status: repoStatusEnum.parse("mirrored"),
+        visibility: "public",
+        userId: "user123",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      await expect(
+        syncGiteaRepoEnhanced(
+          { config, repository },
+          {
+            getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
+            mirrorGitHubReleasesToGitea: mockMirrorGitHubReleasesToGitea,
+            mirrorGitRepoIssuesToGitea: mockMirrorGitRepoIssuesToGitea,
+            mirrorGitRepoPullRequestsToGitea: mockMirrorGitRepoPullRequestsToGitea,
+            mirrorGitRepoLabelsToGitea: mockMirrorGitRepoLabelsToGitea,
+            mirrorGitRepoMilestonesToGitea: mockMirrorGitRepoMilestonesToGitea,
+          }
+        )
+      ).rejects.toThrow("Snapshot failed; sync blocked to protect history.");
+
+      const mirrorSyncCalls = mockHttpPost.mock.calls.filter((call) =>
+        String(call[0]).includes("/mirror-sync")
+      );
+      expect(mirrorSyncCalls.length).toBe(0);
+    });
+
+    test("continues sync when pre-sync snapshot fails and blocking is disabled", async () => {
+      mockShouldCreatePreSyncBackup = true;
+      mockShouldBlockSyncOnBackupFailure = false;
+      mockCreatePreSyncBundleBackup.mockImplementation(() =>
+        Promise.reject(new Error("simulated backup failure"))
+      );
+
+      const config: Partial<Config> = {
+        userId: "user123",
+        githubConfig: {
+          username: "testuser",
+          token: "github-token",
+          privateRepositories: false,
+          mirrorStarred: true,
+        },
+        giteaConfig: {
+          url: "https://gitea.example.com",
+          token: "encrypted-token",
+          defaultOwner: "testuser",
+          mirrorReleases: false,
+          backupBeforeSync: true,
+          blockSyncOnBackupFailure: false,
+        },
+      };
+
+      const repository: Repository = {
+        id: "repo457",
+        name: "mirror-repo",
+        fullName: "user/mirror-repo",
+        owner: "user",
+        cloneUrl: "https://github.com/user/mirror-repo.git",
+        isPrivate: false,
+        isStarred: true,
+        status: repoStatusEnum.parse("mirrored"),
+        visibility: "public",
+        userId: "user123",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      const result = await syncGiteaRepoEnhanced(
+        { config, repository },
+        {
+          getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
+          mirrorGitHubReleasesToGitea: mockMirrorGitHubReleasesToGitea,
+          mirrorGitRepoIssuesToGitea: mockMirrorGitRepoIssuesToGitea,
+          mirrorGitRepoPullRequestsToGitea: mockMirrorGitRepoPullRequestsToGitea,
+          mirrorGitRepoLabelsToGitea: mockMirrorGitRepoLabelsToGitea,
+          mirrorGitRepoMilestonesToGitea: mockMirrorGitRepoMilestonesToGitea,
+        }
+      );
+
+      expect(result).toEqual({ success: true });
+      const mirrorSyncCalls = mockHttpPost.mock.calls.filter((call) =>
+        String(call[0]).includes("/mirror-sync")
+      );
+      expect(mirrorSyncCalls.length).toBe(1);
+    });
+
+    test("mirrors metadata components when enabled and not previously synced", async () => {
+      const config: Partial<Config> = {
+        userId: "user123",
+        githubConfig: {
+          username: "testuser",
+          token: "github-token",
+          privateRepositories: true,
+          mirrorStarred: false,
+        },
+        giteaConfig: {
+          url: "https://gitea.example.com",
+          token: "encrypted-token",
+          defaultOwner: "testuser",
+          mirrorReleases: true,
+          mirrorMetadata: true,
+          mirrorIssues: true,
+          mirrorPullRequests: true,
+          mirrorLabels: true,
+          mirrorMilestones: true,
+        },
+      };
+
+      const repository: Repository = {
+        id: "repo789",
+        name: "metadata-repo",
+        fullName: "user/metadata-repo",
+        owner: "user",
+        cloneUrl: "https://github.com/user/metadata-repo.git",
+        isPrivate: false,
+        isStarred: false,
+        status: repoStatusEnum.parse("mirrored"),
+        visibility: "public",
+        userId: "user123",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        metadata: null,
+      };
+
+      await syncGiteaRepoEnhanced(
+        { config, repository },
+        {
+          getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
+          mirrorGitHubReleasesToGitea: mockMirrorGitHubReleasesToGitea,
+          mirrorGitRepoIssuesToGitea: mockMirrorGitRepoIssuesToGitea,
+          mirrorGitRepoPullRequestsToGitea: mockMirrorGitRepoPullRequestsToGitea,
+          mirrorGitRepoLabelsToGitea: mockMirrorGitRepoLabelsToGitea,
+          mirrorGitRepoMilestonesToGitea: mockMirrorGitRepoMilestonesToGitea,
+        }
+      );
+
+      expect(mockMirrorGitHubReleasesToGitea).toHaveBeenCalledTimes(1);
+      expect(mockMirrorGitRepoIssuesToGitea).toHaveBeenCalledTimes(1);
+      expect(mockMirrorGitRepoPullRequestsToGitea).toHaveBeenCalledTimes(1);
+      expect(mockMirrorGitRepoMilestonesToGitea).toHaveBeenCalledTimes(1);
+      // Labels should be skipped because issues already import them
+      expect(mockMirrorGitRepoLabelsToGitea).not.toHaveBeenCalled();
+    });
+
+    test("continues incremental issue and PR syncing when metadata was previously synced", async () => {
+      const config: Partial<Config> = {
+        userId: "user123",
+        githubConfig: {
+          username: "testuser",
+          token: "github-token",
+          privateRepositories: true,
+          mirrorStarred: false,
+        },
+        giteaConfig: {
+          url: "https://gitea.example.com",
+          token: "encrypted-token",
+          defaultOwner: "testuser",
+          mirrorReleases: false,
+          mirrorMetadata: true,
+          mirrorIssues: true,
+          mirrorPullRequests: true,
+          mirrorLabels: true,
+          mirrorMilestones: true,
+        },
+      };
+
+      const repository: Repository = {
+        id: "repo790",
+        name: "already-synced-repo",
+        fullName: "user/already-synced-repo",
+        owner: "user",
+        cloneUrl: "https://github.com/user/already-synced-repo.git",
+        isPrivate: false,
+        isStarred: false,
+        status: repoStatusEnum.parse("mirrored"),
+        visibility: "public",
+        userId: "user123",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        metadata: JSON.stringify({
+          components: {
+            releases: true,
+            issues: true,
+            pullRequests: true,
+            labels: true,
+            milestones: true,
+          },
+          lastSyncedAt: new Date().toISOString(),
+        }),
+      };
+
+      await syncGiteaRepoEnhanced(
+        { config, repository },
+        {
+          getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
+          mirrorGitHubReleasesToGitea: mockMirrorGitHubReleasesToGitea,
+          mirrorGitRepoIssuesToGitea: mockMirrorGitRepoIssuesToGitea,
+          mirrorGitRepoPullRequestsToGitea: mockMirrorGitRepoPullRequestsToGitea,
+          mirrorGitRepoLabelsToGitea: mockMirrorGitRepoLabelsToGitea,
+          mirrorGitRepoMilestonesToGitea: mockMirrorGitRepoMilestonesToGitea,
+        }
+      );
+
+      expect(mockMirrorGitHubReleasesToGitea).not.toHaveBeenCalled();
+      expect(mockMirrorGitRepoIssuesToGitea).toHaveBeenCalledTimes(1);
+      expect(mockMirrorGitRepoPullRequestsToGitea).toHaveBeenCalledTimes(1);
+      expect(mockMirrorGitRepoLabelsToGitea).not.toHaveBeenCalled();
+      expect(mockMirrorGitRepoMilestonesToGitea).not.toHaveBeenCalled();
+    });
   });
 
   describe("handleExistingNonMirrorRepo", () => {

src/lib/gitea-enhanced.ts

@@ -15,10 +15,28 @@ import { httpPost, httpGet, httpPatch, HttpError } from "./http-client";
 import { db, repositories } from "./db";
 import { eq } from "drizzle-orm";
 import { repoStatusEnum } from "@/types/Repository";
+import {
+  createPreSyncBundleBackup,
+  shouldCreatePreSyncBackup,
+  shouldBlockSyncOnBackupFailure,
+  resolveBackupStrategy,
+  shouldBackupForStrategy,
+  shouldBlockSyncForStrategy,
+  strategyNeedsDetection,
+} from "./repo-backup";
+import { detectForcePush } from "./utils/force-push-detection";
+import {
+  parseRepositoryMetadataState,
+  serializeRepositoryMetadataState,
+} from "./metadata-state";
 
 type SyncDependencies = {
   getGiteaRepoOwnerAsync: typeof import("./gitea")["getGiteaRepoOwnerAsync"];
   mirrorGitHubReleasesToGitea: typeof import("./gitea")["mirrorGitHubReleasesToGitea"];
+  mirrorGitRepoIssuesToGitea: typeof import("./gitea")["mirrorGitRepoIssuesToGitea"];
+  mirrorGitRepoPullRequestsToGitea: typeof import("./gitea")["mirrorGitRepoPullRequestsToGitea"];
+  mirrorGitRepoLabelsToGitea: typeof import("./gitea")["mirrorGitRepoLabelsToGitea"];
+  mirrorGitRepoMilestonesToGitea: typeof import("./gitea")["mirrorGitRepoMilestonesToGitea"];
 };
 
 /**
@@ -242,9 +260,12 @@ export async function getOrCreateGiteaOrgEnhanced({
 export async function syncGiteaRepoEnhanced({
   config,
   repository,
+  skipForcePushDetection,
 }: {
   config: Partial<Config>;
   repository: Repository;
+  /** When true, skip force-push detection and blocking (used by approve-sync). */
+  skipForcePushDetection?: boolean;
 }, deps?: SyncDependencies): Promise<any> {
   try {
     if (!config.userId || !config.giteaConfig?.url || !config.giteaConfig?.token) {
@@ -305,6 +326,141 @@ export async function syncGiteaRepoEnhanced({
       throw new Error(`Repository ${repository.name} is not a mirror. Cannot sync.`);
     }
 
+    // ---- Smart backup strategy with force-push detection ----
+    const backupStrategy = resolveBackupStrategy(config);
+    let forcePushDetected = false;
+
+    if (backupStrategy !== "disabled") {
+      // Run force-push detection if the strategy requires it
+      // (skip when called from approve-sync to avoid re-blocking)
+      if (strategyNeedsDetection(backupStrategy) && !skipForcePushDetection) {
+        try {
+          const decryptedGithubToken = decryptedConfig.githubConfig?.token;
+          if (decryptedGithubToken) {
+            const fpOctokit = new Octokit({ auth: decryptedGithubToken });
+            const detectionResult = await detectForcePush({
+              giteaUrl: config.giteaConfig.url,
+              giteaToken: decryptedConfig.giteaConfig.token,
+              giteaOwner: repoOwner,
+              giteaRepo: repository.name,
+              octokit: fpOctokit,
+              githubOwner: repository.owner,
+              githubRepo: repository.name,
+            });
+
+            forcePushDetected = detectionResult.detected;
+
+            if (detectionResult.skipped) {
+              console.log(
+                `[Sync] Force-push detection skipped for ${repository.name}: ${detectionResult.skipReason}`,
+              );
+            } else if (forcePushDetected) {
+              const branchNames = detectionResult.affectedBranches
+                .map((b) => `${b.name} (${b.reason})`)
+                .join(", ");
+              console.warn(
+                `[Sync] Force-push detected on ${repository.name}: ${branchNames}`,
+              );
+            }
+          } else {
+            console.log(
+              `[Sync] Skipping force-push detection for ${repository.name}: no GitHub token`,
+            );
+          }
+        } catch (detectionError) {
+          // Fail-open: detection errors should never block sync
+          console.warn(
+            `[Sync] Force-push detection failed for ${repository.name}, proceeding with sync: ${
+              detectionError instanceof Error ? detectionError.message : String(detectionError)
+            }`,
+          );
+        }
+      }
+
+      // Check if sync should be blocked (block-on-force-push mode)
+      if (shouldBlockSyncForStrategy(backupStrategy, forcePushDetected)) {
+        const branchInfo = `Force-push detected; sync blocked for manual approval.`;
+
+        await db
+          .update(repositories)
+          .set({
+            status: "pending-approval",
+            updatedAt: new Date(),
+            errorMessage: branchInfo,
+          })
+          .where(eq(repositories.id, repository.id!));
+
+        await createMirrorJob({
+          userId: config.userId,
+          repositoryId: repository.id,
+          repositoryName: repository.name,
+          message: `Sync blocked for ${repository.name}: force-push detected`,
+          details: branchInfo,
+          status: "pending-approval",
+        });
+
+        console.warn(`[Sync] Sync blocked for ${repository.name}: pending manual approval`);
+        return { blocked: true, reason: branchInfo };
+      }
+
+      // Create backup if strategy says so
+      if (shouldBackupForStrategy(backupStrategy, forcePushDetected)) {
+        const cloneUrl =
+          repoInfo.clone_url ||
+          `${config.giteaConfig.url.replace(/\/$/, "")}/${repoOwner}/${repository.name}.git`;
+
+        try {
+          const backupResult = await createPreSyncBundleBackup({
+            config,
+            owner: repoOwner,
+            repoName: repository.name,
+            cloneUrl,
+            force: true, // Strategy already decided to backup; skip legacy gate
+          });
+
+          await createMirrorJob({
+            userId: config.userId,
+            repositoryId: repository.id,
+            repositoryName: repository.name,
+            message: `Snapshot created for ${repository.name}`,
+            details: `Pre-sync snapshot created at ${backupResult.bundlePath}.`,
+            status: "syncing",
+          });
+        } catch (backupError) {
+          const errorMessage =
+            backupError instanceof Error ? backupError.message : String(backupError);
+
+          await createMirrorJob({
+            userId: config.userId,
+            repositoryId: repository.id,
+            repositoryName: repository.name,
+            message: `Snapshot failed for ${repository.name}`,
+            details: `Pre-sync snapshot failed: ${errorMessage}`,
+            status: "failed",
+          });
+
+          if (shouldBlockSyncOnBackupFailure(config)) {
+            await db
+              .update(repositories)
+              .set({
+                status: repoStatusEnum.parse("failed"),
+                updatedAt: new Date(),
+                errorMessage: `Snapshot failed; sync blocked to protect history. ${errorMessage}`,
+              })
+              .where(eq(repositories.id, repository.id!));
+
+            throw new Error(
+              `Snapshot failed; sync blocked to protect history. ${errorMessage}`,
+            );
+          }
+
+          console.warn(
+            `[Sync] Snapshot failed for ${repository.name}, continuing because blockSyncOnBackupFailure=false: ${errorMessage}`,
+          );
+        }
+      }
+    }
+
     // Update mirror interval if needed
     if (config.giteaConfig?.mirrorInterval) {
       try {
@@ -330,36 +486,220 @@ export async function syncGiteaRepoEnhanced({
         Authorization: `token ${decryptedConfig.giteaConfig.token}`,
       });
 
+      const metadataState = parseRepositoryMetadataState(repository.metadata);
+      let metadataUpdated = false;
+      const skipMetadataForStarred =
+        repository.isStarred && config.githubConfig?.starredCodeOnly;
+      let metadataOctokit: Octokit | null = null;
+
+      const ensureOctokit = (): Octokit | null => {
+        if (metadataOctokit) {
+          return metadataOctokit;
+        }
+        if (!decryptedConfig.githubConfig?.token) {
+          return null;
+        }
+        metadataOctokit = new Octokit({
+          auth: decryptedConfig.githubConfig.token,
+        });
+        return metadataOctokit;
+      };
+
       const shouldMirrorReleases =
-        decryptedConfig.giteaConfig?.mirrorReleases &&
-        !(repository.isStarred && decryptedConfig.githubConfig?.starredCodeOnly);
+        !!config.giteaConfig?.mirrorReleases && !skipMetadataForStarred;
+      const shouldMirrorIssuesThisRun =
+        !!config.giteaConfig?.mirrorIssues &&
+        !skipMetadataForStarred;
+      const shouldMirrorPullRequests =
+        !!config.giteaConfig?.mirrorPullRequests &&
+        !skipMetadataForStarred;
+      const shouldMirrorLabels =
+        !!config.giteaConfig?.mirrorLabels &&
+        !skipMetadataForStarred &&
+        !shouldMirrorIssuesThisRun &&
+        !metadataState.components.labels;
+      const shouldMirrorMilestones =
+        !!config.giteaConfig?.mirrorMilestones &&
+        !skipMetadataForStarred &&
+        !metadataState.components.milestones;
 
       if (shouldMirrorReleases) {
-        if (!decryptedConfig.githubConfig?.token) {
+        const octokit = ensureOctokit();
+        if (!octokit) {
           console.warn(
             `[Sync] Skipping release mirroring for ${repository.name}: Missing GitHub token`
           );
         } else {
           try {
-            const octokit = new Octokit({ auth: decryptedConfig.githubConfig.token });
             await dependencies.mirrorGitHubReleasesToGitea({
-              config: decryptedConfig,
+              config,
               octokit,
               repository,
               giteaOwner: repoOwner,
               giteaRepoName: repository.name,
             });
-            console.log(`[Sync] Mirrored releases for ${repository.name} after sync`);
+            metadataState.components.releases = true;
+            metadataUpdated = true;
+            console.log(
+              `[Sync] Mirrored releases for ${repository.name} after sync`
+            );
           } catch (releaseError) {
             console.error(
               `[Sync] Failed to mirror releases for ${repository.name}: ${
-                releaseError instanceof Error ? releaseError.message : String(releaseError)
+                releaseError instanceof Error
+                  ? releaseError.message
+                  : String(releaseError)
               }`
             );
           }
         }
       }
 
+      if (shouldMirrorIssuesThisRun) {
+        const octokit = ensureOctokit();
+        if (!octokit) {
+          console.warn(
+            `[Sync] Skipping issue mirroring for ${repository.name}: Missing GitHub token`
+          );
+        } else {
+          try {
+            await dependencies.mirrorGitRepoIssuesToGitea({
+              config,
+              octokit,
+              repository,
+              giteaOwner: repoOwner,
+              giteaRepoName: repository.name,
+            });
+            metadataState.components.issues = true;
+            metadataState.components.labels = true;
+            metadataUpdated = true;
+            console.log(
+              `[Sync] Mirrored issues for ${repository.name} after sync`
+            );
+          } catch (issueError) {
+            console.error(
+              `[Sync] Failed to mirror issues for ${repository.name}: ${
+                issueError instanceof Error
+                  ? issueError.message
+                  : String(issueError)
+              }`
+            );
+          }
+        }
+      }
+
+      if (shouldMirrorPullRequests) {
+        const octokit = ensureOctokit();
+        if (!octokit) {
+          console.warn(
+            `[Sync] Skipping pull request mirroring for ${repository.name}: Missing GitHub token`
+          );
+        } else {
+          try {
+            await dependencies.mirrorGitRepoPullRequestsToGitea({
+              config,
+              octokit,
+              repository,
+              giteaOwner: repoOwner,
+              giteaRepoName: repository.name,
+            });
+            metadataState.components.pullRequests = true;
+            metadataUpdated = true;
+            console.log(
+              `[Sync] Mirrored pull requests for ${repository.name} after sync`
+            );
+          } catch (prError) {
+            console.error(
+              `[Sync] Failed to mirror pull requests for ${repository.name}: ${
+                prError instanceof Error ? prError.message : String(prError)
+              }`
+            );
+          }
+        }
+      }
+
+      if (shouldMirrorLabels) {
+        const octokit = ensureOctokit();
+        if (!octokit) {
+          console.warn(
+            `[Sync] Skipping label mirroring for ${repository.name}: Missing GitHub token`
+          );
+        } else {
+          try {
+            await dependencies.mirrorGitRepoLabelsToGitea({
+              config,
+              octokit,
+              repository,
+              giteaOwner: repoOwner,
+              giteaRepoName: repository.name,
+            });
+            metadataState.components.labels = true;
+            metadataUpdated = true;
+            console.log(
+              `[Sync] Mirrored labels for ${repository.name} after sync`
+            );
+          } catch (labelError) {
+            console.error(
+              `[Sync] Failed to mirror labels for ${repository.name}: ${
+                labelError instanceof Error
+                  ? labelError.message
+                  : String(labelError)
+              }`
+            );
+          }
+        }
+      } else if (
+        config.giteaConfig?.mirrorLabels &&
+        metadataState.components.labels
+      ) {
+        console.log(
+          `[Sync] Labels already mirrored for ${repository.name}; skipping`
+        );
+      }
+
+      if (shouldMirrorMilestones) {
+        const octokit = ensureOctokit();
+        if (!octokit) {
+          console.warn(
+            `[Sync] Skipping milestone mirroring for ${repository.name}: Missing GitHub token`
+          );
+        } else {
+          try {
+            await dependencies.mirrorGitRepoMilestonesToGitea({
+              config,
+              octokit,
+              repository,
+              giteaOwner: repoOwner,
+              giteaRepoName: repository.name,
+            });
+            metadataState.components.milestones = true;
+            metadataUpdated = true;
+            console.log(
+              `[Sync] Mirrored milestones for ${repository.name} after sync`
+            );
+          } catch (milestoneError) {
+            console.error(
+              `[Sync] Failed to mirror milestones for ${repository.name}: ${
+                milestoneError instanceof Error
+                  ? milestoneError.message
+                  : String(milestoneError)
+              }`
+            );
+          }
+        }
+      } else if (
+        config.giteaConfig?.mirrorMilestones &&
+        metadataState.components.milestones
+      ) {
+        console.log(
+          `[Sync] Milestones already mirrored for ${repository.name}; skipping`
+        );
+      }
+
+      if (metadataUpdated) {
+        metadataState.lastSyncedAt = new Date().toISOString();
+      }
+
       // Mark repo as "synced" in DB
       await db
         .update(repositories)
@@ -369,6 +709,9 @@ export async function syncGiteaRepoEnhanced({
           lastMirrored: new Date(),
           errorMessage: null,
           mirroredLocation: `${repoOwner}/${repository.name}`,
+          metadata: metadataUpdated
+            ? serializeRepositoryMetadataState(metadataState)
+            : repository.metadata ?? null,
         })
         .where(eq(repositories.id, repository.id!));
 
@@ -376,12 +719,12 @@ export async function syncGiteaRepoEnhanced({
         userId: config.userId,
         repositoryId: repository.id,
         repositoryName: repository.name,
-        message: `Successfully synced repository: ${repository.name}`,
-        details: `Repository ${repository.name} was synced with Gitea.`,
+        message: `Sync requested for repository: ${repository.name}`,
+        details: `Mirror sync was requested for ${repository.name}. Gitea/Forgejo performs the actual pull asynchronously; check remote logs for pull errors.`,
         status: "synced",
       });
 
-      console.log(`[Sync] Repository ${repository.name} synced successfully`);
+      console.log(`[Sync] Mirror sync requested for repository ${repository.name}`);
       return response.data;
     } catch (syncError) {
       if (syncError instanceof HttpError && syncError.status === 400) {

src/lib/gitea-starred-repos.test.ts

@@ -24,9 +24,14 @@ mock.module("@/lib/db", () => {
         values: mock(() => Promise.resolve())
       }))
     },
+    users: {},
+    configs: {},
     repositories: {},
     organizations: {},
-    events: {}
+    events: {},
+    mirrorJobs: {},
+    accounts: {},
+    sessions: {},
   };
 });
 
@@ -59,10 +64,16 @@ const mockGetOrCreateGiteaOrg = mock(async ({ orgName, config }: any) => {
 
 const mockMirrorGitHubOrgRepoToGiteaOrg = mock(async () => {});
 const mockIsRepoPresentInGitea = mock(async () => false);
+const mockMirrorGithubRepoToGitea = mock(async () => {});
+const mockGetGiteaRepoOwnerAsync = mock(async () => "starred");
+const mockGetGiteaRepoOwner = mock(() => "starred");
 
 mock.module("./gitea", () => ({
   getOrCreateGiteaOrg: mockGetOrCreateGiteaOrg,
   mirrorGitHubOrgRepoToGiteaOrg: mockMirrorGitHubOrgRepoToGiteaOrg,
+  mirrorGithubRepoToGitea: mockMirrorGithubRepoToGitea,
+  getGiteaRepoOwner: mockGetGiteaRepoOwner,
+  getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
   isRepoPresentInGitea: mockIsRepoPresentInGitea
 }));
 
@@ -226,4 +237,4 @@ describe("Starred Repository Error Handling", () => {
     });
   });
 
-});
+});