@hasna/knowledge 0.2.15 → 0.2.17

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

@@ -223,8 +223,11 @@ generated metadata rows, not raw source bytes, and pins each row to `open-files`
 provenance: source ref/URI, revision/hash, chunk offsets, token count, provider,
 model, dimensions, status, and timestamps. The structured `search` contract
 merges keyword FTS, wiki/index catalog hits, generated wiki chunks, and optional
-vector results so the local SQLite index can later move to pgvector or a managed
-hosted vector store without changing CLI/MCP result shape.
+vector results. `open-knowledge search --context` and MCP `knowledge_search`
+turn those rows into reranked citation context packs with selected excerpts,
+freshness and permission notes, graph evidence, and final rerank scores. The
+local SQLite index can later move to pgvector or a managed hosted vector store
+without changing CLI/MCP result shape.
 
 ## Agent Workflow
 
@@ -246,6 +249,12 @@ 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 Registry
 
 AI provider setup is BYOK and AI SDK v6 based. The local provider layer tracks:

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

@@ -49,14 +49,15 @@ The current local command surface is:
 ```bash
 open-knowledge search "company wiki policy" --scope project --json
 open-knowledge search "company wiki policy" --scope project --semantic --json
+open-knowledge search "company wiki policy" --scope project --context --json
 open-knowledge embeddings index --scope project --model openai:text-embedding-3-small
 open-knowledge embeddings search "company wiki policy" --scope project --json
 ```
 
 `search` is the structured hybrid layer for agents. `embeddings search` is the
 lower-level vector-only command. MCP exposes the same capability through
-`ok_search`, `ok_embeddings_status`, `ok_embeddings_index`, and
-`ok_semantic_search`. Deterministic `--fake` embeddings exist for tests and
+`ok_search`, `knowledge_search`, `ok_embeddings_status`, `ok_embeddings_index`,
+and `ok_semantic_search`. Deterministic `--fake` embeddings exist for tests and
 offline verification only.
 
 ## Hosted Indexes
@@ -132,6 +133,15 @@ They should receive context packs:
 
 This keeps agent prompts stable while the retrieval internals evolve.
 
+The local context-pack implementation is available through
+`open-knowledge search --context` and MCP `knowledge_search`. It reranks merged
+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.
+
 ## Reindexing
 
 Reindexing is driven by source revisions:

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@hasna/knowledge",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "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';
@@ -50,6 +51,9 @@ interface Flags {
   model?: string;
   dimensions?: number;
   semantic?: boolean;
+  context?: boolean;
+  generate?: boolean;
+  approveWrite?: boolean;
   noColor?: boolean;
   scope?: string;
   olderThan?: number;
@@ -64,12 +68,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', '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 {
@@ -103,6 +108,9 @@ function parseArgs(argv: string[]): ParseResult {
       case '--model': flags.model = argv[i + 1]; i += 1; break;
       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 '--fake': flags.fake = true; break;
       case '--no-color': flags.noColor = true; break;
       case '--scope': flags.scope = argv[i + 1]; i += 1; break;
@@ -149,6 +157,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
 
@@ -177,7 +189,8 @@ Commands:
   ingest manifest <file|s3://> Ingest an open-files manifest into knowledge.db
   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, and indexes
+  search <query>               Hybrid search sources, wiki pages, indexes, or context
+  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
@@ -190,6 +203,9 @@ Global Options:
   --model <provider:model>     AI/embedding model ref
   --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
   --fake                       Use deterministic fake embeddings for local tests
   --scope local|global|project  Store scope (default: global ~/.hasna/apps/knowledge/)
   --no-color                  Disable color output
@@ -251,7 +267,8 @@ function printCommandHelp(command: string): void {
   if (command === 'source') { console.log('Usage: open-knowledge source resolve <source-ref> [--purpose knowledge_answer|knowledge_index] [--limit <n>] [--scope local|global|project] [--json]'); return; }
   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> [--semantic] [--model openai:text-embedding-3-small] [--limit <n>] [--dimensions <n>] [--fake] [--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 === '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; }
@@ -299,18 +316,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 --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 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 --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" "(--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 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" "(--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`);
     } 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 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 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 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; }
 
@@ -586,6 +608,18 @@ async function run(argv: string[]): Promise<void> {
   if (command === 'search') {
     const query = positional.slice(1).join(' ');
     if (!query) throw new Error('Usage: open-knowledge search <query>');
+    if (flags.context) {
+      const context = await service.retrieveContext({
+        query,
+        limit: flags.limit,
+        semantic: flags.semantic,
+        modelRef: flags.model,
+        dimensions: flags.dimensions,
+        fake: flags.fake,
+      });
+      output({ ok: true, ...context, message: `${context.excerpts.length} context excerpt(s)` }, flags.json);
+      return;
+    }
     const result = await service.search({
       query,
       limit: flags.limit,
@@ -598,6 +632,23 @@ async function run(argv: string[]): Promise<void> {
     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

@@ -186,6 +186,42 @@ export function buildServer() {
     }
   });
 
+  registerTool(server, 'knowledge_search', 'Knowledge context search', 'Return a reranked citation context pack for agent prompts', {
+    scope: scopeField,
+    query: z.string().describe('Search query or prompt'),
+    limit: z.number().optional().describe('Maximum context results'),
+    semantic: z.boolean().optional().describe('Include vector semantic results'),
+    model: z.string().optional().describe('Embedding model ref, default openai:text-embedding-3-small'),
+    dimensions: z.number().optional().describe('Embedding dimensions for deterministic fake mode'),
+    fake: z.boolean().optional().describe('Use deterministic fake embeddings for local tests'),
+  }, async ({ scope, query, limit, semantic, model, dimensions, fake }) => {
+    const service = createKnowledgeService({ scope });
+    try {
+      return jsonText({ ok: true, ...await service.retrieveContext({ query, limit, semantic, modelRef: model, dimensions, fake }) });
+    } catch (error) {
+      return errorText(error instanceof Error ? error.message : String(error));
+    }
+  });
+
+  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_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 {