How-to guides

Task-oriented recipes — "how do I do X?" Each guide assumes you already know the basics and want to get one thing done.

Task guides

• Run RA locally — get the backend running on your machine for development
• Call the API for a research query — authenticate, run the RAG workflow over the WebSocket, and read a grounded answer
• Configure an organization — set per-tenant feature flags, config keys, and prompt overrides via the /platform API

Operational runbooks

Support and operations procedures for a running RA deployment:

• altaforge-ra-cli setup — one-time setup of the support CLI; do this before any runbook that uses it
• Escalation routing management — manage business areas, services, topics, subtopics, and routing rows
• Escalation sites & site emails — manage escalation sites and their email addresses
• Quick links management — manage the sidebar Quick Links list
• Virtual user & IP allowlist management — manage virtual users and IP-to-user mappings
• Migrate agentic markdown blobs to category-ID paths — one-time data migration
• Migrate legacy document blobs to org-scoped paths — one-time data migration

Adding a docs page (the standard)

• Tutorial → docs/tutorials/ — teaches a beginner by doing.
• How-to → docs/how-to/ — steps to accomplish one task.
• Reference → docs/reference/ — the product contract; the HTTP API rendered from its OpenAPI spec.
• Explanation → docs/explanation/ — the why: design, rationale, standards.

Add the page to nav: in mkdocs.yml. Preview locally with mkdocs serve (deps in docs/requirements.txt).