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

# Knowledge Operations Runbook

> Operate Starfire AI extraction, indexing, embeddings, stale sources, retrieval failures, and Knowledge worker health from Control Center.

# Knowledge operations runbook

Use this runbook when Knowledge sources fail to process, become stale, or do not retrieve as expected.

## 1. Locate the Knowledge Base/source

Confirm owner, Project/organization context, source type, and current processing state.

## 2. Separate ingestion from retrieval

Determine whether the problem is:

* upload/source access
* extraction
* chunking
* embeddings/indexing
* permissions
* retrieval
* reranking
* model interpretation

Do not rebuild the entire index when the failure is only an authorization issue.

## 3. Check indexing workers/providers

If many unrelated sources are stuck in processing/indexing, inspect worker queues and embedding/index provider health.

## 4. Retry failed ingestion

Retry only after confirming the source remains valid and the original failure condition is likely resolved.

## 5. Rebuild or recalculate indexes

Use re-index/re-embedding operations when the index itself is stale or configuration changed. These actions can be expensive; avoid applying them platform-wide without evidence.

## 6. Inspect retrieval

For a ready source that is not returned:

* confirm requester permission
* test a distinctive query
* inspect candidate results when available
* inspect filtering/reranking
* check result/context limits

## 7. Handle stale connected sources

For repositories or connected sources, refresh the upstream revision and confirm the integration still has access.

## 8. Remove duplicates/orphans

Operational cleanup can remove orphaned indexing/storage records when the active backend explicitly identifies them. Do not delete healthy user sources based only on similar names.

## 9. Escalate widespread failure

Create/update an incident when extraction/indexing/retrieval is degraded across many sources or organizations.

<Warning>
  Knowledge administration should expose operational metadata by default. Content access remains a separate permission boundary.
</Warning>