Help index
Re-embeds Knowledge Center pages so the in-app assistant can find them.
How it works
The in-app assistant uses vector search over a chunked, embedded copy of the Knowledge Center to answer questions. This job rebuilds (or incrementally updates) that index:
- Chunks pages by heading
- Computes embeddings for chunks whose content has changed since the last run
- Writes them to the global
help_chunkstable - Deletes orphans — chunks whose source page is no longer in the input set are removed when running in “full” mode
The job has two modes:
- Incremental — driven by CI/CD after a Knowledge Center publish. The input lists the changed pages and their inline markdown content
- Full reindex — walks the local
contentdirectory (defaults to/help/content). Used when bootstrapping a new deployment or recovering from index corruption
The help index is global, not per-workspace. The job is pinned to the system workspace and refuses to run elsewhere.
When it runs
The job is operator-driven — there is no scheduled trigger. CI/CD invokes it after each Knowledge Center deploy; you can also trigger it manually.
Parameters
| Parameter | Description |
|---|---|
| Content Dir | Path to a local Hugo content directory. Used by the full-reindex mode. Defaults to /help/content |
| Pages | A list of page paths and inline markdown content. Used by the incremental mode |
| Deleted Paths | A list of page paths to drop from the index |
| Full | When set together with Pages, enables orphan cleanup — any chunk whose source path is not in the supplied page set is deleted. Use only when Pages contains the complete content set |
The job is skipped with skipped: true, reason: "embedder not configured" when the deployment has no embedding provider configured.
Job results
| Metric | Description |
|---|---|
files_processed | Number of pages walked |
chunks_created | New chunk rows inserted |
chunks_updated | Existing chunk rows whose embedding was refreshed |
chunks_deleted | Orphan chunk rows removed |
chunks_skipped | Chunks whose content hash matched the existing row (no embed call needed) |
languages | Set of locales seen |
Troubleshooting
| Issue | Solution |
|---|---|
embedder not configured skip | The deployment has no embedding provider. Either configure one, or accept that the assistant search will fall back to keyword search |
| Run fails with permission error | Verify the configured embedder API key is still valid |
| Assistant still returns stale answers | Hard-refresh the assistant session. The vector store is read fresh on each query, but the assistant may have cached recent responses |