> ## Documentation Index
> Fetch the complete documentation index at: https://ulpi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Repository Management

> Connect, organize, and optimize documentation across all your repositories

# Manage Documentation Across All Your Repositories

**Your team has documentation scattered across 23 repositories. Frontend docs in one place. Backend in another. Infrastructure somewhere else.**

**Finding anything requires knowing which repo to search—and most new developers have no idea.**

ULPI fixes this by connecting all your repositories into one searchable knowledge base.

**This guide shows you:**

* 🔗 How to connect repositories (2 minutes per repo)
* ⚙️ Configure what gets indexed (exclude drafts, temp files, etc.)
* 🔄 Keep documentation automatically synced via webhooks
* 📊 Monitor indexing status and troubleshoot issues
* 🚀 Optimize for large organizations with 100+ repos

<Info>
  **First time?** Start with [Getting Started](/documentation/getting-started) for initial setup.

  **Want to search?** See [Search Features](/documentation/search-features) for query techniques.
</Info>

***

## The Problem: Documentation Chaos

**Your organization's reality:**

<Tabs>
  <Tab title="Before ULPI">
    **23 repositories, each with their own docs:**

    ```
    backend-api/         → API docs in /docs
    frontend-web/        → Component docs in /src/components
    mobile-app/          → Setup in README only
    infrastructure/      → Runbooks in /runbooks
    auth-service/        → Auth docs in wiki
    payment-service/     → No docs (comments only)
    notifications/       → Docs in Notion (not in repo)
    legacy-monolith/     → 5-year-old docs, probably outdated
    ... 15 more repos
    ```

    **To find "how to deploy":**

    1. Guess which repo has deployment docs
    2. Clone repo (if you don't have it)
    3. Search through `/docs`, `README.md`, `/runbooks`
    4. Find outdated doc from 2020
    5. Ask in Slack: "Where are the current deployment docs?"
    6. **20 minutes wasted**

    **New developer experience:**

    * Doesn't know repos exist
    * No idea where to look
    * Asks same questions for weeks
  </Tab>

  <Tab title="After ULPI">
    **One search across all 23 repositories:**

    ```
    Search: "How do I deploy to production?"

    Results (40ms):
    1. infrastructure/runbooks/deploy-production.md
    2. backend-api/docs/deployment.md
    3. frontend-web/README.md#deployment

    First result is exactly what you need.
    ```

    **New developer experience:**

    * Searches: "local development setup"
    * Gets setup guides from all relevant repos
    * Up and running in 30 minutes
    * **No Slack questions needed**

    **Time saved:** 19 minutes per search × 10 searches/day × 50 developers = **158 hours/day**
  </Tab>
</Tabs>

**ULPI makes all your documentation searchable—no matter which repo it's in.**

***

## Quick Start: Connect Your First Repository

**Get searchable docs in under 2 minutes:**

<Steps>
  <Step title="Navigate to Repositories">
    **Dashboard** → **Repositories** → Click **Connect Repository**

    <Info>
      **Pro tip:** Start with your most important repository (usually `backend-api` or main app)
    </Info>
  </Step>

  <Step title="Authorize Access">
    **Click "Connect GitHub" (or GitLab/Bitbucket)**

    ULPI requests **read-only** access:

    * ✅ Read repository contents
    * ✅ Register webhooks (for auto-sync)
    * ❌ **No write access** (cannot modify code)

    **Security:** OAuth with encrypted token storage. Revocable anytime from GitHub settings.
  </Step>

  <Step title="Select Repositories">
    **Choose connection strategy:**

    <Tabs>
      <Tab title="Individual Repos (Recommended)">
        **Best for first-time setup:**

        1. Check boxes next to 2-3 important repos
        2. Click **Connect Selected**
        3. See ULPI in action before connecting everything

        **Recommended:**

        * Main application repo
        * Backend API repo
        * Infrastructure/deployment repo

        **Why start small?** Verify ULPI works well before organization-wide rollout.
      </Tab>

      <Tab title="All Repositories">
        **Best for org-wide deployment:**

        1. Toggle **Select All Repositories**
        2. Click **Connect All**
        3. All current + future repos automatically connected

        **Use case:** You're sold on ULPI, want comprehensive search immediately

        <Warning>
          **Large orgs (100+ repos):** Initial indexing takes 15-30 minutes. Consider starting with critical repos first.
        </Warning>
      </Tab>

      <Tab title="By Organization">
        **Best for multi-org setups:**

        1. Use **Organization filter** dropdown
        2. Select specific GitHub org
        3. Choose repos from that org only

        **Example:** You're part of:

        * `acme-corp` (work)
        * `open-source-project` (personal)
        * `consulting-client` (contract)

        Only connect `acme-corp` repositories.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Wait for Indexing">
    **ULPI automatically indexes your documentation:**

    **What's happening:**

    * Discovering all documentation files
    * Parsing Markdown content
    * Generating semantic embeddings
    * Building search index

    **Time estimates:**

    | Repository Size      | Files         | Indexing Time |
    | -------------------- | ------------- | ------------- |
    | Small (starter)      | Less than 100 | 30-60 seconds |
    | Medium (typical app) | 100-1,000     | 2-5 minutes   |
    | Large (monorepo)     | 1,000-10,000  | 5-15 minutes  |

    **You can configure MCP while waiting!** Jump to [Getting Started](/documentation/getting-started) Step 3.
  </Step>

  <Step title="Verify Indexing Complete">
    **Status changes from "Indexing..." to "✅ Indexed"**

    **Verify search works:**

    1. Ask your AI assistant: "How do I set up local development?"
    2. Should return results from your repository
    3. Click the GitHub link to verify it's YOUR docs

    <Check>
      **Success!** Your documentation is now searchable by AI.
    </Check>
  </Step>
</Steps>

**Total time:** 2 minutes + automatic indexing

***

## Supported Git Platforms

**ULPI works with all major Git providers:**

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" color="#10b981">
    **Full support:**

    * GitHub.com (public and private)
    * GitHub Enterprise Server (self-hosted)
    * Organizations and personal accounts
    * All repository types

    **Setup:** OAuth connection (1 click)

    **Webhooks:** Automatic registration
  </Card>

  <Card title="GitLab" icon="gitlab" color="#f59e0b">
    **Full support:**

    * GitLab.com
    * Self-hosted GitLab (CE and EE)
    * Groups and subgroups
    * Project access tokens

    **Setup:** OAuth or access token

    **Webhooks:** Automatic registration
  </Card>

  <Card title="Bitbucket" icon="bitbucket" color="#3b82f6">
    **Full support:**

    * Bitbucket Cloud
    * Bitbucket Server (self-hosted)
    * Workspaces and projects
    * Repository access keys

    **Setup:** OAuth connection

    **Webhooks:** Automatic registration
  </Card>

  <Card title="Gitea / Gogs" icon="code-branch" color="#8b5cf6">
    **Full support:**

    * Self-hosted Gitea
    * Gogs instances
    * Organizations

    **Setup:** Access token

    **Webhooks:** Manual configuration required

    [Setup guide →](/documentation/repositories#gitea-setup)
  </Card>
</CardGroup>

<Accordion title="Self-Hosted Git Servers">
  **Requirements for self-hosted instances:**

  1. **Publicly accessible URL** (ULPI needs to reach your server)
     * OR: VPN connection to ULPI (Enterprise plan)
     * OR: Webhook proxy (we can help set this up)

  2. **API access enabled**
     * Most modern Git servers have API enabled by default

  3. **Webhook support**
     * For auto-sync on git push
     * Manual re-indexing available if webhooks aren't possible

  **Enterprise support:** Contact [sales@ulpi.io](mailto:sales@ulpi.io) for VPN peering or on-premise deployment.
</Accordion>

***

## What Gets Indexed (and What Doesn't)

**ULPI is smart about what to index:**

### Automatically Included

<Tabs>
  <Tab title="Documentation Files">
    **Primary documentation:**

    ```
    ✅ README.md (root and all subdirectories)
    ✅ docs/ directory (all Markdown files)
    ✅ documentation/ directory
    ✅ .github/ directory (CONTRIBUTING.md, ISSUE_TEMPLATE, etc.)
    ✅ All .md and .mdx files anywhere
    ✅ CONTRIBUTING.md, CODE_OF_CONDUCT.md
    ✅ CHANGELOG.md, SECURITY.md
    ✅ Architecture Decision Records (ADRs)
    ```

    **Example structure:**

    ```
    myrepo/
    ├── README.md                    ✅ Indexed
    ├── docs/
    │   ├── getting-started.md       ✅ Indexed
    │   ├── api/
    │   │   └── authentication.md    ✅ Indexed
    │   └── guides/
    │       └── deployment.md        ✅ Indexed
    ├── .github/
    │   ├── CONTRIBUTING.md          ✅ Indexed
    │   └── pull_request_template.md ✅ Indexed
    ```
  </Tab>

  <Tab title="Code Comments (Optional)">
    **Can be enabled per repository:**

    ```javascript theme={null}
    /**
     * Authenticates user with OAuth 2.0
     * ✅ This JSDoc comment can be indexed
     *
     * @param {string} token - OAuth token
     * @returns {User} Authenticated user object
     */
    function authenticateUser(token) {
      // Regular comments are NOT indexed
      return validateToken(token);
    }
    ```

    **Supported comment types:**

    * JSDoc (JavaScript/TypeScript)
    * PHPDoc (PHP)
    * Javadoc (Java)
    * Docstrings (Python)
    * XML comments (C#)

    **When to enable:**

    * ✅ You have well-documented code
    * ✅ Code comments contain architecture decisions
    * ✅ API endpoints documented in code
    * ❌ Don't enable if comments are messy or incomplete

    **To enable:** Repository settings → **Index code comments**
  </Tab>

  <Tab title="Wiki Pages (Optional)">
    **GitHub/GitLab wikis can be indexed:**

    ```
    ✅ Home.md
    ✅ Setup-Guide.md
    ✅ Troubleshooting.md
    ✅ All wiki pages
    ```

    **When to enable:**

    * ✅ You actively maintain wiki
    * ✅ Wiki has important documentation
    * ✅ Wiki is up-to-date
    * ❌ Don't enable if wiki is outdated or abandoned

    **To enable:** Repository settings → **Index wiki pages**

    <Info>
      **Pro tip:** Consider migrating wiki to `/docs` directory for better version control.
    </Info>
  </Tab>
</Tabs>

### Automatically Excluded

**Files that are never indexed:**

<Tabs>
  <Tab title="Build Artifacts">
    ```
    ❌ node_modules/
    ❌ vendor/
    ❌ dist/
    ❌ build/
    ❌ .next/
    ❌ out/
    ❌ target/
    ❌ .cache/
    ```

    **Why excluded:** Generated files, not actual documentation
  </Tab>

  <Tab title="Binary Files">
    ```
    ❌ *.pdf
    ❌ *.docx
    ❌ *.pptx
    ❌ *.png, *.jpg, *.svg
    ❌ *.zip, *.tar.gz
    ```

    **Why excluded:** Can't extract meaningful text for semantic search

    **Workaround:** Convert to Markdown for indexing
  </Tab>

  <Tab title="Git Internals">
    ```
    ❌ .git/
    ❌ .gitignore
    ❌ .gitattributes
    ```

    **Why excluded:** Not documentation
  </Tab>

  <Tab title="Large Files">
    ```
    ❌ Files >10MB
    ```

    **Why excluded:** Too large to process efficiently

    **Workaround:** Split into smaller files
  </Tab>
</Tabs>

### Custom Exclusions with .ulpiignore

**Exclude specific files or patterns:**

Create `.ulpiignore` in repository root:

```bash theme={null}
# .ulpiignore (syntax like .gitignore)

# Exclude generated API docs
/docs/api/generated/
/docs/auto-generated/

# Exclude drafts and WIP docs
**/drafts/**
**/*.draft.md
**/*.wip.md

# Exclude old/deprecated docs
/docs/archive/
/docs/deprecated/

# Exclude specific files
CHANGELOG.md          # Too noisy for search
TODO.md               # Internal only
NOTES.md              # Scratchpad

# Exclude translations (if you only want English)
/docs/i18n/
/docs/locales/

# Include specific files (negate exclusion)
!docs/archive/important-historical-doc.md
```

**Pattern syntax:**

* `*` - Match any characters in filename
* `**` - Match any directories
* `!` - Negate pattern (include files that would be excluded)
* `/` - Match from repo root

**To apply changes:**

1. Commit `.ulpiignore` to repository
2. Push to main branch
3. Dashboard → Repository → **Re-Index**

**Verify exclusions:** Repository details → **Indexed Files** → Search for filename

***

## Automatic Sync via Webhooks

**Your documentation stays up-to-date automatically:**

### How Webhooks Work

<Tabs>
  <Tab title="Automatic Flow">
    **What happens when you push:**

    ```mermaid theme={null}
    sequenceDiagram
        participant Dev as Developer
        participant Git as GitHub/GitLab
        participant ULPI as ULPI API
        participant Index as Search Index

        Dev->>Git: git push origin main
        Git->>ULPI: Webhook: "docs/auth.md changed"
        ULPI->>ULPI: Queue re-index job
        ULPI->>Git: Fetch changed file
        Git-->>ULPI: File contents
        ULPI->>Index: Update search index
        Index-->>ULPI: Indexed
        Note over ULPI: Cache invalidated
        Note over Index: AI sees updated docs
    ```

    **Timeline:**

    * **Less than 1 second:** Webhook received
    * **5-10 seconds:** Job queued and fetched
    * **20-40 seconds:** Re-indexed
    * **30-60 seconds:** Searchable by AI

    **Total:** 30-60 seconds from push to searchable
  </Tab>

  <Tab title="What Triggers Re-Index">
    **Full re-index (slow):**

    * New documentation directory created
    * Branch created/deleted
    * `.ulpiignore` file modified
    * Manual trigger from dashboard

    **Partial re-index (fast):**

    * Existing Markdown file modified
    * Documentation file renamed
    * Documentation file deleted

    **No re-index:**

    * Code files changed (`.js`, `.php`, `.py`)
    * Build artifacts updated
    * Files in `.ulpiignore` changed
    * Non-documentation changes

    **Smart indexing:** ULPI only re-processes changed files, not entire repository.
  </Tab>

  <Tab title="Setup (Usually Automatic)">
    **ULPI registers webhooks automatically when you connect a repository.**

    **Verify webhook is active:**

    1. Dashboard → Repositories → Select repo
    2. Look for **"Webhook: Active ✅"**

    **If webhook shows "Inactive ❌":**

    * You may need admin access to register webhooks
    * Firewall may be blocking ULPI
    * Manual setup required (see next tab)
  </Tab>

  <Tab title="Manual Setup (If Needed)">
    **If automatic webhook setup fails:**

    <Steps>
      <Step title="Get Webhook URL">
        Dashboard → Repository details → **Webhook Settings**

        Copy webhook URL:

        ```
        https://api.ulpi.io/api/webhooks/vcs/github/{your-repo-id}
        ```
      </Step>

      <Step title="Add to GitHub/GitLab">
        **GitHub:**

        1. Repository → Settings → Webhooks → Add webhook
        2. Payload URL: (paste webhook URL)
        3. Content type: `application/json`
        4. Events: Select "Just the push event"
        5. Active: ✅ Checked
        6. Add webhook

        **GitLab:**

        1. Project → Settings → Webhooks
        2. URL: (paste webhook URL)
        3. Trigger: Push events, Tag push events
        4. Enable SSL verification: ✅
        5. Add webhook
      </Step>

      <Step title="Verify in ULPI">
        Push a test change to docs:

        ```bash theme={null}
        echo "test" >> README.md
        git commit -am "test webhook"
        git push
        ```

        Dashboard → Repository → **Last webhook:** should update within 10 seconds
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Accordion title="Troubleshooting: Webhooks Not Firing">
  **Symptoms:** Push changes, but search results don't update

  **Check webhook status:**

  1. Dashboard → Repositories → Select repo
  2. Look for "Webhook: Active ✅" or "Webhook: Inactive ❌"

  **Common issues:**

  1. **Insufficient permissions**
     * Need **admin** or **write** access to register webhooks
     * Ask repo admin to grant access
     * Or: Ask admin to manually add webhook

  2. **Firewall blocking ULPI**
     * Corporate firewall blocks `api.ulpi.io`
     * Whitelist: `*.ulpi.io` in firewall rules
     * Contact IT for approval

  3. **Webhook deleted manually**
     * Someone deleted webhook from GitHub/GitLab settings
     * Reconnect repository to re-register webhook

  4. **Rate limiting (GitHub)**
     * Hit GitHub API rate limit (5,000 requests/hour)
     * Wait 1 hour and try again
     * Or: Manually trigger re-index

  **Manual workaround:** Repository details → **Re-Index** button (forces re-index without webhook)
</Accordion>

***

## Repository Status & Monitoring

**Track indexing status for all repositories:**

### Status Indicators

<Tabs>
  <Tab title="✅ Indexed (Ready)">
    **Status:** Indexed

    **Meaning:** All documentation is indexed and searchable

    **What you can do:**

    * Search works normally
    * AI assistants have access
    * Webhooks auto-sync on push

    **Action:** None needed—everything working
  </Tab>

  <Tab title="🔄 Indexing (In Progress)">
    **Status:** Indexing...

    **Meaning:** Currently processing files

    **When this happens:**

    * First-time connection
    * Manual re-index triggered
    * Large webhook update (100+ files changed)

    **Duration:**

    | Files         | Time    |
    | ------------- | ------- |
    | Less than 100 | 30-60s  |
    | 100-1,000     | 2-5min  |
    | 1,000-10,000  | 5-15min |

    **Action:** Wait for completion (check back in 2-5 minutes)

    **Progress:** Dashboard shows "47% complete (234/500 files)"
  </Tab>

  <Tab title="❌ Failed (Error)">
    **Status:** Failed

    **Meaning:** Error occurred during indexing

    **Common causes:**

    * **Access revoked:** Re-authenticate with GitHub/GitLab
    * **Repository deleted:** Disconnect and reconnect
    * **API rate limit:** Wait 1 hour, then retry
    * **Invalid Markdown:** Check for malformed files
    * **Network error:** Temporary issue, retry

    **Action:**

    1. Click **View Error Details**
    2. Read error message
    3. Fix issue (see troubleshooting below)
    4. Click **Retry Indexing**

    **Error log:** Repository details → **Error Log** → See full stack trace
  </Tab>

  <Tab title="⏸️ Paused (Disabled)">
    **Status:** Paused

    **Meaning:** Indexing temporarily disabled

    **When to use:**

    * Large documentation refactor in progress
    * Migrating repository
    * Temporarily reduce API usage
    * Testing changes before indexing

    **What happens:**

    * Existing search results still available
    * New changes NOT indexed
    * Webhooks NOT processed

    **Action:** Resume indexing when ready:

    * Repository details → **Resume Indexing**
  </Tab>

  <Tab title="⚠️ Webhook Inactive">
    **Status:** Indexed (Webhook Inactive)

    **Meaning:** Docs are indexed, but auto-sync is disabled

    **Impact:**

    * Search works for current docs
    * New changes WON'T auto-update
    * Must manually re-index after pushes

    **Causes:**

    * Insufficient permissions to register webhook
    * Webhook was manually deleted
    * Corporate firewall blocking webhooks

    **Action:** Fix webhook (see manual setup above) or use manual re-indexing
  </Tab>
</Tabs>

### Repository Statistics

**View detailed metrics:**

<Tabs>
  <Tab title="Files & Content">
    **What's indexed:**

    ```
    Total files indexed:     247
    ├── Markdown files:      198
    ├── README files:        32
    ├── Code comments:       0 (disabled)
    └── Wiki pages:          17

    Total size:              4.2 MB
    Average file size:       17 KB
    Largest file:            156 KB (docs/api-reference.md)

    Total chunks:            1,234
    Average chunks/file:     5.2
    ```

    **Use this to:**

    * Verify all expected docs are indexed
    * Identify large files that might need splitting
    * See if code comments should be enabled
  </Tab>

  <Tab title="Activity & Usage">
    **Indexing activity:**

    ```
    Last indexed:            2 hours ago
    Last webhook:            15 minutes ago
    Total re-indexes:        47 (since connection)

    Searches (last 30 days):
    ├── Total searches:      1,247
    ├── Searches/day:        41 avg
    └── Top queries:
        1. "deployment guide"      (89 searches)
        2. "API authentication"    (67 searches)
        3. "local setup"           (54 searches)
    ```

    **Use this to:**

    * See which docs are most searched
    * Identify documentation gaps
    * Verify webhooks are working
  </Tab>

  <Tab title="Performance Metrics">
    **Search performance:**

    ```
    Indexing time:           1m 23s
    Search latency:          42ms avg
    Cache hit rate:          78%

    Webhook processing:
    ├── Avg processing time: 45s
    ├── Fastest:             12s
    └── Slowest:             3m 14s (large refactor)

    Token efficiency:
    ├── Avg tokens/search:   2,340
    ├── vs full docs:        58,000
    └── Efficiency:          25x fewer tokens
    ```

    **Use this to:**

    * Monitor search speed
    * Optimize indexing settings
    * Report ROI to management
  </Tab>

  <Tab title="Health & Errors">
    **Error tracking:**

    ```
    Status:                  Healthy ✅

    Recent issues:           None

    Historical errors (last 30 days):
    ├── Total errors:        2
    ├── Rate limit errors:   1 (Nov 8)
    └── Network errors:      1 (Nov 3)

    Success rate:            99.7%
    Uptime:                  100%
    ```

    **Use this to:**

    * Spot patterns in failures
    * Proactively address issues
    * Provide data for support tickets
  </Tab>
</Tabs>

***

## Advanced Repository Management

**For teams managing many repositories:**

### Multi-Branch Indexing

**Index multiple branches simultaneously:**

<Accordion title="Use Cases for Multi-Branch Indexing">
  **When to enable:**

  1. **Review docs before merging:**
     * Index `develop` branch
     * Search docs in PR before merge
     * Verify documentation is complete

  2. **Compare documentation across versions:**
     * Index `v1.x` and `v2.x` branches
     * Search old docs: `"API guide" branch:v1.x`
     * Help users on older versions

  3. **Pre-release documentation:**
     * Index feature branches
     * Internal teams see upcoming features
     * External docs stay on `main` only

  **Available on:** Pro and Enterprise plans
</Accordion>

<Steps>
  <Step title="Enable Multi-Branch">
    Repository settings → **Branches** → **Enable multi-branch indexing**
  </Step>

  <Step title="Add Branches">
    Click **Add Branch** and configure:

    **Specific branch:**

    ```
    develop
    staging
    production
    ```

    **Branch patterns:**

    ```
    feature/*        # All feature branches
    release/*        # All release branches
    hotfix/*         # All hotfix branches
    ```

    **Version branches:**

    ```
    v1.x
    v2.x
    v3.x
    ```
  </Step>

  <Step title="Search Specific Branches">
    **Query syntax:**

    ```
    "API changes" branch:develop
    "deployment" branch:v2.x
    "new features" branch:feature/oauth-upgrade
    ```

    **Compare branches:**

    ```
    Search in main:    "authentication guide" branch:main
    Search in develop: "authentication guide" branch:develop
    ```

    See differences between production and development docs.
  </Step>
</Steps>

<Warning>
  **Cost consideration:** Each branch counts as separate repository for indexing quota.

  * 1 repo + 2 branches = 3 repos for billing
  * Consider which branches are truly needed
</Warning>

### Organization-Wide Deployment

**Best practices for rolling out ULPI across large organizations:**

<AccordionGroup>
  <Accordion title="Phase 1: Pilot (Weeks 1-2)" icon="flag">
    **Start with 3-5 critical repositories:**

    **Recommended pilot repos:**

    * ✅ Main application (most searched)
    * ✅ Backend API (well-documented)
    * ✅ Infrastructure/runbooks (high value)

    **Goals:**

    * Verify ULPI works with your setup
    * Gather feedback from early adopters
    * Identify documentation gaps
    * Measure search usage metrics

    **Success criteria:**

    * 80%+ of searches return relevant results
    * AI assistants successfully use docs
    * 5+ active users searching daily
  </Accordion>

  <Accordion title="Phase 2: Expand (Weeks 3-4)" icon="arrow-up">
    **Connect 10-20 additional repositories:**

    **Prioritize by:**

    1. **High traffic** - Most developers interact with
    2. **Well-documented** - Has quality docs to index
    3. **Critical services** - Auth, payments, core APIs

    **Communication:**

    * Announce in eng-all Slack
    * Share pilot success metrics
    * Provide ULPI setup guide
    * Offer office hours for questions

    **Monitor:**

    * Search volume per repository
    * Which docs get searched most
    * Error rates and indexing issues
  </Accordion>

  <Accordion title="Phase 3: Organization-Wide (Week 5+)" icon="building">
    **Connect all remaining repositories:**

    **Bulk connection options:**

    1. **Automatic org-wide:**
       * Settings → **Connect all organization repositories**
       * Includes future repos automatically

    2. **Selective by team:**
       * Frontend team: Connect frontend repos
       * Backend team: Connect backend repos
       * etc.

    **Governance:**

    * Designate ULPI admins per team
    * Create `.ulpiignore` guidelines
    * Document best practices
    * Regular audits of indexed repos

    **Training:**

    * Record demo video
    * Write internal search tips guide
    * Add to onboarding checklist
  </Accordion>

  <Accordion title="Ongoing Maintenance" icon="rotate">
    **Monthly tasks:**

    * Review repositories with failed indexing
    * Archive disconnected old repos
    * Update documentation standards
    * Review most-searched queries (find doc gaps)

    **Quarterly:**

    * Audit `.ulpiignore` files across repos
    * Review search analytics
    * Survey developer satisfaction
    * Optimize slow-indexing repos

    **Annually:**

    * Review organization-wide metrics
    * Calculate ROI (time saved)
    * Plan documentation improvements
  </Accordion>
</AccordionGroup>

### Repository Collections

**Group related repositories for easier management:**

<Tabs>
  <Tab title="By Team">
    **Frontend Collection:**

    ```
    - web-app
    - mobile-app
    - component-library
    - design-system
    ```

    **Backend Collection:**

    ```
    - api-gateway
    - auth-service
    - payment-service
    - notification-service
    ```

    **Use:** Search only frontend docs when working on UI
  </Tab>

  <Tab title="By Environment">
    **Production Services:**

    ```
    - production-apis
    - production-infrastructure
    - production-runbooks
    ```

    **Development/Staging:**

    ```
    - dev-environments
    - staging-configs
    - testing-docs
    ```

    **Use:** Separate prod docs from dev/staging
  </Tab>

  <Tab title="By Product">
    **Product A:**

    ```
    - product-a-frontend
    - product-a-backend
    - product-a-mobile
    ```

    **Product B:**

    ```
    - product-b-api
    - product-b-admin
    ```

    **Use:** Multi-product companies keep docs separated
  </Tab>
</Tabs>

**Create collection:**

1. Dashboard → Collections → **Create Collection**
2. Name: "Frontend Repos"
3. Add repositories to collection
4. Share collection with team

**Search within collection:**

```
"authentication" collection:frontend
```

***

## Troubleshooting Common Issues

<AccordionGroup>
  <Accordion title="🔍 Documentation Not Updating After Push" icon="circle-exclamation">
    **Symptom:** Pushed changes to docs, but search results are stale

    **Diagnosis checklist:**

    <Steps>
      <Step title="Check Webhook Status">
        Dashboard → Repository → Look for "Webhook: Active ✅"

        **If inactive:**

        * Re-register webhook (see manual setup above)
        * Check permissions (need admin access)
      </Step>

      <Step title="Verify File Location">
        **Is file in indexed directory?**

        * `/docs/**/*.md` ✅
        * `/documentation/**/*.md` ✅
        * `README.md` ✅
        * `/src/utils/README.md` ✅
        * `/temp/draft.md` ❌ (if in `.ulpiignore`)

        **Check:** Repository → **Indexed Files** → Search for your file
      </Step>

      <Step title="Check .ulpiignore">
        ```bash theme={null}
        # Check if file is excluded
        cat .ulpiignore

        # Common issue: excluded too broadly
        /docs/  # ❌ Excludes ALL docs
        /docs/drafts/  # ✅ Excludes only drafts
        ```

        **Fix:** Update `.ulpiignore`, commit, re-index
      </Step>

      <Step title="Verify Branch">
        **Pushing to indexed branch?**

        Most repos index `main` only.

        ```bash theme={null}
        # Check current branch
        git branch

        # If on different branch:
        git checkout main
        git merge your-feature-branch
        git push origin main
        ```

        **Or:** Enable multi-branch indexing for your branch
      </Step>

      <Step title="Manual Re-Index">
        **Force re-index as last resort:**

        Repository details → **Re-Index** button

        **This triggers:**

        * Full re-scan of repository
        * Re-processing of all docs
        * Cache invalidation

        **Time:** 30s - 5min depending on repo size
      </Step>
    </Steps>

    **Still not working?** Contact support with:

    * Repository name
    * File path that's not updating
    * Last push timestamp
    * Webhook status
  </Accordion>

  <Accordion title="⏱️ Slow Indexing (Taking >10 Minutes)" icon="clock">
    **Normal indexing times:**

    * Less than 100 files: 30s - 1min ✅
    * 100-1,000 files: 1-3min ✅
    * 1,000-10,000 files: 3-5min ✅
    * 10,000+ files: 5-15min ⚠️

    **If taking much longer:**

    **1. Check file count:**

    ```
    Dashboard → Repository → "Total files: 47,234"
    ```

    **Monorepo with many docs?** Consider:

    * Using `.ulpiignore` to exclude unneeded docs
    * Splitting into multiple repos
    * Indexing only `/docs` directory

    **2. Check for large files:**

    ```
    Dashboard → Repository → "Largest file: 45 MB"
    ```

    **Files >10MB are skipped.** If many large files:

    * Split into smaller files
    * Convert large PDFs to Markdown
    * Use `.ulpiignore` to exclude

    **3. Check network issues:**

    * ULPI must fetch all files from GitHub/GitLab
    * Slow network = slow indexing
    * **Enterprise:** Use VPC peering for faster access

    **4. Check GitHub API rate limits:**

    ```
    https://api.github.com/rate_limit
    ```

    **If limited:** Wait 1 hour and retry

    **5. Contact support:**

    * If >10,000 files: We can optimize your indexing
    * If >30min: Something is wrong, we'll investigate
  </Accordion>

  <Accordion title="❌ Indexing Failed (Error)" icon="triangle-exclamation">
    **Click error message for details. Common errors:**

    **"Access Denied" / "401 Unauthorized":**

    * OAuth token expired or revoked
    * **Fix:** Reconnect repository (re-authenticate)

    **"Repository Not Found" / "404":**

    * Repository deleted or renamed
    * **Fix:** Disconnect old repo, connect new one

    **"Rate Limit Exceeded":**

    * Hit GitHub API limit (5,000 requests/hour)
    * **Fix:** Wait 1 hour, retry automatically

    **"Invalid Markdown Syntax":**

    * Malformed Markdown file causing parser error
    * **Fix:** Check error log for file name, fix syntax

    **"Network Error" / "Timeout":**

    * Temporary network issue
    * **Fix:** Retry indexing (usually resolves itself)

    **"Webhook Payload Too Large":**

    * Pushed >1,000 files at once
    * **Fix:** Manual re-index (handles large changes)

    **View full error:**

    * Repository details → **Error Log**
    * Copy error message for support ticket
  </Accordion>

  <Accordion title="📄 Missing Files (Expected File Not Indexed)" icon="file-slash">
    **File not showing up in search?**

    **Checklist:**

    1. **Is it a Markdown file?**
       * ✅ `.md`, `.mdx`
       * ❌ `.txt` (unless in `/docs`)
       * ❌ `.pdf`, `.docx`

    2. **Is it in indexed directory?**
       * ✅ `/docs/`, `README.md`, `/documentation/`
       * ❌ `/temp/`, `/private/` (unless explicitly included)

    3. **Not in `.ulpiignore`?**
       ```bash theme={null}
       # Check exclusions
       cat .ulpiignore
       ```

    4. **File not empty?**
       ```bash theme={null}
       # Check file size
       ls -lh docs/my-file.md
       # Should be >0 bytes
       ```

    5. **UTF-8 encoding?**
       ```bash theme={null}
       # Check encoding
       file -I docs/my-file.md
       # Should show: charset=utf-8
       ```

    **Verify file was indexed:**

    * Repository details → **Indexed Files**
    * Search for filename
    * If not listed → Check above conditions

    **Force inclusion:**

    * Add to `.ulpiignore` with negation:
      ```
      # Include specific file
      !temp/important-doc.md
      ```
  </Accordion>

  <Accordion title="🔐 Can't Access Private Repository" icon="lock">
    **Symptoms:** Repository shows "Access Denied"

    **For personal repos:**

    1. Dashboard → Settings → **Git Connections**
    2. Click **Reconnect GitHub**
    3. Authorize access to **private repositories**
    4. Select repository again

    **For organization repos:**

    1. **Check org approval:**
       * GitHub → Settings → Applications → ULPI
       * If "Pending approval" → Ask org admin to approve

    2. **Request org admin approval:**
       * Send to admin: `github.com/orgs/YOUR_ORG/settings/oauth_application_policy`
       * Admin: Find "ULPI Documentation"
       * Admin: Click "Grant access"

    3. **Verify you have access:**
       * You must have **Read** access to repository
       * Check: `github.com/YOUR_ORG/REPO/settings/access`

    **Still not working?**

    * Try disconnecting and reconnecting repository
    * Verify OAuth token has correct scopes
    * Contact support: [support@ulpi.io](mailto:support@ulpi.io)
  </Accordion>

  <Accordion title="⚠️ Webhook Inactive (Auto-Sync Disabled)" icon="bell-slash">
    **Symptom:** Status shows "Webhook: Inactive ❌"

    **Impact:**

    * Docs are searchable (current version)
    * New changes WON'T auto-update
    * Must manually re-index after each push

    **Common causes:**

    **1. Insufficient permissions:**

    * Need **admin** or **write** access
    * **Fix:** Ask repo admin to grant access

    **2. Firewall blocking:**

    * Corporate firewall blocks `api.ulpi.io`
    * **Fix:** Whitelist `*.ulpi.io` in firewall

    **3. Webhook manually deleted:**

    * Someone removed webhook from GitHub
    * **Fix:** Reconnect repository to re-register

    **4. GitHub Enterprise behind VPN:**

    * ULPI can't reach your server
    * **Fix:** Enterprise plan with VPN peering

    **Manual setup:**

    * See "Manual Webhook Setup" tab above
    * Requires admin access to repository

    **Workaround:**

    * Use manual re-index after each push
    * Not ideal, but works if webhooks can't be enabled
  </Accordion>
</AccordionGroup>

***

## Best Practices for Documentation

**Optimize your repositories for better search:**

<CardGroup cols={2}>
  <Card title="📁 Standard Directory Structure" icon="folder-tree" color="#10b981">
    **Recommended structure:**

    ```
    your-repo/
    ├── README.md              # Quick start
    ├── docs/
    │   ├── getting-started.md # Setup guide
    │   ├── api/
    │   │   ├── authentication.md
    │   │   └── endpoints.md
    │   ├── guides/
    │   │   ├── deployment.md
    │   │   └── troubleshooting.md
    │   └── architecture/
    │       ├── decisions/     # ADRs
    │       └── diagrams/
    ├── CONTRIBUTING.md
    └── .ulpiignore
    ```

    **Why this works:**

    * Easy to find docs (always `/docs`)
    * Logical organization by topic
    * ULPI indexes everything
  </Card>

  <Card title="📝 Clear, Descriptive Filenames" icon="signature" color="#3b82f6">
    **Good filenames:**

    * ✅ `authentication-guide.md`
    * ✅ `deployment-to-aws.md`
    * ✅ `troubleshooting-500-errors.md`
    * ✅ `api-rate-limiting.md`

    **Bad filenames:**

    * ❌ `doc1.md`
    * ❌ `notes.md`
    * ❌ `stuff.md`
    * ❌ `temp.md`

    **Impact on search:**

    * Filenames are used in ranking
    * Descriptive names = better results
  </Card>

  <Card title="🔄 Update Docs with Code" icon="arrows-rotate" color="#8b5cf6">
    **Document in the same PR:**

    ```
    PR #247: Add OAuth 2.0 authentication

    Changed files:
    ✅ src/auth/oauth.js          (code)
    ✅ docs/authentication.md     (docs)
    ✅ README.md                  (updated)
    ```

    **Benefits:**

    * Docs never get stale
    * Reviewers catch doc issues
    * Webhooks auto-index on merge
    * AI sees updated docs instantly
  </Card>

  <Card title="📑 Use Headings & Structure" icon="heading" color="#f59e0b">
    **Well-structured docs:**

    ```markdown theme={null}
    # Authentication Guide

    ## Overview
    Brief intro...

    ## Quick Start
    Step-by-step...

    ## OAuth 2.0
    ### Setup
    ### Token Refresh
    ### Error Handling

    ## Troubleshooting
    ### Common Errors
    ### Debug Tips
    ```

    **Why:**

    * Semantic search uses headings
    * Chunking respects sections
    * Better result snippets
  </Card>
</CardGroup>

### Documentation Quality Tips

<AccordionGroup>
  <Accordion title="✍️ Write for Your Audience" icon="users">
    **New developers need:**

    * Clear setup instructions
    * Prerequisites listed
    * Step-by-step guides
    * Screenshots/diagrams

    **Experienced developers need:**

    * API references
    * Architecture decisions
    * Performance tuning
    * Troubleshooting guides

    **Write both types:**

    * `getting-started.md` for newbies
    * `architecture/decisions/` for veterans
  </Accordion>

  <Accordion title="🔗 Link Between Docs" icon="link">
    **Cross-reference related docs:**

    ```markdown theme={null}
    # Deployment Guide

    Prerequisites:
    - [Local setup complete](./getting-started.md)
    - [Environment configured](./configuration.md)
    - [Tests passing](./testing.md)

    See also:
    - [Rollback procedure](./rollback.md)
    - [Monitoring](./monitoring.md)
    ```

    **Benefits:**

    * Helps readers find related info
    * ULPI follows links for context
    * Better semantic understanding
  </Accordion>

  <Accordion title="📅 Keep Docs Current" icon="calendar-check">
    **Strategies:**

    1. **Review quarterly:**
       * Set calendar reminder
       * Read through all docs
       * Update outdated info

    2. **Version indicators:**
       ```markdown theme={null}
       > **Version:** v2.0
       > **Last updated:** 2025-01-15
       > **Deprecated:** v1.0 docs moved to archive/
       ```

    3. **Archive old docs:**

       ```
       docs/
       ├── current/         # Latest docs
       └── archive/
           ├── v1.x/
           └── deprecated/
       ```

       Add to `.ulpiignore`:

       ```
       /docs/archive/
       ```

    4. **Changelog:**
       Track doc changes in `docs/CHANGELOG.md`
  </Accordion>

  <Accordion title="🎯 Write for Search" icon="magnifying-glass">
    **SEO for docs (helps ULPI too):**

    **Include keywords naturally:**

    ```markdown theme={null}
    ❌ "Setup process"
    ✅ "Local development environment setup on macOS"
    ```

    **Answer questions:**

    ```markdown theme={null}
    # How to Deploy to Production

    ## What is the deployment process?
    ## Where are the deployment scripts?
    ## When should I deploy?
    ## Who can deploy to production?
    ```

    **Use synonyms:**

    ```markdown theme={null}
    # Authentication (Login, User Verification)

    This guide covers authentication, also known as
    login, sign-in, and user verification...
    ```

    **Result:** Better search results for varied queries
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Search Your Docs" icon="magnifying-glass" href="/documentation/search-features">
    Learn how to search across all connected repositories

    **Master semantic search techniques**
  </Card>

  <Card title="API Integration" icon="code" href="/documentation/api-integration">
    Access documentation programmatically via REST API

    **Build custom search workflows**
  </Card>

  <Card title="How It Works" icon="gear" href="/documentation/how-it-works">
    Understand the indexing and search technology

    **Deep dive into architecture**
  </Card>

  <Card title="Getting Started" icon="rocket" href="/documentation/getting-started">
    Connect more repositories and configure AI tools

    **Expand your searchable knowledge base**
  </Card>
</CardGroup>

***

<Note>
  **Need help with repositories?**

  * 📧 **Email:** [support@ulpi.io](mailto:support@ulpi.io)
  * 📚 **Docs:** [docs.ulpi.io](https://docs.ulpi.io)
  * 💬 **Slack:** [ulpi.io/slack](https://ulpi.io/slack)

  **Average response time:** Under 2 hours during business hours

  **Enterprise support:** Dedicated Slack channel + priority response
</Note>