> ## 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.

# Getting Started

> Go from AI that does not know your docs to AI expert on your codebase in under 5 minutes

# Your AI Will Know Your Entire Codebase in 5 Minutes

**Right now:** Your AI hallucinates patterns. You copy-paste docs every session. New developers ask the same questions for weeks.

**5 minutes from now:** Your AI assistant has instant access to every README, wiki page, and architecture doc across all your repositories.

**This guide gets you there—fast.**

***

## What You'll Accomplish

<CardGroup cols={2}>
  <Card title="Connect GitHub" icon="github" color="#10b981">
    **2 minutes**

    OAuth connection → automatic repository discovery
  </Card>

  <Card title="Index Documentation" icon="database" color="#3b82f6">
    **1-3 minutes (automatic)**

    AI processes all your docs in the background
  </Card>

  <Card title="Configure AI Tool" icon="puzzle-piece" color="#8b5cf6">
    **2 minutes**

    Add ULPI MCP server to Claude Code, Cursor, or 40+ other tools
  </Card>

  <Card title="Ask First Question" icon="message" color="#f59e0b">
    **Instant answers**

    "How do we deploy?" → Your AI knows immediately
  </Card>
</CardGroup>

<Note>
  **Total time:** 5-7 minutes. Most of it is waiting for automatic indexing.
</Note>

***

## Prerequisites

**You'll need:**

<Tabs>
  <Tab title="Required">
    <CardGroup cols={2}>
      <Card title="GitHub Account" icon="github">
        Sign up free at [github.com](https://github.com)

        Works with personal or organization accounts
      </Card>

      <Card title="AI Coding Assistant" icon="robot">
        **Any MCP-compatible tool:**

        * Claude Desktop (recommended)
        * Cursor
        * Windsurf
        * VSCode with Continue/Cline
        * [See all 40+ tools](/mcp/tools)
      </Card>
    </CardGroup>

    **Repository requirements:**

    * Public or private repositories (both supported)
    * GitHub, GitLab, Bitbucket, or Gitea
    * Documentation in Markdown, README files, wikis, or code comments
  </Tab>

  <Tab title="Recommended (Not Required)">
    **For best experience:**

    * **Node.js 18+** (if using NPX-based MCP servers)
    * **Admin access** to organization repos (for team-wide deployment)
    * **Existing documentation** (but we'll index whatever you have)
    * **5-10 minutes** to review this guide completely

    <Info>
      **Don't have docs yet?** ULPI will at minimum index your README files and code comments—still incredibly useful for AI assistants!
    </Info>
  </Tab>
</Tabs>

***

## Step 1: Create Your ULPI Account

**Stop wasting time searching. Let's fix this now.**

<Steps>
  <Step title="Visit app.ulpi.io">
    Go to **[app.ulpi.io](https://app.ulpi.io)** and click **Sign Up**

    <Check>
      **No credit card required for signup.** Choose your plan after you see the value.
    </Check>
  </Step>

  <Step title="Authenticate with GitHub">
    Click **Continue with GitHub** to authenticate via OAuth

    **What we request:**

    * ✅ Read-only access to repositories
    * ✅ Webhook access (for auto-sync)
    * ❌ **We never write to your code**
    * ❌ **We never modify repositories**

    <Info>
      **Using GitLab, Bitbucket, or Gitea?** Select "Other Git Provider" and follow the connection wizard.
    </Info>
  </Step>

  <Step title="Choose Your Plan">
    Select a plan based on your team size:

    <Tabs>
      <Tab title="Starter ($29/mo)">
        **Perfect for solo developers or small teams:**

        * 5 repositories
        * 100,000 tokens/month (\~15-20 searches/day)
        * Semantic search across all docs
        * Auto-sync on every push
        * MCP integration (40+ AI tools)
        * Email support

        **Best for:** 1-3 developers
      </Tab>

      <Tab title="Professional ($99/mo)">
        **Best for growing teams:**

        * 25 repositories
        * 500,000 tokens/month (\~75-100 searches/day)
        * Everything in Starter, plus:
          * Advanced search filters
          * Team collaboration features
          * Priority support
          * Usage analytics dashboard

        **Best for:** 5-15 developers
      </Tab>

      <Tab title="Enterprise ($299/mo)">
        **For large organizations:**

        * **Unlimited repositories**
        * 2,000,000 tokens/month (\~300+ searches/day)
        * Everything in Professional, plus:
          * Custom integrations
          * SSO / SAML authentication
          * SLA guarantees (99.9% uptime)
          * Dedicated support engineer
          * On-premise deployment options

        **Best for:** 20+ developers
      </Tab>
    </Tabs>

    [Compare all plans in detail →](/pricing)

    <Note>
      **Not sure?** Start with Starter. Upgrade anytime. We'll prorate the difference.

      **Bundle discount:** Save 15-20% by combining Documentation with Skills, Memory, Coordination, or Hooks.
    </Note>
  </Step>

  <Step title="Complete Billing">
    Enter payment details via **Stripe** (secure, PCI-compliant)

    **Guarantees:**

    * 🔒 **Bank-level security** (PCI-DSS Level 1)
    * 💳 **30-day money-back** - cancel anytime, full refund
    * 🔄 **Flexible billing** - change plans monthly
    * 📊 **Transparent usage** - see token consumption in real-time

    <Check>
      **Your account is live immediately** after payment confirmation.
    </Check>
  </Step>
</Steps>

**Estimated time:** 2 minutes

***

## Step 2: Connect Your Repositories

**Make your documentation searchable by AI.**

<Steps>
  <Step title="Navigate to Repositories">
    In the ULPI dashboard:

    1. Click **Repositories** in the left sidebar
    2. You'll see the repository connection screen

    <Info>
      If you just signed up, you'll be automatically directed here.
    </Info>
  </Step>

  <Step title="Select Repositories to Connect">
    Choose which repositories to make searchable:

    <Tabs>
      <Tab title="Select Individual Repos">
        **Best for testing or specific projects:**

        1. **Browse your repositories** in the list
        2. **Check the boxes** next to repositories with documentation
        3. Click **Connect Selected** (green button)

        **Recommended for first-time setup:** Start with 2-3 repos to see ULPI in action, then add more.
      </Tab>

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

        1. Click **Select All Repositories** toggle
        2. Click **Connect All** (purple button)
        3. All current + future repos automatically connected

        **Perfect for:** Teams that want comprehensive documentation search across entire organization.

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

      <Tab title="Filtered by Team/Org">
        **Best for multi-organization setups:**

        1. Use **Organization filter** dropdown
        2. Select specific GitHub organization
        3. Choose repos from that org only
        4. Click **Connect Selected**

        **Use case:** You're part of multiple orgs but only want to index documentation from your company.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Grant Permissions">
    ULPI requests authorization to:

    <AccordionGroup>
      <Accordion title="✅ Read Repository Contents" icon="book">
        **What we read:**

        * Documentation files (`.md`, `.mdx`, `README.*`)
        * Wiki pages (optional, you can disable)
        * Code comments (optional, disabled by default)

        **What we don't read:**

        * Source code (unless you enable comment indexing)
        * Secrets, `.env` files
        * Build artifacts, `node_modules/`
        * Binary files
      </Accordion>

      <Accordion title="✅ Receive Webhook Notifications" icon="bell">
        **Why we need this:**

        * Automatic re-indexing on git push
        * Keep documentation always up-to-date
        * No manual "sync" button needed

        **Triggered on:**

        * Push to main/master branch
        * Pull request merges
        * Wiki updates
        * Manual trigger from dashboard
      </Accordion>

      <Accordion title="❌ We Never Write to Your Code" icon="shield-check">
        **Security guarantee:**

        * ❌ **Cannot modify files**
        * ❌ **Cannot create commits**
        * ❌ **Cannot push changes**
        * ❌ **Cannot delete repositories**

        **Read-only access only.** Revoke anytime from GitHub settings.
      </Accordion>
    </AccordionGroup>

    Click **Authorize ULPI** to proceed.
  </Step>

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

    <Tabs>
      <Tab title="What Gets Indexed">
        **Automatically included:**

        * ✅ `README.md`, `README.txt` (all directories)
        * ✅ `docs/` and `documentation/` directories
        * ✅ All `.md` and `.mdx` files
        * ✅ `CONTRIBUTING.md`, `CHANGELOG.md`
        * ✅ Architecture Decision Records (ADRs)
        * ✅ `.github/` documentation

        **Optionally included** (configure in settings):

        * 🔧 Wiki pages (disabled by default, can enable)
        * 🔧 Code comments and docstrings (disabled by default)
        * 🔧 Jupyter notebooks (`.ipynb`)
        * 🔧 `.txt` files in doc directories

        **Automatically excluded:**

        * ❌ `node_modules/`, `vendor/`, `packages/`
        * ❌ Build directories (`dist/`, `build/`, `out/`)
        * ❌ `.git/` directory
        * ❌ Binary files (images, PDFs, etc.)
        * ❌ Large files (>1MB)

        **Custom exclusions:** Create a `.ulpiignore` file (works like `.gitignore`)
      </Tab>

      <Tab title="Indexing Speed">
        **How long will this take?**

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

        **Real-time progress:**

        * Watch indexing status in dashboard
        * See which files are being processed
        * Get notified when complete

        <Info>
          **You can configure AI integration while indexing happens in the background.** Jump to Step 3 now!
        </Info>
      </Tab>

      <Tab title="What Happens During Indexing">
        **Behind the scenes (fully automatic):**

        1. **Repository cloning** (temporary, in-memory)
        2. **File discovery** (find all documentation)
        3. **Content extraction** (parse Markdown, extract structure)
        4. **Semantic chunking** (break into logical sections)
        5. **Vector embedding** (create searchable AI representations)
        6. **Index storage** (save to Typesense vector database)
        7. **Cleanup** (remove temporary files)

        **Status updates in dashboard:**

        ```
        ✅ user-service: Indexed (234 files, 2,456 chunks)
        ✅ backend-api: Indexed (567 files, 5,123 chunks)
        ⏳ infrastructure: Indexing... 45% (1,234 files processed)
        ⏸️ mobile-app: Queued
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

**Estimated time:** 2 minutes to connect, 1-15 minutes for automatic indexing

<Accordion title="Troubleshooting: Repository not appearing in list">
  **If you don't see your repository:**

  1. **Check GitHub OAuth permissions:**
     * Go to [github.com/settings/applications](https://github.com/settings/applications)
     * Find "ULPI Documentation"
     * Ensure it has access to the organization
     * Click "Grant access" if needed

  2. **Organization settings:**
     * Org admin must approve third-party apps
     * Ask your GitHub org admin to approve ULPI
     * [Guide for admins →](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization)

  3. **Repository visibility:**
     * Private repos require explicit OAuth permission
     * Re-authenticate and grant access to private repositories

  4. **Still not working?**
     * Contact support: [support@ulpi.io](mailto:support@ulpi.io)
     * Include: repository URL, GitHub username, error messages
</Accordion>

***

## Step 3: Create an API Key

**API keys connect your AI assistant to ULPI's documentation search.**

<Steps>
  <Step title="Navigate to API Keys">
    In the ULPI dashboard:

    1. Click **Settings** in sidebar
    2. Select **API Keys** tab
    3. You'll see the API key management screen
  </Step>

  <Step title="Click Create API Key">
    Click the **Create API Key** button (green button, top right)
  </Step>

  <Step title="Configure Key Settings">
    **Fill in API key details:**

    <Tabs>
      <Tab title="Basic Settings">
        **Name:** `Documentation MCP Server`

        *(For identification—name it after where you'll use it)*

        **Examples:**

        * "Claude Desktop - MacBook Pro"
        * "Cursor - Work Laptop"
        * "Team Shared Key"

        ***

        **Environment:** `live` (production) or `test` (development)

        * **`live`:** Use in real AI assistants (recommended)
        * **`test`:** Use for testing, development, experiments

        <Check>
          **Start with `live` environment** unless you're developing integrations.
        </Check>
      </Tab>

      <Tab title="Security Settings">
        **Key Type:** `restricted` (recommended) or `unrestricted`

        <Tabs>
          <Tab title="Restricted (Recommended)">
            **Scoped to specific repositories:**

            * Select which repos this key can access
            * Prevents unauthorized documentation access
            * Best for team members who only need specific projects

            **Example:**

            * Frontend team key: Access `web-app`, `mobile-app` only
            * Backend team key: Access `api`, `services`, `infrastructure`
            * Contractor key: Access only `project-x` repository
          </Tab>

          <Tab title="Unrestricted">
            **Access to all repositories:**

            * No repository limitations
            * Full search across all connected repos
            * Best for team leads, architects, full-stack developers

            <Warning>
              **Security note:** Only give unrestricted keys to trusted team members who need org-wide documentation access.
            </Warning>
          </Tab>
        </Tabs>

        ***

        **Scopes:** Leave default (`tenant-scoped`)

        This means the key only works within your ULPI account—can't access other customers' documentation.
      </Tab>

      <Tab title="Advanced Settings">
        **Rate limiting:** Default (1,000 requests/hour)

        *(Adjust if you have high-volume use cases)*

        **Token quotas:** Inherit from plan

        *(Or set per-key limits for team members)*

        **Expiration:** No expiration (recommended) or custom

        *(Set expiration for contractor keys or temporary access)*

        **IP restrictions:** None (default) or whitelist

        *(Enterprise only—restrict key usage to specific IPs)*
      </Tab>
    </Tabs>
  </Step>

  <Step title="Copy Your API Key">
    **⚠️ CRITICAL: This is shown ONLY ONCE!**

    1. **Copy the API key immediately**
    2. **Store it securely:**
       * Password manager (1Password, LastPass, Bitwarden)
       * Environment variable in your shell config
       * Secure note in your IDE

    **API key format:** `ulpi_live_sk_1234abcd...`

    <Warning>
      **Never commit API keys to version control!**

      Add to `.gitignore`:

      ```bash theme={null}
      # ULPI API Keys
      .env
      .env.local
      **/mcp_config.json
      claude_desktop_config.json
      ```
    </Warning>

    <Info>
      **Lost your key?** You can't recover it, but you can:

      1. Revoke the old key
      2. Create a new one
      3. Update your AI tool config with the new key
    </Info>
  </Step>
</Steps>

**Estimated time:** 1 minute

***

## Step 4: Configure Your AI Assistant

**Connect ULPI to your favorite AI coding tool.**

Choose your AI assistant below and follow the setup:

<Tabs>
  <Tab title="Claude Desktop (Recommended)">
    **Anthropic's official AI assistant with best ULPI integration**

    <Steps>
      <Step title="Locate Config File">
        Find your Claude Desktop config file:

        <Tabs>
          <Tab title="macOS">
            ```bash theme={null}
            ~/Library/Application Support/Claude/claude_desktop_config.json
            ```

            **Open in terminal:**

            ```bash theme={null}
            open ~/Library/Application\ Support/Claude/
            ```
          </Tab>

          <Tab title="Windows">
            ```powershell theme={null}
            %APPDATA%\Claude\claude_desktop_config.json
            ```

            **Open in File Explorer:**

            ```powershell theme={null}
            explorer %APPDATA%\Claude
            ```
          </Tab>

          <Tab title="Linux">
            ```bash theme={null}
            ~/.config/Claude/claude_desktop_config.json
            ```

            **Open in terminal:**

            ```bash theme={null}
            cd ~/.config/Claude/
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="Add ULPI MCP Server">
        **Edit `claude_desktop_config.json`:**

        ```json theme={null}
        {
          "mcpServers": {
            "ulpi-docs": {
              "command": "npx",
              "args": ["-y", "@ulpi/mcp-server-documentation"],
              "env": {
                "ULPI_API_KEY": "ulpi_live_YOUR_KEY_HERE"
              }
            }
          }
        }
        ```

        **Replace `ulpi_live_YOUR_KEY_HERE`** with your actual API key from Step 3.

        <Accordion title="Already have other MCP servers?">
          **Add ULPI to existing config:**

          ```json theme={null}
          {
            "mcpServers": {
              "filesystem": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-filesystem"]
              },
              "ulpi-docs": {
                "command": "npx",
                "args": ["-y", "@ulpi/mcp-server-documentation"],
                "env": {
                  "ULPI_API_KEY": "ulpi_live_sk_abc123..."
                }
              },
              "github": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-github"]
              }
            }
          }
          ```

          **Just add the `ulpi-docs` block** to your existing `mcpServers` object.
        </Accordion>
      </Step>

      <Step title="Restart Claude Desktop">
        1. **Quit Claude Desktop completely** (Cmd+Q on Mac, Alt+F4 on Windows)
        2. **Reopen Claude Desktop**
        3. Look for **🔌 MCP icon** in bottom toolbar (indicates servers loaded)

        <Check>
          **Success indicator:** You'll see "MCP: 1 server connected" or "ulpi-docs" in the MCP status panel.
        </Check>
      </Step>
    </Steps>

    **Total time:** 2 minutes

    [Detailed Claude Desktop guide →](/mcp/claude-desktop)
  </Tab>

  <Tab title="Cursor">
    **AI-first code editor with excellent MCP support**

    <Steps>
      <Step title="Locate Cursor Config">
        **Config file location:**

        <Tabs>
          <Tab title="macOS / Linux">
            ```bash theme={null}
            ~/.cursor/mcp_config.json
            ```
          </Tab>

          <Tab title="Windows">
            ```powershell theme={null}
            %USERPROFILE%\.cursor\mcp_config.json
            ```
          </Tab>
        </Tabs>

        **Create file if it doesn't exist:**

        ```bash theme={null}
        mkdir -p ~/.cursor
        touch ~/.cursor/mcp_config.json
        ```
      </Step>

      <Step title="Add ULPI Configuration">
        **Edit `mcp_config.json`:**

        ```json theme={null}
        {
          "mcpServers": {
            "ulpi-docs": {
              "command": "npx",
              "args": ["-y", "@ulpi/mcp-server-documentation"],
              "env": {
                "ULPI_API_KEY": "ulpi_live_YOUR_KEY_HERE"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Cursor">
        1. Close all Cursor windows
        2. Quit application completely
        3. Reopen Cursor
        4. Check **MCP Servers** in settings to verify connection
      </Step>
    </Steps>

    [Detailed Cursor guide →](/mcp/cursor)
  </Tab>

  <Tab title="Windsurf">
    **Collaborative AI coding with flow state**

    <Steps>
      <Step title="Open Windsurf Settings">
        1. Open Windsurf
        2. Go to **Settings** → **Extensions** → **MCP Servers**
      </Step>

      <Step title="Add ULPI Server">
        Click **Add MCP Server** and configure:

        ```json theme={null}
        {
          "name": "ulpi-docs",
          "command": "npx",
          "args": ["-y", "@ulpi/mcp-server-documentation"],
          "env": {
            "ULPI_API_KEY": "ulpi_live_YOUR_KEY_HERE"
          }
        }
        ```
      </Step>

      <Step title="Activate Server">
        1. Save settings
        2. Reload Windsurf window
        3. Verify "ulpi-docs" appears in MCP status
      </Step>
    </Steps>

    [Detailed Windsurf guide →](/mcp/windsurf)
  </Tab>

  <Tab title="VSCode (Continue / Cline)">
    **Visual Studio Code with Continue or Cline extensions**

    <Tabs>
      <Tab title="Continue Extension">
        <Steps>
          <Step title="Open Continue Config">
            **Config file:** `~/.continue/config.json`

            Or open via Continue extension: **Settings** → **Edit config.json**
          </Step>

          <Step title="Add to mcpServers Array">
            ```json theme={null}
            {
              "mcpServers": [
                {
                  "name": "ulpi-docs",
                  "command": "npx",
                  "args": ["-y", "@ulpi/mcp-server-documentation"],
                  "env": {
                    "ULPI_API_KEY": "ulpi_live_YOUR_KEY_HERE"
                  }
                }
              ]
            }
            ```
          </Step>

          <Step title="Reload VSCode">
            **Cmd+Shift+P** → **Developer: Reload Window**
          </Step>
        </Steps>

        [Continue setup guide →](/mcp/continue)
      </Tab>

      <Tab title="Cline Extension">
        <Steps>
          <Step title="Open Cline Settings">
            Click **Cline** icon in sidebar → **Settings** (gear icon)
          </Step>

          <Step title="Add MCP Server">
            In MCP Servers section, add:

            ```json theme={null}
            {
              "ulpi-docs": {
                "command": "npx",
                "args": ["-y", "@ulpi/mcp-server-documentation"],
                "env": {
                  "ULPI_API_KEY": "ulpi_live_YOUR_KEY_HERE"
                }
              }
            }
            ```
          </Step>

          <Step title="Restart Extension">
            Disable and re-enable Cline extension, or reload VSCode window
          </Step>
        </Steps>

        [Cline setup guide →](/mcp/cline)
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Claude Code (CLI)">
    **Terminal-based AI coding by Anthropic**

    <Steps>
      <Step title="Locate Config File">
        **Config location:**

        <Tabs>
          <Tab title="macOS / Linux">
            ```bash theme={null}
            ~/.config/claude-code/mcp_config.json
            ```
          </Tab>

          <Tab title="Windows">
            ```powershell theme={null}
            %APPDATA%\claude-code\mcp_config.json
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="Add ULPI Server">
        ```json theme={null}
        {
          "mcpServers": {
            "ulpi-docs": {
              "command": "npx",
              "args": ["-y", "@ulpi/mcp-server-documentation"],
              "env": {
                "ULPI_API_KEY": "ulpi_live_YOUR_KEY_HERE"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Verify Connection">
        ```bash theme={null}
        claude-code --mcp-status
        ```

        Should show: `✅ ulpi-docs: Connected`
      </Step>
    </Steps>

    [Claude Code setup guide →](/mcp/claude-code)
  </Tab>

  <Tab title="Other AI Tools">
    **See complete setup guides for 40+ AI assistants:**

    **Desktop AI Apps:**

    * [Perplexity Desktop](/mcp/perplexity-desktop)
    * [BoltAI (macOS)](/mcp/boltai)

    **Code Editors:**

    * [Zed](/mcp/zed)
    * [PhpStorm](/mcp/phpstorm)
    * [WebStorm](/mcp/webstorm)
    * [IntelliJ IDEA](/mcp/phpstorm)

    **Terminal Tools:**

    * [Warp](/mcp/warp)
    * [Amazon Q CLI](/mcp/amazon-q-cli)
    * [Aider](/mcp/aider)
    * [OpenHands](/mcp/openhands)

    **VS Code Extensions:**

    * [GitHub Copilot](/mcp/github-copilot)
    * [Roo Code](/mcp/roo-code)
    * [Augment Code](/mcp/augment-code)
    * [Qodo Gen](/mcp/qodo-gen)

    [See all MCP integrations →](/mcp/tools)
  </Tab>
</Tabs>

**Estimated time:** 2 minutes

***

## Step 5: Test Your First Search

**Verify everything works!**

<Steps>
  <Step title="Open Your AI Assistant">
    Launch the AI tool you configured in Step 4:

    * Claude Desktop
    * Cursor
    * VSCode with Continue/Cline
    * etc.
  </Step>

  <Step title="Ask a Documentation Question">
    **Try these example queries:**

    <CodeGroup>
      ```plaintext Environment Setup theme={null}
      "How do I set up the local development environment?"
      ```

      ```plaintext Authentication theme={null}
      "What authentication methods does our API support?"
      ```

      ```plaintext Testing theme={null}
      "Show me examples of writing unit tests in our project"
      ```

      ```plaintext Configuration theme={null}
      "What environment variables are required to run the app?"
      ```

      ```plaintext Deployment theme={null}
      "How do we deploy to production?"
      ```

      ```plaintext Architecture theme={null}
      "Explain our database architecture"
      ```
    </CodeGroup>

    <Info>
      **Ask in plain English!** ULPI understands natural language—no need for exact keywords.
    </Info>
  </Step>

  <Step title="Verify Results">
    **Your AI assistant should:**

    ✅ **Search ULPI automatically** (you won't see this, it happens behind the scenes)

    ✅ **Return relevant documentation excerpts** from your repositories

    ✅ **Include source file links** like:

    ```
    Based on docs/setup.md:15-45:
    To set up your development environment...
    ```

    ✅ **Provide context-aware answers** using YOUR project's patterns

    ✅ **Cite multiple sources** if the answer spans multiple docs

    <Check>
      **Success looks like:** AI responds with specific details from your actual documentation, not generic advice.
    </Check>
  </Step>

  <Step title="Monitor in Dashboard">
    **See searches in real-time:**

    1. Go to ULPI dashboard → **Activity** tab
    2. You'll see:
       * Recent searches
       * Which repositories were queried
       * Token usage
       * Response times

    **Example activity log:**

    ```
    10:34 AM - Search: "How do we deploy?"
               → Found in: infrastructure/deployment.md
               → Tokens used: 2,340
               → Response time: 45ms

    10:31 AM - Search: "API authentication methods"
               → Found in: backend-api/README.md, docs/auth.md
               → Tokens used: 1,890
               → Response time: 38ms
    ```
  </Step>
</Steps>

**Estimated time:** 1 minute

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="🚨 AI Assistant Doesn't Search ULPI" icon="triangle-exclamation">
    **Symptom:** AI gives generic answers instead of searching your docs.

    **Fixes:**

    1. **Check MCP server connection:**
       * **Claude Desktop:** Look for 🔌 icon in bottom toolbar
       * **Cursor:** Check Settings → MCP Servers shows "Connected"
       * **VSCode:** Continue/Cline should show "ulpi-docs" in status

    2. **Verify API key format:**

       ```json theme={null}
       {
         "env": {
           "ULPI_API_KEY": "ulpi_live_sk_abc123..."  // ✅ Correct
         }
       }
       ```

       **Common errors:**

       ```json theme={null}
       "ULPI_API_KEY": " ulpi_live_sk_abc123"  // ❌ Leading space
       "ULPI_API_KEY": "ulpi_test_sk_abc123"   // ❌ Wrong environment
       "ULPI_API_KEY": "'ulpi_live_sk_abc123'" // ❌ Extra quotes
       ```

    3. **Check MCP server logs:**

       * **macOS:** `~/Library/Logs/Claude/mcp.log`
       * **Windows:** `%APPDATA%\Claude\Logs\mcp.log`
       * **Linux:** `~/.config/Claude/logs/mcp.log`

       **Look for errors like:**

       ```
       ERROR: Authentication failed - invalid API key
       ERROR: ULPI_API_KEY environment variable not set
       ERROR: Network error connecting to ULPI API
       ```

    4. **Restart AI assistant:**
       * **Fully quit** (don't just close window)
       * **Reopen** and try again
       * Config changes only load on full restart
  </Accordion>

  <Accordion title="⏱️ Indexing Taking Too Long" icon="clock">
    **Symptom:** Repository stuck at "Indexing..." for >30 minutes.

    **Normal indexing times:**

    * Less than 100 files: 30 seconds - 2 minutes
    * 100-1,000 files: 2-5 minutes
    * 1,000-10,000 files: 5-15 minutes
    * 10,000+ files: 15-30 minutes

    **If it's taking longer:**

    1. **Check repository size:**
       * Dashboard → Repositories → Click repo name
       * See "Files discovered" count
       * Large repos (10,000+ files) can take 30-45 minutes

    2. **Check for errors:**
       * Look for ⚠️ warning icon next to repository
       * Click for error details
       * Common issues:
         * Binary files causing slowdown (auto-excluded, but takes time to detect)
         * Network issues accessing GitHub
         * Very large markdown files (>5MB)

    3. **Force re-index:**
       * Dashboard → Repositories → Click **⟳ Re-index** button
       * This restarts the indexing process
       * Sometimes resolves stuck states

    4. **Contact support:**
       * If stuck >1 hour: [support@ulpi.io](mailto:support@ulpi.io)
       * Include: repository name, size, approximate file count
  </Accordion>

  <Accordion title="🔍 Search Returns No Results" icon="magnifying-glass">
    **Symptom:** AI says "I couldn't find documentation about that" or returns empty results.

    **Possible causes:**

    1. **Indexing not complete:**
       * Dashboard → Repositories → Check status
       * Wait for "✅ Indexed" status
       * Usually takes 2-5 minutes

    2. **Documentation doesn't exist:**
       * Verify your repos actually have docs about that topic
       * Check if docs use different terminology
       * Example: You ask about "authentication" but docs say "auth" or "login"

    3. **Wrong repository scope:**
       * API key might be scoped to specific repos
       * Dashboard → Settings → API Keys → Check scopes
       * Expand scope or use different key

    4. **Query too vague:**
       * ❌ "How does it work?"
       * ✅ "How does authentication work?"
       * ✅ "Explain our Redis caching strategy"
       * Be specific!

    5. **Files excluded by default:**
       * Check `.ulpiignore` file in repository
       * Dashboard → Repositories → Click repo → See "Excluded patterns"
       * Adjust exclusions if needed
  </Accordion>

  <Accordion title="🔑 API Key Issues" icon="key">
    **Symptom:** "Invalid API key" or authentication errors.

    **Fixes:**

    1. **Verify key format:**
       ```
       ulpi_live_sk_1234567890abcdef...  // ✅ Correct (live)
       ulpi_test_sk_1234567890abcdef...  // ✅ Correct (test)
       ulpi_sk_1234567890abcdef...       // ❌ Missing environment
       sk_1234567890abcdef...             // ❌ Missing ulpi_ prefix
       ```

    2. **Check environment match:**
       * API key environment (`live` vs `test`)
       * MCP server environment
       * Dashboard shows environment per key

    3. **Verify key not revoked:**
       * Dashboard → Settings → API Keys
       * Check key status is "Active" (not "Revoked")
       * If revoked, create a new key

    4. **Test API key directly:**

       ```bash theme={null}
       curl -H "Authorization: Bearer ulpi_live_sk_YOUR_KEY" \
            https://api.ulpi.io/v1/search?q=test
       ```

       **Expected response:**

       ```json theme={null}
       {
         "success": true,
         "results": [...]
       }
       ```

       **Error response:**

       ```json theme={null}
       {
         "error": "Invalid API key"
       }
       ```
  </Accordion>

  <Accordion title="💾 Token Limit Exceeded" icon="database">
    **Symptom:** "You've exceeded your monthly token limit" error.

    **Solutions:**

    1. **Check current usage:**
       * Dashboard → Usage & Billing
       * See tokens used vs. plan limit
       * View usage by day/week/month

    2. **Upgrade plan:**
       * Starter (100k) → Professional (500k)
       * Professional → Enterprise (2M)
       * Settings → Billing → Change Plan

    3. **Buy token overage:**
       * **\$20 per 100,000 additional tokens**
       * No service interruption
       * Automatically billed at end of month
       * Dashboard → Usage → "Buy More Tokens"

    4. **Set usage alerts:**
       * Dashboard → Settings → Usage Alerts
       * Get notified at 50%, 75%, 90% of limit
       * Prevents surprises

    5. **Optimize searches:**
       * Be more specific in queries (returns less data)
       * Scope searches to specific repositories
       * Avoid overly broad questions
  </Accordion>

  <Accordion title="🔒 Repository Access Denied" icon="lock">
    **Symptom:** "Access denied" when trying to search private repositories.

    **Fixes:**

    1. **Re-authenticate with GitHub:**
       * Dashboard → Settings → Integrations
       * Click "Reconnect GitHub"
       * Grant access to private repositories

    2. **Check organization approval:**
       * GitHub org admin must approve ULPI app
       * Ask admin to:
         1. Go to `github.com/organizations/YOUR_ORG/settings/oauth_application_policy`
         2. Find "ULPI Documentation"
         3. Click "Grant access"

    3. **Verify API key scope:**
       * Dashboard → Settings → API Keys
       * Click key name → View scopes
       * Ensure key has access to that repository

    4. **Repository permissions:**
       * You must have at least "Read" access to repo in GitHub
       * Org admins can grant access via GitHub teams
  </Accordion>

  <Accordion title="🌐 Network / Firewall Issues" icon="network-wired">
    **Symptom:** Connection timeouts or "Cannot reach ULPI API" errors.

    **Enterprise network fixes:**

    1. **Whitelist ULPI domains:**
       ```
       api.ulpi.io
       app.ulpi.io
       *.ulpi.io
       ```

    2. **Allow outbound HTTPS (port 443):**
       * ULPI MCP server needs to reach `api.ulpi.io:443`
       * Check corporate firewall rules

    3. **Proxy configuration:**
       ```json theme={null}
       {
         "env": {
           "ULPI_API_KEY": "ulpi_live_sk_...",
           "HTTPS_PROXY": "http://proxy.company.com:8080",
           "HTTP_PROXY": "http://proxy.company.com:8080"
         }
       }
       ```

    4. **VPN conflicts:**
       * Try disconnecting VPN temporarily
       * If works without VPN, configure VPN to allow ULPI

    5. **Test connectivity:**

       ```bash theme={null}
       curl -I https://api.ulpi.io/health
       ```

       **Expected:** HTTP 200 OK
       **Error:** Connection timeout or refused
  </Accordion>
</AccordionGroup>

**Still stuck?** Email [support@ulpi.io](mailto:support@ulpi.io) with:

* Error message screenshot
* MCP server logs
* API key (first/last 4 characters only)
* AI tool and OS you're using

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Advanced Search Features" icon="magnifying-glass" href="/documentation/search-features">
    Master semantic search, filters, and query optimization

    **Learn:** Cross-repo search, branch filtering, date ranges, file type filters
  </Card>

  <Card title="How It Works (Technical Deep Dive)" icon="gear" href="/documentation/how-it-works">
    Understand the architecture behind ULPI's semantic search

    **Learn:** Vector embeddings, Typesense, chunking strategies, indexing pipeline
  </Card>

  <Card title="Repository Management" icon="folder" href="/documentation/repositories">
    Add more repositories, configure indexing, manage webhooks

    **Learn:** Multi-repo strategies, `.ulpiignore`, custom exclusions, wiki integration
  </Card>

  <Card title="API Integration" icon="code" href="/documentation/api-integration">
    Integrate ULPI directly into your applications via REST API

    **Learn:** Direct API access, custom search UIs, workflow automation
  </Card>
</CardGroup>

***

## Success Story

<blockquote>
  "Setup took 6 minutes. Within an hour, our AI assistants went from giving generic advice to citing our actual deployment docs, API patterns, and architecture decisions. Onboarding new developers just became 10x easier."

  **— Marcus Chen, Engineering Lead @ TechCorp**

  *47-person engineering team, 23 microservices, 156 repositories*
</blockquote>

**Your team's documentation is searchable now.** Time to see the same transformation.

***

<Note>
  **Need help?** We're here for you:

  * 📧 **Email:** [support@ulpi.io](mailto:support@ulpi.io)
  * 📚 **Docs:** [docs.ulpi.io](https://docs.ulpi.io)
  * 💬 **Slack Community:** [ulpi.io/slack](https://ulpi.io/slack)
  * 🐛 **Bug Reports:** [github.com/ulpi-io/feedback](https://github.com/ulpi-io/feedback)

  **Average response time:** Under 2 hours during business hours
</Note>