test(knowledge): add credential discovery tests + update QueryRouter docs

Add 9 unit tests validating that platform-corpus.json contains all FAQ
entries for agentic credential setup (Gmail, extension credentials, file
discovery, wunderland connect) and that they are reachable through
KeywordFallback search. Update QUERY_ROUTER.md with agentic credential
discovery documentation.

Author: jddunn

docs/QUERY_ROUTER.md

@@ -111,6 +111,18 @@ User project docs     (your ./docs, ./guides, etc.)
 
 This means an agent can answer questions like "What vector stores does AgentOS support?" or "How do I set up a Bluesky channel?" without any project-specific documentation — the answer comes from the bundled platform knowledge.
 
+### Agentic Credential Discovery
+
+A key application of platform knowledge is **agentic credential setup**. The corpus includes dedicated FAQ entries for:
+
+- **Gmail setup** (`faq:setup-gmail`): Step-by-step instructions for creating a Google Cloud project, enabling the Gmail API, downloading the `client_secret_*.json` file, and running the OAuth flow via `wunderland connect gmail --credentials`.
+- **General credential setup** (`faq:setup-credentials-general`): The universal pattern for helping users configure any extension — discover what's needed via `discover_capabilities`, find files via `shell_execute`, parse them via `file_read`, and persist credentials.
+- **Extension credentials reference** (`faq:extension-credentials`): Complete listing of what environment variables each extension requires (GITHUB_TOKEN, DISCORD_BOT_TOKEN, ELEVENLABS_API_KEY, etc.).
+- **File discovery** (`faq:find-credential-files`): How to locate downloaded credential files on the user's system (checking ~/Downloads, ~/Desktop, ~/.aws, ~/.ssh).
+- **wunderland connect reference** (`faq:wunderland-connect`): Command reference for the OAuth-based connect flow with all supported services and the `--credentials` flag.
+
+When a user asks "help me set up Gmail" or "I downloaded a credentials file", the NL intent classifier routes to the connect flow, and the agent uses these knowledge entries combined with agentic tools (`shell_execute`, `file_read`) to guide the user through credential setup without any hard-coded logic in the CLI itself.
+
 ### Configuration
 
 Platform knowledge is enabled by default. To disable it:

src/query-router/__tests__/credential-knowledge.test.ts

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview Tests for credential setup knowledge in the platform corpus.
+ *
+ * Validates that the bundled platform-corpus.json contains all FAQ entries
+ * required for the agentic credential discovery flow (Gmail setup, extension
+ * credentials, file discovery, wunderland connect reference) and that these
+ * entries are surfaced through the KeywordFallback search engine.
+ *
+ * @module @framers/agentos/query-router/__tests__/credential-knowledge
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { KeywordFallback } from '../KeywordFallback.js';
+
+// ---------------------------------------------------------------------------
+// Corpus loading
+// ---------------------------------------------------------------------------
+
+/** Path to the bundled platform knowledge corpus. */
+const corpusPath = resolve(__dirname, '../../../knowledge/platform-corpus.json');
+
+/** Parsed platform corpus entries. */
+const corpus: Array<{ id: string; heading: string; content: string; category: string }> =
+  JSON.parse(readFileSync(corpusPath, 'utf-8'));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Converts raw corpus entries into CorpusChunk-shaped objects suitable for
+ * KeywordFallback. The sourcePath follows the convention `platform:<category>/<id>`.
+ */
+function toChunks() {
+  return corpus.map((e) => ({
+    id: e.id,
+    heading: e.heading,
+    content: e.content,
+    sourcePath: `platform:${e.category}/${e.id}`,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Tests — FAQ entry existence
+// ---------------------------------------------------------------------------
+
+describe('Credential setup knowledge in platform corpus', () => {
+  it('contains Gmail setup FAQ', () => {
+    const gmail = corpus.find((e) => e.id === 'faq:setup-gmail');
+    expect(gmail).toBeDefined();
+    expect(gmail!.content).toContain('client_secret');
+    expect(gmail!.content).toContain('GOOGLE_CLIENT_ID');
+  });
+
+  it('contains general credential setup FAQ', () => {
+    const general = corpus.find((e) => e.id === 'faq:setup-credentials-general');
+    expect(general).toBeDefined();
+    expect(general!.content).toContain('discover_capabilities');
+    expect(general!.content).toContain('shell_execute');
+    expect(general!.content).toContain('file_read');
+  });
+
+  it('contains extension credentials reference', () => {
+    const creds = corpus.find((e) => e.id === 'faq:extension-credentials');
+    expect(creds).toBeDefined();
+    expect(creds!.content).toContain('GITHUB_TOKEN');
+    expect(creds!.content).toContain('DISCORD_BOT_TOKEN');
+    expect(creds!.content).toContain('ELEVENLABS_API_KEY');
+  });
+
+  it('contains file discovery FAQ', () => {
+    const find = corpus.find((e) => e.id === 'faq:find-credential-files');
+    expect(find).toBeDefined();
+    expect(find!.content).toContain('Downloads');
+    expect(find!.content).toContain('shell_execute');
+  });
+
+  it('contains wunderland connect reference', () => {
+    const connect = corpus.find((e) => e.id === 'faq:wunderland-connect');
+    expect(connect).toBeDefined();
+    expect(connect!.content).toContain('--credentials');
+  });
+
+  // -------------------------------------------------------------------------
+  // Tests — keyword search reachability
+  // -------------------------------------------------------------------------
+
+  it('keyword search for "gmail setup" finds the Gmail FAQ', () => {
+    const fallback = new KeywordFallback(toChunks());
+    const results = fallback.search('gmail setup credentials', 5);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.some((r) => r.id.includes('gmail'))).toBe(true);
+  });
+
+  it('keyword search for "API keys needed" finds extension credentials', () => {
+    const fallback = new KeywordFallback(toChunks());
+    const results = fallback.search('what API keys credentials needed', 5);
+    expect(results.length).toBeGreaterThan(0);
+  });
+
+  it('keyword search for "connect gmail" finds wunderland connect reference', () => {
+    const fallback = new KeywordFallback(toChunks());
+    const results = fallback.search('connect gmail wunderland', 5);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.some((r) => r.id.includes('connect') || r.id.includes('gmail'))).toBe(true);
+  });
+
+  it('keyword search for "find credential files" finds the file discovery FAQ', () => {
+    const fallback = new KeywordFallback(toChunks());
+    const results = fallback.search('find credential files downloads', 5);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.some((r) => r.id.includes('credential') || r.id.includes('find'))).toBe(true);
+  });
+});