docforge-cli 0.2.0__tar.gz

docforge_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tobias Ens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docforge_cli-0.2.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: docforge-cli
+Version: 0.2.0
+Summary: Forge searchable context from Confluence and git repos for AI coding assistants
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: asyncpg>=0.30
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pydantic-settings>=2.6
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: sentence-transformers>=5.0
+Requires-Dist: pgvector>=0.3
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.34
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: testcontainers[postgres]>=4.0; extra == "dev"
+Provides-Extra: entra
+Requires-Dist: fastapi-azure-auth>=5.0; extra == "entra"
+Requires-Dist: azure-identity>=1.19; extra == "entra"
+Requires-Dist: aiohttp>=3.10; extra == "entra"
+Dynamic: license-file
+
+# docforge
+
+**The self-hosted context engine for AI coding assistants.**
+
+Point docforge at your Confluence spaces and local git repositories. It indexes, embeds, and serves them over MCP — so Claude Code, Cursor, Copilot, and any assistant that speaks MCP can search your team's knowledge without your data leaving your infrastructure.
+
+docforge doesn't replace your AI assistant. It feeds it — turning Claude Code, Cursor, Copilot, and anything else that speaks MCP into tools that actually know your team's docs and code.
+
+[![CI](https://github.com/GranatenUdo/docforge/actions/workflows/ci.yml/badge.svg)](https://github.com/GranatenUdo/docforge/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/docforge-cli.svg)](https://pypi.org/project/docforge-cli/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+## Why docforge
+
+| Tool | Self-hosted | Integration | Confluence + code | Footprint | Complements AI assistants? |
+|---|---|---|---|---|---|
+| **docforge** | ✓ | MCP server | ✓ (Confluence + local git) | Minimal (PG + 1 container) | ✓ (any MCP client) |
+| [Atlassian Rovo MCP](https://www.atlassian.com/blog/announcements/atlassian-rovo-mcp-ga) | ✗ (Cloud-only) | MCP server | Confluence only (Cloud) | SaaS | ✓ |
+| [zilliztech/claude-context](https://github.com/zilliztech/claude-context) | ✓ | MCP server | Code only | Minimal | ✓ |
+| [Onyx](https://github.com/onyx-dot-app/onyx) | ✓ | MCP + chat UI | ✓ (50+ connectors) | Heavy (Standard) / Minimal (Lite) | ✓ (+ its own UI) |
+| Cursor codebase index + @Docs | ✗ | Proprietary | Code + public web docs | SaaS | — (built into Cursor only) |
+| [Copilot Spaces](https://github.com/orgs/community/discussions/180894) | ✗ | Proprietary (MCP for actions) | Code + attachments | SaaS | — (built into Copilot only) |
+| [Sourcegraph Cody](https://sourcegraph.com/docs/cody/enterprise/features) | ✓ (Enterprise) | OpenCtx / MCP | ✓ (via OpenCtx) | Heavy (Sourcegraph platform) | — (built into Cody only) |
+| LangChain / LlamaIndex DIY | ✓ | Whatever you build | You wire it | Depends | Depends |
+
+docforge is the narrow, focused option in this landscape: minimal footprint, MCP-native so it works with every assistant, and combines Confluence + code out of the box. It doesn't compete on connector count (Onyx wins there), visual UX (Cursor and Cody win), or SaaS convenience (Rovo). It competes on being **small, legible, vendor-neutral, and self-hosted** — four properties no commercial option offers together.
+
+### ✅ When docforge fits
+
+- You run Confluence Data Center/Server, or you want to self-host.
+- Your team uses MCP-capable assistants (Claude Code, Cursor with MCP, Copilot with MCP, etc.).
+- You want Confluence + git repos indexed together with one tool.
+- Operational simplicity matters — one Postgres, one container, MIT-licensed code you can audit in an afternoon.
+
+### ❌ When docforge is the wrong choice
+
+- You need 50+ connectors (Slack, Jira, Gmail, Drive, Notion) → use **[Onyx](https://github.com/onyx-dot-app/onyx)** or **[Glean](https://www.glean.com/)**.
+- You need per-document ACLs enforced at query time → not yet supported; use **Onyx**.
+- You need a chat UI for non-developers → docforge has no UI; use **Onyx**, **Glean**, or **Cody**.
+- You're on Atlassian Cloud and happy with SaaS → **[Atlassian Rovo MCP](https://www.atlassian.com/blog/announcements/atlassian-rovo-mcp-ga)** is free and official.
+- You need SSO / SCIM / RBAC → out of scope; docforge authenticates but doesn't authorize per-resource.
+- Your corpus is very large (>100K pages/chunks) → dense-only retrieval without hybrid starts to degrade; on the [roadmap](ROADMAP.md).
+- You need near-real-time updates → ingest is batch; no webhook-driven continuous sync yet.
+- You need multilingual search evaluated → EmbeddingGemma is multilingual, but docforge has no eval coverage on non-English corpora yet.
+
+## Quick Start
+
+```bash
+pip install docforge-cli
+docforge init my-project
+cd my-project
+# Edit docforge.yml with your Confluence URL
+# Edit sources.yml with your page IDs and local git repo paths
+# Edit .env with your credentials
+docker compose up -d db
+docforge init-db
+docforge ingest
+docforge serve
+```
+
+**Note:** The git crawler indexes **local filesystem paths** — docforge does not clone GitHub URLs. Clone first, then point docforge at the checkout path in `sources.yml`.
+
+## How It Works
+
+1. **Configure** your Confluence URL, page IDs, and local git repo paths in `sources.yml`.
+2. **Ingest** crawls pages and files, chunks text (~500 tokens), generates vector embeddings (768-dim).
+3. **Serve** exposes an MCP server that AI assistants query automatically.
+
+When an AI assistant needs cross-team context, it calls docforge's `search_documentation` MCP tool behind the scenes and gets relevant documentation chunks with source attribution.
+
+### Architecture
+
+![docforge architecture: Confluence and local git repos flow through docforge ingest into Postgres with pgvector, then docforge serve exposes an MCP server consumed by Claude Code, Cursor, and Copilot](docs/assets/architecture.svg)
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `docforge init <name>` | Scaffold a new project with config templates |
+| `docforge init-db` | Initialize the PostgreSQL database schema |
+| `docforge ingest` | Crawl all sources, embed, store in PostgreSQL |
+| `docforge search "<query>"` | Test search from terminal |
+| `docforge serve` | Run MCP server for AI assistants |
+| `docforge serve --api` | Run FastAPI search API (for hosted deployment) |
+| `docforge status` | Show index stats and health |
+
+## Deploy to your infrastructure
+
+For team-wide use, deploy the search API to Azure (~$35/month at default SKUs):
+
+- PostgreSQL Flexible Server (Burstable B1ms, 32 GB) with pgvector.
+- Container App running the FastAPI search API.
+- Container Registry, Key Vault, Log Analytics, managed environment.
+- Team members use a lightweight MCP client that calls the hosted API.
+
+See [`deploy/azure/`](deploy/azure/) for Bicep templates and a full cost breakdown.
+
+## Configuration
+
+See `docs/` for the full configuration reference, including `docforge.yml` and `sources.yml` schemas.
+
+## Contributing
+
+Contributions welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, branch conventions, and PR expectations. Bug reports and feature requests go through [GitHub Issues](https://github.com/GranatenUdo/docforge/issues); open-ended questions and ideas live in [Discussions](https://github.com/GranatenUdo/docforge/discussions).
+
+## Evaluation & retrieval quality
+
+docforge ships with a retrieval-quality eval harness at [`docforge/scripts/eval_search.py`](docforge/scripts/eval_search.py). It measures recall@1, recall@k, and MRR against a ground-truth query set you maintain. The harness is designed for **drift detection** — run it after `sources.yml` changes, embedding-model updates, or ranking tweaks, and compare against your baseline. There is no absolute quality threshold; the metric magnitude depends on how closely your ground-truth queries match source titles. See [`docforge/scripts/README.md`](docforge/scripts/README.md) for details.
+
+## FAQ
+
+### "Cannot connect to PostgreSQL"
+
+Check that the database is running: `docker compose up -d db`. Verify `DATABASE_URL` in `.env` points to `postgresql://docforge:localdev@localhost:5432/docforge` (or your custom value).
+
+### "HF_TOKEN required" or model download fails
+
+The embedding model `google/embeddinggemma-300m` requires a Hugging Face token with access to the gated model. Create one at https://huggingface.co/settings/tokens, accept the model license at https://huggingface.co/google/embeddinggemma-300m, and set `HF_TOKEN=hf_...` in `.env`.
+
+### "No results found" after ingest
+
+Run `docforge status` to confirm sources and chunks exist. If counts are zero, check the ingest logs for per-source failures — the summary at the end lists sources that failed.
+
+### First ingest / first container start is very slow
+
+The first run downloads the 300M embedding model (~1.2 GB) from Hugging Face. Locally, the model is cached at `~/.cache/huggingface/`. In the Docker image, it is cached at `/app/.cache/huggingface/` — **mount this as a volume** so container restarts do not re-download: `docker run -v docforge-hf-cache:/app/.cache/huggingface ...`.
+
+### "Ingest skipped everything"
+
+docforge skips sources whose `content_hash` matches the stored hash (no changes detected). To force re-ingest, clear the hash: `UPDATE sources SET content_hash = NULL;` then run `docforge ingest`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Credits
+
+docforge stands on open shoulders:
+
+- [EmbeddingGemma-300M](https://huggingface.co/google/embeddinggemma-300m) — open-weights embedding model under the Gemma license.
+- [pgvector](https://github.com/pgvector/pgvector) — vector similarity for Postgres.
+- [FastMCP](https://github.com/PrefectHQ/fastmcp) — MCP server framework.
+- [FastAPI](https://fastapi.tiangolo.com/), [Typer](https://typer.tiangolo.com/), [asyncpg](https://magicstack.github.io/asyncpg/), [sentence-transformers](https://www.sbert.net/) — core infrastructure.

docforge_cli-0.2.0/README.md

@@ -0,0 +1,145 @@
+# docforge
+
+**The self-hosted context engine for AI coding assistants.**
+
+Point docforge at your Confluence spaces and local git repositories. It indexes, embeds, and serves them over MCP — so Claude Code, Cursor, Copilot, and any assistant that speaks MCP can search your team's knowledge without your data leaving your infrastructure.
+
+docforge doesn't replace your AI assistant. It feeds it — turning Claude Code, Cursor, Copilot, and anything else that speaks MCP into tools that actually know your team's docs and code.
+
+[![CI](https://github.com/GranatenUdo/docforge/actions/workflows/ci.yml/badge.svg)](https://github.com/GranatenUdo/docforge/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/docforge-cli.svg)](https://pypi.org/project/docforge-cli/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+## Why docforge
+
+| Tool | Self-hosted | Integration | Confluence + code | Footprint | Complements AI assistants? |
+|---|---|---|---|---|---|
+| **docforge** | ✓ | MCP server | ✓ (Confluence + local git) | Minimal (PG + 1 container) | ✓ (any MCP client) |
+| [Atlassian Rovo MCP](https://www.atlassian.com/blog/announcements/atlassian-rovo-mcp-ga) | ✗ (Cloud-only) | MCP server | Confluence only (Cloud) | SaaS | ✓ |
+| [zilliztech/claude-context](https://github.com/zilliztech/claude-context) | ✓ | MCP server | Code only | Minimal | ✓ |
+| [Onyx](https://github.com/onyx-dot-app/onyx) | ✓ | MCP + chat UI | ✓ (50+ connectors) | Heavy (Standard) / Minimal (Lite) | ✓ (+ its own UI) |
+| Cursor codebase index + @Docs | ✗ | Proprietary | Code + public web docs | SaaS | — (built into Cursor only) |
+| [Copilot Spaces](https://github.com/orgs/community/discussions/180894) | ✗ | Proprietary (MCP for actions) | Code + attachments | SaaS | — (built into Copilot only) |
+| [Sourcegraph Cody](https://sourcegraph.com/docs/cody/enterprise/features) | ✓ (Enterprise) | OpenCtx / MCP | ✓ (via OpenCtx) | Heavy (Sourcegraph platform) | — (built into Cody only) |
+| LangChain / LlamaIndex DIY | ✓ | Whatever you build | You wire it | Depends | Depends |
+
+docforge is the narrow, focused option in this landscape: minimal footprint, MCP-native so it works with every assistant, and combines Confluence + code out of the box. It doesn't compete on connector count (Onyx wins there), visual UX (Cursor and Cody win), or SaaS convenience (Rovo). It competes on being **small, legible, vendor-neutral, and self-hosted** — four properties no commercial option offers together.
+
+### ✅ When docforge fits
+
+- You run Confluence Data Center/Server, or you want to self-host.
+- Your team uses MCP-capable assistants (Claude Code, Cursor with MCP, Copilot with MCP, etc.).
+- You want Confluence + git repos indexed together with one tool.
+- Operational simplicity matters — one Postgres, one container, MIT-licensed code you can audit in an afternoon.
+
+### ❌ When docforge is the wrong choice
+
+- You need 50+ connectors (Slack, Jira, Gmail, Drive, Notion) → use **[Onyx](https://github.com/onyx-dot-app/onyx)** or **[Glean](https://www.glean.com/)**.
+- You need per-document ACLs enforced at query time → not yet supported; use **Onyx**.
+- You need a chat UI for non-developers → docforge has no UI; use **Onyx**, **Glean**, or **Cody**.
+- You're on Atlassian Cloud and happy with SaaS → **[Atlassian Rovo MCP](https://www.atlassian.com/blog/announcements/atlassian-rovo-mcp-ga)** is free and official.
+- You need SSO / SCIM / RBAC → out of scope; docforge authenticates but doesn't authorize per-resource.
+- Your corpus is very large (>100K pages/chunks) → dense-only retrieval without hybrid starts to degrade; on the [roadmap](ROADMAP.md).
+- You need near-real-time updates → ingest is batch; no webhook-driven continuous sync yet.
+- You need multilingual search evaluated → EmbeddingGemma is multilingual, but docforge has no eval coverage on non-English corpora yet.
+
+## Quick Start
+
+```bash
+pip install docforge-cli
+docforge init my-project
+cd my-project
+# Edit docforge.yml with your Confluence URL
+# Edit sources.yml with your page IDs and local git repo paths
+# Edit .env with your credentials
+docker compose up -d db
+docforge init-db
+docforge ingest
+docforge serve
+```
+
+**Note:** The git crawler indexes **local filesystem paths** — docforge does not clone GitHub URLs. Clone first, then point docforge at the checkout path in `sources.yml`.
+
+## How It Works
+
+1. **Configure** your Confluence URL, page IDs, and local git repo paths in `sources.yml`.
+2. **Ingest** crawls pages and files, chunks text (~500 tokens), generates vector embeddings (768-dim).
+3. **Serve** exposes an MCP server that AI assistants query automatically.
+
+When an AI assistant needs cross-team context, it calls docforge's `search_documentation` MCP tool behind the scenes and gets relevant documentation chunks with source attribution.
+
+### Architecture
+
+![docforge architecture: Confluence and local git repos flow through docforge ingest into Postgres with pgvector, then docforge serve exposes an MCP server consumed by Claude Code, Cursor, and Copilot](docs/assets/architecture.svg)
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `docforge init <name>` | Scaffold a new project with config templates |
+| `docforge init-db` | Initialize the PostgreSQL database schema |
+| `docforge ingest` | Crawl all sources, embed, store in PostgreSQL |
+| `docforge search "<query>"` | Test search from terminal |
+| `docforge serve` | Run MCP server for AI assistants |
+| `docforge serve --api` | Run FastAPI search API (for hosted deployment) |
+| `docforge status` | Show index stats and health |
+
+## Deploy to your infrastructure
+
+For team-wide use, deploy the search API to Azure (~$35/month at default SKUs):
+
+- PostgreSQL Flexible Server (Burstable B1ms, 32 GB) with pgvector.
+- Container App running the FastAPI search API.
+- Container Registry, Key Vault, Log Analytics, managed environment.
+- Team members use a lightweight MCP client that calls the hosted API.
+
+See [`deploy/azure/`](deploy/azure/) for Bicep templates and a full cost breakdown.
+
+## Configuration
+
+See `docs/` for the full configuration reference, including `docforge.yml` and `sources.yml` schemas.
+
+## Contributing
+
+Contributions welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, branch conventions, and PR expectations. Bug reports and feature requests go through [GitHub Issues](https://github.com/GranatenUdo/docforge/issues); open-ended questions and ideas live in [Discussions](https://github.com/GranatenUdo/docforge/discussions).
+
+## Evaluation & retrieval quality
+
+docforge ships with a retrieval-quality eval harness at [`docforge/scripts/eval_search.py`](docforge/scripts/eval_search.py). It measures recall@1, recall@k, and MRR against a ground-truth query set you maintain. The harness is designed for **drift detection** — run it after `sources.yml` changes, embedding-model updates, or ranking tweaks, and compare against your baseline. There is no absolute quality threshold; the metric magnitude depends on how closely your ground-truth queries match source titles. See [`docforge/scripts/README.md`](docforge/scripts/README.md) for details.
+
+## FAQ
+
+### "Cannot connect to PostgreSQL"
+
+Check that the database is running: `docker compose up -d db`. Verify `DATABASE_URL` in `.env` points to `postgresql://docforge:localdev@localhost:5432/docforge` (or your custom value).
+
+### "HF_TOKEN required" or model download fails
+
+The embedding model `google/embeddinggemma-300m` requires a Hugging Face token with access to the gated model. Create one at https://huggingface.co/settings/tokens, accept the model license at https://huggingface.co/google/embeddinggemma-300m, and set `HF_TOKEN=hf_...` in `.env`.
+
+### "No results found" after ingest
+
+Run `docforge status` to confirm sources and chunks exist. If counts are zero, check the ingest logs for per-source failures — the summary at the end lists sources that failed.
+
+### First ingest / first container start is very slow
+
+The first run downloads the 300M embedding model (~1.2 GB) from Hugging Face. Locally, the model is cached at `~/.cache/huggingface/`. In the Docker image, it is cached at `/app/.cache/huggingface/` — **mount this as a volume** so container restarts do not re-download: `docker run -v docforge-hf-cache:/app/.cache/huggingface ...`.
+
+### "Ingest skipped everything"
+
+docforge skips sources whose `content_hash` matches the stored hash (no changes detected). To force re-ingest, clear the hash: `UPDATE sources SET content_hash = NULL;` then run `docforge ingest`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Credits
+
+docforge stands on open shoulders:
+
+- [EmbeddingGemma-300M](https://huggingface.co/google/embeddinggemma-300m) — open-weights embedding model under the Gemma license.
+- [pgvector](https://github.com/pgvector/pgvector) — vector similarity for Postgres.
+- [FastMCP](https://github.com/PrefectHQ/fastmcp) — MCP server framework.
+- [FastAPI](https://fastapi.tiangolo.com/), [Typer](https://typer.tiangolo.com/), [asyncpg](https://magicstack.github.io/asyncpg/), [sentence-transformers](https://www.sbert.net/) — core infrastructure.

docforge_cli-0.2.0/docforge/__main__.py

@@ -0,0 +1,5 @@
+"""Module entrypoint — `python -m docforge` dispatches to the Typer app."""
+
+from docforge.cli import app
+
+app()

docforge_cli-0.2.0/docforge/api.py

@@ -0,0 +1,266 @@
+"""FastAPI search API for docforge.
+
+Runs on Azure Container Apps. Loads embedding model at startup,
+serves search queries over HTTP.
+
+Run locally: uvicorn docforge.api:app --reload
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from contextlib import asynccontextmanager
+from typing import Any
+
+import numpy as np
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.security import SecurityScopes
+from pydantic import BaseModel
+
+from docforge.config import Settings
+from docforge.db import close_pool, get_pool
+from docforge.processors.embedder import Embedder
+
+logger = logging.getLogger(__name__)
+
+_embedder: Embedder | None = None
+_settings: Settings | None = None
+_azure_scheme = None  # Populated in lifespan when auth.mode == "entra"
+_cleanup_task: asyncio.Task | None = None
+
+_CLEANUP_INTERVAL_SECONDS = 3600  # one hour — overridable in tests
+
+
+async def _query_log_cleanup_loop(database_url: str, retention_days: int) -> None:
+    """Deletes query_log rows older than retention_days every
+    _CLEANUP_INTERVAL_SECONDS. Idempotent, so multi-replica is safe."""
+    # int() coercion makes the f-string SQL below injection-safe. asyncpg's
+    # $1::interval parameter binding doesn't accept str, hence the literal.
+    days = int(retention_days)
+    while True:
+        try:
+            pool = await get_pool(database_url)
+            async with pool.acquire() as conn:
+                result = await conn.execute(
+                    f"DELETE FROM query_log WHERE created_at < now() - interval '{days} days'"
+                )
+            logger.info("query_log cleanup: %s", result)
+        except Exception as e:
+            logger.exception("query_log cleanup failed: %s", e)
+        await asyncio.sleep(_CLEANUP_INTERVAL_SECONDS)
+
+
+def _get_settings() -> Settings:
+    global _settings
+    if _settings is None:
+        _settings = Settings()
+    return _settings
+
+
+def _build_auth_scheme(settings: Settings):
+    """Return a SingleTenantAzureAuthorizationCodeBearer if mode==entra, else None."""
+    if settings.auth.mode != "entra":
+        return None
+    from fastapi_azure_auth import SingleTenantAzureAuthorizationCodeBearer
+
+    app_client_id = settings.auth.audience.removeprefix("api://")
+    return SingleTenantAzureAuthorizationCodeBearer(
+        app_client_id=app_client_id,
+        tenant_id=settings.auth.tenant_id,
+        scopes={f"{settings.auth.audience}/search": "Search docforge"},
+    )
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Load the embedding model at startup; close the DB pool on shutdown."""
+    global _embedder, _azure_scheme, _cleanup_task
+    settings = _get_settings()
+    _azure_scheme = _build_auth_scheme(settings)
+    if _azure_scheme is not None:
+        await _azure_scheme.openid_config.load_config()
+        logger.info(
+            "Entra auth enabled (tenant=%s, audience=%s)",
+            settings.auth.tenant_id,
+            settings.auth.audience,
+        )
+    logger.info("Loading embedding model...")
+    _embedder = Embedder(settings.embedding_model, hf_token=settings.hf_token.get_secret_value())
+    logger.info("Model loaded: %s (%dd)", _embedder.model_name, _embedder.dimensions)
+
+    _cleanup_task = asyncio.create_task(
+        _query_log_cleanup_loop(settings.database_url, settings.query_log_retention_days)
+    )
+
+    yield
+
+    if _cleanup_task is not None:
+        _cleanup_task.cancel()
+        try:
+            await _cleanup_task
+        except asyncio.CancelledError:
+            pass
+    await close_pool()
+
+
+app = FastAPI(title="docforge", lifespan=lifespan)
+
+
+async def _auth_dependency(request: Request):
+    """Return the authenticated User under auth.mode=entra, None otherwise."""
+    if _azure_scheme is None:
+        return None
+    # Empty SecurityScopes: we don't enforce scope-level authorization beyond
+    # the token validation the scheme itself does. Without this arg the call
+    # signature mismatches what fastapi-azure-auth expects.
+    return await _azure_scheme(request, SecurityScopes())
+
+
+class SearchRequest(BaseModel):
+    query: str
+    user_name: str
+    team_name: str
+    area_name: str | None = None
+    limit: int = 5
+
+
+class SearchResult(BaseModel):
+    text: str
+    section_title: str | None
+    source_title: str
+    source_url: str
+    source_tags: list[str]
+    similarity: float
+
+
+class SearchResponse(BaseModel):
+    results: list[SearchResult]
+    query: str
+    count: int
+
+
+@app.get("/health")
+async def health() -> dict[str, Any]:
+    """Health check endpoint."""
+    return {
+        "status": "ok",
+        "model": _embedder.model_name if _embedder else "not loaded",
+    }
+
+
+@app.post("/search", response_model=SearchResponse)
+async def search(req: SearchRequest, user=Depends(_auth_dependency)) -> SearchResponse:
+    """Search indexed documentation by semantic similarity."""
+    start = time.perf_counter()
+    if not _embedder:
+        raise HTTPException(status_code=503, detail="Embedding model not loaded yet")
+
+    try:
+        query_vector = _embedder.embed_query(req.query)
+    except Exception as e:
+        logger.error("Embedding failed: %s", e)
+        raise HTTPException(status_code=500, detail="Failed to embed query")
+
+    settings = _get_settings()
+    user_tags = [req.team_name] + ([req.area_name] if req.area_name else [])
+
+    try:
+        pool = await get_pool(settings.database_url)
+        async with pool.acquire() as conn:
+            rows = await conn.fetch(
+                """
+                SELECT
+                    c.text,
+                    c.section_title,
+                    s.title AS source_title,
+                    s.url AS source_url,
+                    s.tags AS source_tags,
+                    1 - (c.embedding <=> $1::vector) AS similarity,
+                    (1 - (c.embedding <=> $1::vector)) *
+                        (1
+                         + $2::float * cardinality(
+                             ARRAY(SELECT unnest(s.tags) INTERSECT SELECT unnest($3::text[]))
+                           )
+                         + $4::float * (CASE WHEN 'org' = ANY(s.tags) THEN 1 ELSE 0 END)
+                        ) AS boosted_score
+                FROM chunks c
+                JOIN sources s ON c.source_id = s.id
+                WHERE s.status = 'active'
+                ORDER BY boosted_score DESC
+                LIMIT $5
+                """,
+                np.array(query_vector, dtype=np.float32),
+                settings.tag_match_weight,
+                user_tags,
+                settings.org_tag_weight,
+                req.limit,
+            )
+    except Exception as e:
+        logger.error("Database error during search: %s", e)
+        raise HTTPException(status_code=503, detail="Database unavailable")
+
+    from docforge.query_log import log_query
+
+    request_ms = int((time.perf_counter() - start) * 1000)
+
+    # team_name and area_name remain self-declared (routing hints, not identity).
+    # user_name and user_oid come from the token when present.
+    await log_query(
+        pool,
+        user.preferred_username if user else req.user_name,
+        req.team_name,
+        req.area_name,
+        req.query,
+        len(rows),
+        user_oid=user.oid if user else None,
+        request_ms=request_ms,
+    )
+
+    results = [
+        SearchResult(
+            text=row["text"],
+            section_title=row["section_title"],
+            source_title=row["source_title"],
+            source_url=row["source_url"],
+            source_tags=list(row["source_tags"] or []),
+            similarity=float(row["similarity"]),
+        )
+        for row in rows
+    ]
+
+    return SearchResponse(results=results, query=req.query, count=len(results))
+
+
+@app.get("/sources")
+async def list_sources(user=Depends(_auth_dependency)) -> dict[str, Any]:
+    """List all indexed documentation sources."""
+    settings = _get_settings()
+    try:
+        pool = await get_pool(settings.database_url)
+        async with pool.acquire() as conn:
+            rows = await conn.fetch(
+                """
+                SELECT title, url, status, last_crawled_at,
+                       (SELECT count(*) FROM chunks WHERE source_id = s.id) AS chunk_count
+                FROM sources s
+                ORDER BY title
+                """
+            )
+    except Exception as e:
+        logger.error("Database error listing sources: %s", e)
+        raise HTTPException(status_code=503, detail="Database unavailable")
+
+    return {
+        "count": len(rows),
+        "sources": [
+            {
+                "title": row["title"],
+                "url": row["url"],
+                "status": row["status"],
+                "chunk_count": row["chunk_count"],
+            }
+            for row in rows
+        ],
+    }