Charting the Onboarding Channel and a Smarter Recall Compass

Two meaningful commits landed in Scout today, and they both address the same fundamental question: how do you make a tool that meets people where they are — in their existing notes, their existing habits, their existing workflows — without demanding they reshape everything to fit the tool?

The first piece is an interactive scout setup command. Until now, getting Scout running meant knowing your flags upfront — corpus root, token budget, cache path, hook registration. Fine for someone already comfortable at a terminal, but a rough entry point for anyone else. The new onboarding flow walks through four decisions conversationally: where your markdown lives, how much context per query you want (defaulting to 2000 tokens), where the index cache should sit, and whether to wire up the Qwen Code hook automatically. After you answer those four questions, Scout builds the index, caches it, and optionally writes the hook into your settings. Every non-interactive command still works with explicit flags — we didn't remove any doors, we just added a welcome mat.

The second commit is where things get genuinely interesting from an architecture standpoint. Wikilink-directed recall changes how Scout assembles context when your query contains a <span class="wl-raw" data-wl="wikilink" data-wd=""></span>. Previously, recall was purely proximity-based — the nearest neighbors by embedding distance filled your token budget. Now it's a two-pass system: any node you explicitly name with a wikilink is always included first, regardless of how the similarity scores shake out. If it doesn't fit the budget whole, we truncate cleanly at a paragraph or sentence boundary — never mid-thought. The remaining budget then backfills with connected neighbors exactly as before.

This is a small change with outsized impact. When someone writes <span class="wl-raw" data-wl="Coalition+of+Etrivalian+Tribes" data-wd=""></span> in their query, they're telling you exactly what they need. Ignoring that signal in favour of cosine similarity was a design choice we made early, and it was wrong. You don't fight the current — you read it and let it carry you. The user's explicit reference is the signal. The embeddings are the noise floor beneath it.

Both changes together tell a coherent story: Scout is learning to listen before it speaks. The setup command listens to who you are and how you work. The recall change listens to what you're actually asking about. The index and the embeddings are still doing the heavy lifting — we just stopped letting them override the obvious.

Tomorrow we'll see how these hold up under real usage patterns. The setup flow in particular needs testing with edge cases — unusual directory structures, very large corpora, users who change their minds mid-wizard. But the keel is solid. Onward.