@hasna/knowledge 0.2.16 → 0.2.18

package/docs/architecture/ai-native-knowledge-base.md

@@ -249,6 +249,19 @@ The command should:
 7. Record a run ledger with tool calls, sources, costs, outputs, and generated
    records.
 
+The first implementation exposes this as `open-knowledge ask|build <prompt>`
+and the installed `knowledge <prompt>` bin alias. It retrieves read-only context,
+returns a local citation draft by default, optionally calls AI SDK generation via
+`--generate`, records `runs`, `run_events`, and `provider_usage`, and only
+proposes durable wiki updates until the wiki compile/write task owns writes.
+
+Provider-native web search is exposed separately as
+`open-knowledge web search <query>` and MCP `ok_web_search`. Real network access
+is safety-gated; OpenAI and Anthropic use provider web-search tools through AI
+SDK, while DeepSeek remains a future fallback/external-search path. Returned web
+snippets can optionally be filed as read-only `web` source refs for later local
+search and citation.
+
 ## Provider Registry
 
 AI provider setup is BYOK and AI SDK v6 based. The local provider layer tracks:

package/docs/architecture/hybrid-semantic-search.md

@@ -138,6 +138,14 @@ The local context-pack implementation is available through
 search rows using exact-term coverage, citation availability, source freshness,
 and source/wiki authority, then emits excerpts and citation objects that preserve
 source refs, artifact URIs, revision/hash metadata, offsets, and provenance.
+`open-knowledge ask|build <prompt>`, the installed `knowledge <prompt>` alias,
+and MCP `knowledge_ask` wrap this context pack in a run ledger and return a
+citation draft or explicit AI SDK generated answer.
+
+Provider-native web search lives beside local retrieval. `open-knowledge web
+search` and MCP `ok_web_search` are safety-gated, capture provider sources, and
+can file snippets as read-only `web` source refs so later local retrieval treats
+them like other cited sources.
 
 ## Reindexing
 

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@hasna/knowledge",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   "type": "module",
   "bin": {
+    "knowledge": "bin/open-knowledge.js",
     "open-knowledge": "bin/open-knowledge.js",
     "open-knowledge-mcp": "bin/open-knowledge-mcp.js"
   },

package/src/agent.ts

@@ -0,0 +1,367 @@
+import { randomUUID } from 'node:crypto';
+import { migrateKnowledgeDb, openKnowledgeDb } from './knowledge-db';
+import { languageModelFor, normalizeAiSdkUsage, parseModelRef, recordProviderUsage, resolveModelRef } from './providers';
+import { retrieveKnowledgeContext, type KnowledgeContextPack, type RetrievalOptions } from './retrieval';
+import type { KnowledgeConfig } from './workspace';
+
+export interface KnowledgePromptOptions extends Omit<RetrievalOptions, 'query'> {
+  prompt: string;
+  generate?: boolean;
+  approveWrite?: boolean;
+  now?: Date;
+}
+
+export interface KnowledgePromptResult {
+  run_id: string;
+  prompt: string;
+  generated: boolean;
+  provider: string;
+  model: string;
+  answer: string;
+  context: KnowledgeContextPack;
+  citations: KnowledgeContextPack['citations'];
+  proposed_wiki_updates: Array<{
+    kind: 'answer_note';
+    title: string;
+    citations: string[];
+    requires_approval: boolean;
+  }>;
+  write_policy: {
+    approved: boolean;
+    durable_writes_performed: false;
+    reason: string;
+  };
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+    cost_usd: number;
+  };
+  warnings: string[];
+}
+
+function estimateTokens(text: string): number {
+  const words = text.trim().split(/\s+/).filter(Boolean).length;
+  return Math.max(1, Math.ceil(words * 1.25));
+}
+
+function citationLabel(index: number): string {
+  return `C${index + 1}`;
+}
+
+function localAnswer(prompt: string, context: KnowledgeContextPack): string {
+  if (context.excerpts.length === 0) {
+    return `No indexed knowledge matched the prompt: ${prompt}`;
+  }
+  const lines = [
+    `Found ${context.excerpts.length} relevant knowledge excerpt(s) for: ${prompt}`,
+    '',
+    ...context.excerpts.slice(0, 5).map((excerpt, index) => {
+      const citation = context.citations.find((entry) => entry.id === excerpt.citation_id);
+      const ref = citation?.source_ref ?? citation?.source_uri ?? citation?.artifact_path ?? citation?.artifact_uri ?? 'unknown source';
+      return `[${citationLabel(index)}] ${excerpt.text} (${ref})`;
+    }),
+  ];
+  return lines.join('\n');
+}
+
+function promptForModel(prompt: string, context: KnowledgeContextPack): string {
+  const citations = context.citations.map((citation, index) => ({
+    id: citationLabel(index),
+    source_ref: citation.source_ref,
+    source_uri: citation.source_uri,
+    artifact_path: citation.artifact_path,
+    revision: citation.revision,
+    hash: citation.hash,
+    quote: citation.quote,
+  }));
+  const excerpts = context.excerpts.map((excerpt, index) => ({
+    id: citationLabel(index),
+    kind: excerpt.kind,
+    text: excerpt.text,
+    score: excerpt.score,
+  }));
+  return [
+    `Prompt: ${prompt}`,
+    '',
+    'Use only the provided context. Cite claims with citation ids like [C1]. If context is insufficient, say what is missing.',
+    '',
+    `Context excerpts:\n${JSON.stringify(excerpts, null, 2)}`,
+    '',
+    `Citations:\n${JSON.stringify(citations, null, 2)}`,
+  ].join('\n');
+}
+
+function proposedUpdates(prompt: string, context: KnowledgeContextPack): KnowledgePromptResult['proposed_wiki_updates'] {
+  if (context.citations.length === 0) return [];
+  return [{
+    kind: 'answer_note',
+    title: prompt.length > 80 ? `${prompt.slice(0, 77)}...` : prompt,
+    citations: context.citations.map((citation) => citation.id),
+    requires_approval: true,
+  }];
+}
+
+function insertRun(dbPath: string, input: {
+  runId: string;
+  prompt: string;
+  status: string;
+  provider: string;
+  model: string;
+  metadata: Record<string, unknown>;
+  now: string;
+}): void {
+  const db = openKnowledgeDb(dbPath);
+  try {
+    db.run(
+      `INSERT INTO runs (id, type, prompt, status, provider, model, metadata_json, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        input.runId,
+        'knowledge-prompt',
+        input.prompt,
+        input.status,
+        input.provider,
+        input.model,
+        JSON.stringify(input.metadata),
+        input.now,
+        input.now,
+      ],
+    );
+  } finally {
+    db.close();
+  }
+}
+
+function addRunEvent(dbPath: string, input: {
+  runId: string;
+  level: 'info' | 'warn' | 'error';
+  event: string;
+  metadata: Record<string, unknown>;
+  now: string;
+}): void {
+  const db = openKnowledgeDb(dbPath);
+  try {
+    db.run(
+      `INSERT INTO run_events (id, run_id, level, event, metadata_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [
+        `evt_${randomUUID()}`,
+        input.runId,
+        input.level,
+        input.event,
+        JSON.stringify(input.metadata),
+        input.now,
+      ],
+    );
+  } finally {
+    db.close();
+  }
+}
+
+function updateRun(dbPath: string, input: {
+  runId: string;
+  status: string;
+  provider: string;
+  model: string;
+  metadata: Record<string, unknown>;
+  now: string;
+}): void {
+  const db = openKnowledgeDb(dbPath);
+  try {
+    db.run(
+      `UPDATE runs
+       SET status = ?, provider = ?, model = ?, metadata_json = ?, updated_at = ?
+       WHERE id = ?`,
+      [
+        input.status,
+        input.provider,
+        input.model,
+        JSON.stringify(input.metadata),
+        input.now,
+        input.runId,
+      ],
+    );
+  } finally {
+    db.close();
+  }
+}
+
+function recordUsage(dbPath: string, runId: string, usage: KnowledgePromptResult['usage'], provider: string, model: string, now: string, metadata: Record<string, unknown> = {}): void {
+  const db = openKnowledgeDb(dbPath);
+  try {
+    recordProviderUsage(db, {
+      run_id: runId,
+      provider,
+      model,
+      input_tokens: usage.input_tokens,
+      output_tokens: usage.output_tokens,
+      cost_usd: usage.cost_usd,
+      metadata,
+      created_at: now,
+    });
+  } finally {
+    db.close();
+  }
+}
+
+export async function runKnowledgePrompt(options: KnowledgePromptOptions): Promise<KnowledgePromptResult> {
+  const prompt = options.prompt.trim();
+  if (!prompt) throw new Error('Knowledge prompt is required.');
+  const now = (options.now ?? new Date()).toISOString();
+  const runId = `run_${randomUUID()}`;
+  const modelRef = resolveModelRef(options.modelRef ?? 'default', options.config);
+  const parsed = parseModelRef(modelRef);
+
+  migrateKnowledgeDb(options.dbPath);
+  insertRun(options.dbPath, {
+    runId,
+    prompt,
+    status: options.generate ? 'running' : 'dry_run',
+    provider: options.generate ? parsed.provider : 'local',
+    model: options.generate ? parsed.model : 'context-draft',
+    metadata: {
+      semantic: options.semantic === true || options.fake === true || Boolean(options.modelRef),
+      approve_write: options.approveWrite === true,
+      generated: options.generate === true,
+    },
+    now,
+  });
+
+  const { prompt: _prompt, generate: _generate, approveWrite: _approveWrite, now: _now, ...retrievalOptions } = options;
+  const context = await retrieveKnowledgeContext({
+    ...retrievalOptions,
+    query: prompt,
+  });
+  addRunEvent(options.dbPath, {
+    runId,
+    level: 'info',
+    event: 'context_retrieved',
+    metadata: {
+      results: context.results.length,
+      citations: context.citations.length,
+      warnings: context.warnings,
+    },
+    now,
+  });
+
+  let answer = localAnswer(prompt, context);
+  let generated = false;
+  let provider = 'local';
+  let model = 'context-draft';
+  let usage = {
+    input_tokens: estimateTokens(prompt) + context.excerpts.reduce((sum, excerpt) => sum + estimateTokens(excerpt.text), 0),
+    output_tokens: estimateTokens(answer),
+    cost_usd: 0,
+  };
+  const warnings = [...context.warnings];
+
+  if (options.generate) {
+    try {
+      if (options.fake) {
+        generated = true;
+        provider = parsed.provider;
+        model = parsed.model;
+        answer = `Fake generated answer for: ${prompt}\n\n${answer}`;
+      } else {
+        const { generateText } = await import('ai');
+        const languageModel = await languageModelFor(modelRef, {
+          config: options.config,
+          env: options.env,
+        });
+        const result = await generateText({
+          model: languageModel as never,
+          system: 'You answer company knowledge-base prompts using only provided context and citation ids.',
+          prompt: promptForModel(prompt, context),
+        });
+        generated = true;
+        provider = parsed.provider;
+        model = parsed.model;
+        answer = result.text;
+        const normalized = normalizeAiSdkUsage({
+          provider,
+          model,
+          usage: result.usage as Record<string, unknown> | undefined,
+          providerMetadata: result.providerMetadata as Record<string, unknown> | undefined,
+        });
+        usage = {
+          input_tokens: normalized.input_tokens,
+          output_tokens: normalized.output_tokens,
+          cost_usd: normalized.cost_usd,
+        };
+      }
+    } catch (error) {
+      addRunEvent(options.dbPath, {
+        runId,
+        level: 'error',
+        event: 'answer_generation_failed',
+        metadata: { message: error instanceof Error ? error.message : String(error) },
+        now,
+      });
+      updateRun(options.dbPath, {
+        runId,
+        status: 'failed',
+        provider: parsed.provider,
+        model: parsed.model,
+        metadata: {
+          generated: false,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        now,
+      });
+      throw error;
+    }
+  }
+
+  const updates = proposedUpdates(prompt, context);
+  const writePolicy = {
+    approved: options.approveWrite === true,
+    durable_writes_performed: false as const,
+    reason: options.approveWrite
+      ? 'Approval flag recorded; durable wiki writing is deferred to the wiki compile task.'
+      : 'Dry-run mode: proposed wiki updates require approval before durable writes.',
+  };
+  addRunEvent(options.dbPath, {
+    runId,
+    level: 'info',
+    event: generated ? 'answer_generated' : 'answer_drafted',
+    metadata: {
+      provider,
+      model,
+      proposed_updates: updates.length,
+      durable_writes_performed: false,
+    },
+    now,
+  });
+  recordUsage(options.dbPath, runId, usage, provider, model, now, {
+    generated,
+    citations: context.citations.length,
+  });
+  updateRun(options.dbPath, {
+    runId,
+    status: generated ? 'completed' : 'dry_run',
+    provider,
+    model,
+    metadata: {
+      generated,
+      citations: context.citations.length,
+      proposed_updates: updates.length,
+      approve_write: options.approveWrite === true,
+    },
+    now,
+  });
+
+  return {
+    run_id: runId,
+    prompt,
+    generated,
+    provider,
+    model,
+    answer,
+    context,
+    citations: context.citations,
+    proposed_wiki_updates: updates,
+    write_policy: writePolicy,
+    usage,
+    warnings,
+  };
+}

package/src/cli.ts

@@ -9,6 +9,7 @@ import { openKnowledgeDb } from './knowledge-db';
 import { createKnowledgeService } from './service';
 import { assertProviderCredentials, parseModelRef, resolveModelRef, type AiProviderId } from './providers';
 import { approvalStatus, assertS3ReadAllowed, assertWebSearchAllowed, createApprovalGate, recordAuditEvent, recordRedactionFindings, redactSecrets } from './safety';
+import { basename } from 'node:path';
 import pkg from '../package.json' with { type: 'json' };
 
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
@@ -51,6 +52,11 @@ interface Flags {
   dimensions?: number;
   semantic?: boolean;
   context?: boolean;
+  generate?: boolean;
+  approveWrite?: boolean;
+  provider?: string;
+  domain?: string[];
+  fileResults?: boolean;
   noColor?: boolean;
   scope?: string;
   olderThan?: number;
@@ -65,12 +71,13 @@ interface ParseResult {
   flags: Flags;
 }
 
-const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'storage', 'db', 'wiki', 'source', 'ingest', 'reindex', 'search', 'embeddings', 'providers', 'safety', 'help'];
+const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'storage', 'db', 'wiki', 'source', 'ingest', 'reindex', 'search', 'web', 'ask', 'build', 'embeddings', 'providers', 'safety', 'help'];
 const COMMAND_ALIASES: Record<string, string> = {
   ls: 'list',
   rm: 'delete',
   edit: 'update',
   unarchive: 'restore',
+  knowledge: 'ask',
 };
 
 function parseArgs(argv: string[]): ParseResult {
@@ -105,6 +112,11 @@ function parseArgs(argv: string[]): ParseResult {
       case '--dimensions': flags.dimensions = Number(argv[i + 1]); i += 1; break;
       case '--semantic': flags.semantic = true; break;
       case '--context': flags.context = true; break;
+      case '--generate': flags.generate = true; break;
+      case '--approve-write': flags.approveWrite = true; break;
+      case '--provider': flags.provider = argv[i + 1]; i += 1; break;
+      case '--domain': flags.domain = [...(flags.domain ?? []), argv[i + 1]]; i += 1; break;
+      case '--file-results': flags.fileResults = true; break;
       case '--fake': flags.fake = true; break;
       case '--no-color': flags.noColor = true; break;
       case '--scope': flags.scope = argv[i + 1]; i += 1; break;
@@ -151,6 +163,10 @@ function suggestCommand(input: string): string {
   return bestScore <= 3 ? best : '';
 }
 
+function invokedAsKnowledge(): boolean {
+  return basename(process.argv[1] ?? '') === 'knowledge';
+}
+
 function printGlobalHelp(): void {
   console.log(`open-knowledge - local agent knowledge store
 
@@ -180,6 +196,8 @@ Commands:
   ingest source <source-ref>   Ingest a read-only source ref into knowledge.db
   reindex outbox <file|s3://>  Consume open-files change events and invalidate chunks
   search <query>               Hybrid search sources, wiki pages, indexes, or context
+  web search <query>           Provider-native web search with citations
+  ask|build <prompt>           Build a read-only citation answer/context pack
   embeddings status|index|search Build/query local vector embeddings
   providers status|models|check Inspect AI SDK provider config and credentials
   safety status|check|approve|audit|redact
@@ -193,6 +211,11 @@ Global Options:
   --dimensions <n>             Embedding dimensions for local/fake providers
   --semantic                   Include vector semantic results in search
   --context                    Return a reranked citation context pack for search
+  --generate                   Call AI SDK text generation for ask/build
+  --approve-write              Record approval intent for future durable wiki writes
+  --provider <name>            Provider override for web search
+  --domain <domain>            Restrict provider web search to a domain
+  --file-results               File web snippets as web source refs
   --fake                       Use deterministic fake embeddings for local tests
   --scope local|global|project  Store scope (default: global ~/.hasna/apps/knowledge/)
   --no-color                  Disable color output
@@ -255,6 +278,8 @@ function printCommandHelp(command: string): void {
   if (command === 'ingest') { console.log('Usage: open-knowledge ingest manifest <file|s3://bucket/key> | source <source-ref> [--purpose knowledge_index] [--scope local|global|project] [--json]'); return; }
   if (command === 'reindex') { console.log('Usage: open-knowledge reindex outbox <file|s3://bucket/key> [--scope local|global|project] [--json]'); return; }
   if (command === 'search') { console.log('Usage: open-knowledge search <query> [--context] [--semantic] [--model openai:text-embedding-3-small] [--limit <n>] [--dimensions <n>] [--fake] [--scope local|global|project] [--json]'); return; }
+  if (command === 'web') { console.log('Usage: open-knowledge web search <query> [--provider openai|anthropic] [--model provider:model] [--domain <domain>] [--file-results] [--fake] [--scope local|global|project] [--json]'); return; }
+  if (command === 'ask' || command === 'build' || command === 'knowledge') { console.log('Usage: open-knowledge ask|build <prompt> [--generate] [--semantic] [--model default|provider:model] [--approve-write] [--scope local|global|project] [--json]'); return; }
   if (command === 'embeddings') { console.log('Usage: open-knowledge embeddings status|index|search [query] [--model openai:text-embedding-3-small] [--limit <n>] [--dimensions <n>] [--fake] [--scope local|global|project] [--json]'); return; }
   if (command === 'providers') { console.log('Usage: open-knowledge providers status|models|check [provider|model-alias] [--scope local|global|project] [--json]'); return; }
   if (command === 'safety') { console.log('Usage: open-knowledge safety status|check|approve|audit|redact [args] [--scope local|global|project] [--json]'); return; }
@@ -302,18 +327,23 @@ async function run(argv: string[]): Promise<void> {
   if (flags.completions) {
     const shell = flags.completions;
     if (shell === 'bash') {
-      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search embeddings providers safety help ls rm edit unarchive --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --semantic --context --fake --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
+      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --semantic --context --generate --approve-write --provider --domain --file-results --fake --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
     } else if (shell === 'zsh') {
-      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search embeddings providers safety help ls rm edit unarchive)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--semantic)--semantic" "(--context)--context" "(--fake)--fake" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--model)--model[model ref]:" "(--dimensions)--dimensions[embedding dimensions]:number:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
+      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--semantic)--semantic" "(--context)--context" "(--generate)--generate" "(--approve-write)--approve-write" "(--file-results)--file-results" "(--fake)--fake" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--model)--model[model ref]:" "(--dimensions)--dimensions[embedding dimensions]:number:" "(--provider)--provider[provider]:" "(--domain)--domain[domain]:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
     } else if (shell === 'fish') {
-      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search embeddings providers safety help ls rm edit unarchive"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -l semantic; complete -c open-knowledge -l context; complete -c open-knowledge -l fake; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l model; complete -c open-knowledge -l dimensions; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
+      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -l semantic; complete -c open-knowledge -l context; complete -c open-knowledge -l generate; complete -c open-knowledge -l approve-write; complete -c open-knowledge -l provider; complete -c open-knowledge -l domain; complete -c open-knowledge -l file-results; complete -c open-knowledge -l fake; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l model; complete -c open-knowledge -l dimensions; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
     } else {
       throw new Error("Invalid --completions value. Use 'bash', 'zsh', or 'fish'.");
     }
     return;
   }
 
-  const command = resolveCommand(positional[0]);
+  let command = resolveCommand(positional[0]);
+  let commandArgOffset = 1;
+  if (invokedAsKnowledge() && command && !COMMANDS.includes(command)) {
+    command = 'ask';
+    commandArgOffset = 0;
+  }
 
   if (!command || flags.help || command === 'help') { printCommandHelp(positional[1]); return; }
 
@@ -613,6 +643,41 @@ async function run(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === 'web') {
+    const action = positional[1] ?? 'search';
+    if (action !== 'search') throw new Error("Invalid web action. Use 'search'.");
+    const query = positional.slice(2).join(' ');
+    if (!query) throw new Error('Usage: open-knowledge web search <query>');
+    const result = await service.webSearch({
+      query,
+      limit: flags.limit,
+      modelRef: flags.model,
+      provider: flags.provider as AiProviderId | undefined,
+      domains: flags.domain,
+      fake: flags.fake,
+      fileResults: flags.fileResults,
+    });
+    output({ ok: true, ...result, message: `${result.sources.length} web source(s)` }, flags.json);
+    return;
+  }
+
+  if (command === 'ask' || command === 'build') {
+    const prompt = positional.slice(commandArgOffset).join(' ');
+    if (!prompt) throw new Error('Usage: open-knowledge ask <prompt>');
+    const result = await service.runPrompt({
+      prompt,
+      limit: flags.limit,
+      semantic: flags.semantic,
+      modelRef: flags.model,
+      dimensions: flags.dimensions,
+      fake: flags.fake,
+      generate: flags.generate,
+      approveWrite: flags.approveWrite,
+    });
+    output({ ok: true, ...result, message: result.generated ? 'Generated answer with citations' : 'Prepared citation context draft' }, flags.json);
+    return;
+  }
+
   if (command === 'providers') {
     const action = positional[1] ?? 'status';
     if (action === 'status') {

package/src/mcp.js

@@ -203,6 +203,43 @@ export function buildServer() {
     }
   });
 
+  registerTool(server, 'knowledge_ask', 'Knowledge prompt answer', 'Answer a prompt using read-only knowledge context and optional AI SDK generation', {
+    scope: scopeField,
+    prompt: z.string().describe('Prompt to answer with the knowledge base'),
+    limit: z.number().optional().describe('Maximum context results'),
+    semantic: z.boolean().optional().describe('Include vector semantic results'),
+    generate: z.boolean().optional().describe('Call AI SDK text generation; omitted returns a local citation draft'),
+    approve_write: z.boolean().optional().describe('Record approval intent for future durable wiki writes'),
+    model: z.string().optional().describe('Model alias/ref, default configured provider default'),
+    dimensions: z.number().optional().describe('Embedding dimensions for deterministic fake mode'),
+    fake: z.boolean().optional().describe('Use deterministic fake embeddings/generation for local tests'),
+  }, async ({ scope, prompt, limit, semantic, generate, approve_write, model, dimensions, fake }) => {
+    const service = createKnowledgeService({ scope });
+    try {
+      return jsonText({ ok: true, ...await service.runPrompt({ prompt, limit, semantic, generate, approveWrite: approve_write, modelRef: model, dimensions, fake }) });
+    } catch (error) {
+      return errorText(error instanceof Error ? error.message : String(error));
+    }
+  });
+
+  registerTool(server, 'ok_web_search', 'Provider web search', 'Run safety-gated provider-native web search and return citations/sources', {
+    scope: scopeField,
+    query: z.string().describe('Web search query'),
+    limit: z.number().optional().describe('Maximum sources'),
+    provider: z.enum(['openai', 'anthropic', 'deepseek']).optional().describe('Provider override'),
+    model: z.string().optional().describe('Model alias/ref'),
+    domains: z.array(z.string()).optional().describe('Allowed domains'),
+    fake: z.boolean().optional().describe('Use deterministic fake web results'),
+    file_results: z.boolean().optional().describe('File web snippets as web source refs'),
+  }, async ({ scope, query, limit, provider, model, domains, fake, file_results }) => {
+    const service = createKnowledgeService({ scope });
+    try {
+      return jsonText({ ok: true, ...await service.webSearch({ query, limit, provider, modelRef: model, domains, fake, fileResults: file_results }) });
+    } catch (error) {
+      return errorText(error instanceof Error ? error.message : String(error));
+    }
+  });
+
   registerTool(server, 'ok_add', 'Add a knowledge item', 'Add a new item to the knowledge store', {
     title: z.string().describe('Item title'),
     content: z.string().describe('Item content/body'),

package/src/providers.ts

@@ -128,7 +128,7 @@ const BUILTIN_ALIASES: Record<string, string> = {
 };
 
 function providerConfig(config?: KnowledgeConfig): AiProvidersConfig {
-  return (config as KnowledgeConfig & { providers?: AiProvidersConfig }).providers ?? {};
+  return (config as KnowledgeConfig & { providers?: AiProvidersConfig } | undefined)?.providers ?? {};
 }
 
 export function providerSettings(config: KnowledgeConfig | undefined, provider: AiProviderId): AiProviderSettings {

package/src/service.ts

@@ -1,4 +1,5 @@
 import { createArtifactStore } from './artifact-store';
+import { runKnowledgePrompt, type KnowledgePromptOptions } from './agent';
 import {
   embeddingIndexStatus,
   indexKnowledgeEmbeddings,
@@ -15,6 +16,7 @@ import { providerStatus, listModelRegistry, type ProviderStatusResult, type Mode
 import { retrieveKnowledgeContext, type RetrievalOptions } from './retrieval';
 import { hybridSearch, type HybridSearchOptions } from './search';
 import { resolveSafetyPolicy } from './safety';
+import { runProviderWebSearch, type WebSearchOptions } from './web-search';
 import {
   recordStorageObjects,
   resolveStorageContract,
@@ -234,6 +236,25 @@ export class KnowledgeService {
       config: this.config(),
     });
   }
+
+  async runPrompt(options: Omit<KnowledgePromptOptions, 'dbPath' | 'config'>) {
+    const workspace = this.ensureWorkspace();
+    return runKnowledgePrompt({
+      ...options,
+      dbPath: workspace.knowledgeDbPath,
+      config: this.config(),
+    });
+  }
+
+  async webSearch(options: Omit<WebSearchOptions, 'dbPath' | 'config' | 'safetyPolicy'>) {
+    const workspace = this.ensureWorkspace();
+    return runProviderWebSearch({
+      ...options,
+      dbPath: workspace.knowledgeDbPath,
+      config: this.config(),
+      safetyPolicy: this.safetyPolicy(),
+    });
+  }
 }
 
 export function createKnowledgeService(options: KnowledgeServiceOptions = {}): KnowledgeService {