RAG Chat Roadmap

A chat layer is useful after the docs have a stable structure. Build the docs first, then index them.

Goal

Let colleagues ask questions such as:

• What does Needs Hub mean?
• How do I launch a worker?
• How do I recover a stuck pending message?
• What is the worker protocol?
• How do I adapt the deploy pipeline to my project?

The assistant should answer from the docs and link to the relevant page.

Source Set

Initial source set:

• this docs site content
• sanitized README
• architecture docs
• operations docs
• changelog entries
• example incident replays

Do not index private runtime state, worker transcripts, credentials, personal notes, or project-specific customer data.

Suggested Architecture

1. Export docs content as Markdown or JSON chunks.
2. Add stable page URLs and headings as metadata.
3. Generate embeddings.
4. Store chunks in a small vector store.
5. Build a chat UI with cited answers.
6. Log unanswered questions as docs backlog.

Guardrails

• Refuse to answer from private or unavailable sources.
• Prefer citations to the docs page over confident general advice.
• Mark implementation details as version-specific.
• Keep setup answers separated from production/deploy advice.

When To Build It

Build RAG/chat after the docs site covers the normal path, recovery path, and team-adoption path. A chat system over incomplete docs will amplify gaps instead of solving them.