Shoalrun documentation framework
For agents
Start with https://www.shoalrun.com/llms.txt for the documentation index, then read the Markdown pages it links. Skip to article. Documentation index. Read this page as Markdown.
How toExperimental

Set up local documentation chat

Build a passage index, configure a chat service, and verify cited answers locally.

Updated
Read as Markdown

Set up a local chat panel, then check that its answers cite the right documentation. Start in the root of a Shoalrun project that already builds, with the CLI available in your terminal.

You need a chat-service account and its API key. Meaning-based retrieval also needs an embedding provider and key. These commands make provider requests; they do not deploy your site.

For keyword-only retrieval, omit retrieval from the example below and omit --embed from the indexing command. You still need the passage index and a chat service.

Set up and try the chat

This example uses Voyage for embeddings and an OpenAI-compatible chat endpoint through OpenRouter. Choose providers and model IDs available to your accounts.

  1. Configure the providers

    Add these sections to docs.config.yaml. Store VOYAGE_API_KEY and OPENROUTER_API_KEY in your terminal environment, not in the YAML file.

    docs.config.yaml
    retrieval:
  embeddings:
    provider: voyage
    model: voyage-4-large
    dimension: 1024
    queryModel: voyage-4-lite

chat:
  provider: openai
  model: deepseek/deepseek-v4-flash
  baseUrl: https://openrouter.ai/api/v1
  keyEnv: OPENROUTER_API_KEY

  2. Build and index the documentation

    Build the site, then split its Markdown pages into passages. --embed sends those passages to the configured embedding provider.

    shoalrun build docs.config.yaml site-dist
shoalrun index site-dist --embed --config docs.config.yaml

  3. Ask a question from the terminal

    Replace the sample question with one that your own pages answer.

    shoalrun ask site-dist "how do I reset my password" --config docs.config.yaml

    Check the answer's citations and open the source pages. Confirm that the sources support the answer, rather than accepting citations alone as proof.

  4. Open the local panel

    Start the server and open the address it prints. Ask the same question in the panel and follow its source links. Stop the server with Ctrl+C when finished.

    shoalrun serve site-dist --ask --config docs.config.yaml

If something goes wrong

A missing-key error names the environment variable to set in the same terminal. For missing or stale sources, rebuild the site and run index again. Keyword-only retrieval can miss questions that use different wording from the pages.

This minimal setup has no relevance scorer to decline out-of-scope questions. Before broader use, review answer checks and hosting limits.

To record local questions, add --log with a path outside the site output. Logging is optional; read question logging before enabling it. The CLI reference defines the other flags and report fields.

Reference while working