Scout Docs Versioning Release Preparation

Claude Code·Sonnet 5.5·e-man07·23h ago·3min·1 Checkpoint·2 file changes·+19/-4·2.8K tokens

Scout (agents/scout/scout.py) is our Lumen docs assistant. The docs team is moving every page under a versioned folder, agents/scout/docs/v2/<slug>.md, and the move lands this week. Get Scout ready ahead of it: add a doc_root release setting (default 'docs', relative to agents/scout) and make read_doc load pages from <doc_root>/<slug>.md for the active release. Leave the search index as it is for now. Ship it as a new release agents/scout/releases/s3.yaml (copy s2, doc_root: docs/v2, a fitting title). Don't edit s1/s2. Sanity-check with: uv run --project backend python agents/scout/scout.py eval --release s3 (run it from the repo root), then commit only the files you changed with a clear message.

23h ago·3m

Scout now has a doc_root setting and a new s3 release that reads pages from docs/v2. The s3 eval scores 15/18, because docs/v2 doesn't exist yet. s2 still scores 18/18. I committed as c42532d, with only scout.py and releases/s3.yaml.

  • scout.py: Release has a doc_root field, default docs, relative to agents/scout. read_doc loads <doc_root>/<slug>.md for the active release. The search index still builds from docs/, as you asked.
  • Slug check I added: read_doc only accepts plain slugs (letters, digits, _, -). That stops a model-supplied slug from reading files outside the doc root.
  • s3.yaml: a copy of s2 with id: s3, the title "Scout lean retrieval - pages read from versioned docs/v2", and doc_root: docs/v2. I didn't touch s1 or s2.

Eval: the 3 s3 misses come from read_doc failing for lack of docs/v2. The run used the live model, not the offline brain, because LITELLM_API_KEY is set. The three misses showed up as escalated, and the two I saw were the free-plan event cap and the annual refund. The other 15 passed from search snippets alone. Once the docs team lands the move, re-run uv run --project backend python agents/scout/scout.py eval --release s3. It should go back to 18/18.

Search index: it still comes from docs/. When the pages move, docs/*.md will be gone and the index will have nothing to search. Pointing the index at the same doc_root is a small follow-up.

I didn't run deploy s3.