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

# HolyDocs Integration

Sync HolyDocs pages into RogerIQ knowledge and send doc-gap insights back to the docs workflow.

# HolyDocs Integration

RogerIQ has a first-party HolyDocs integration. HolyDocs can sync MDX pages into RogerIQ knowledge, send page context to the widget, receive doc-gap insights, and trigger proactive messages from docs events.

## What HolyDocs Sends to RogerIQ

| Endpoint | Purpose |
| --- | --- |
| `POST /api/projects/:pid/kb/articles:bulk-upsert` | Idempotently sync docs pages into knowledge. |
| `GET /api/projects/:pid/insights/doc-gaps` | Read clustered low-confidence or unresolved support gaps. |
| `POST /api/projects/:pid/proactive/trigger` | Trigger a proactive widget message, often from a changelog publish. |
| `POST /api/integrations/holydocs/widget/page-context` | Public page context endpoint for docs-rendered widget suggestions. |

## Bulk Upsert

HolyDocs sends pages with an `external_source`, stable `external_id`, URL, locale, metadata, and content.

```json
{
  "external_source": "holydocs",
  "full_sync": true,
  "articles": [
    {
      "external_id": "/guides/start",
      "title": "Getting started",
      "content": "...markdown...",
      "external_url": "https://docs.example.com/guides/start",
      "locale": "en",
      "metadata": { "description": "..." },
      "is_public": true
    }
  ]
}
```

Response:

```json
{
  "data": {
    "external_source": "holydocs",
    "total_in_batch": 1,
    "created": 0,
    "updated": 1,
    "unchanged": 0,
    "deleted": 0,
    "errors": []
  }
}
```

## Sync Behavior

- Rows are keyed by `(project_id, external_source, external_id)`.
- Unchanged title and content skips re-vectorization.
- Metadata can still refresh when content is unchanged.
- Vector indexing failures are reported per article without dropping the row.
- `full_sync: true` deletes missing rows for the same external source only.

## OAuth Flow

HolyDocs connects through RogerIQ OAuth with PKCE and receives a RogerIQ access token scoped to the selected organization and project.

Useful scopes:

| Scope | Purpose |
| --- | --- |
| `read` | Read project resources and insights. |
| `write` | Write synced articles and proactive triggers. |
| `kb:write` | Narrow write access to knowledge sync. |
| `insights:read` | Read doc gaps and support insights. |
| `widget:write` | Patch widget config or trigger proactive messages. |

For docs maintained in HolyDocs, prefer HolyDocs sync over crawler ingestion. It keeps stable page IDs, cleaner content, locales, and deploy-time automation.