@hasna/knowledge 0.2.20 → 0.2.22

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

@@ -43,6 +43,14 @@ The future hosted/SaaS wrapper owns:
 The OSS package must stay useful without a hosted account. Hosted mode should be
 an optional remote client over explicit API contracts.
 
+The local hosted-aware contract follows the `open-skills` pattern: `mode` is
+`local` by default, `setup --mode hosted` records `hosted.api_url`, env vars
+`KNOWLEDGE_API_URL` and `KNOWLEDGE_API_KEY` can override local config, and
+credentials live outside project state in `~/.hasna/knowledge/auth.json`.
+`remote contracts` publishes the registry/search/ask/build/sync/status/logs and
+artifact endpoints that a SaaS wrapper can implement. Local use, local search,
+and local artifact generation do not require this remote API.
+
 ## Local Workspace
 
 Project-local state lives at:
@@ -199,6 +207,14 @@ The database catalog tracks every schema, index shard, log partition, wiki page,
 source citation, and generated artifact. Markdown remains the readable layer;
 SQLite/Postgres and object storage carry the scalable catalog.
 
+The first compile/write loop is local and approval-gated. `wiki compile`
+generates cited pages from derived source chunks, creates concept backlinks,
+updates index rows, records storage objects, and appends dated JSONL logs.
+`wiki file-answer` writes answer notes only with `--approve-write`; otherwise it
+returns the dry-run proposal. `wiki lint` checks missing/stale citations,
+duplicates, orphan pages, unresolved source refs, contradiction markers, and
+new-article candidates.
+
 ## Search Model
 
 Search is hybrid:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/knowledge",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   "type": "module",
   "bin": {

package/src/auth.ts

@@ -0,0 +1,123 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import type { KnowledgeConfig } from './workspace';
+
+export interface KnowledgeAuthConfig {
+  api_key: string;
+  email?: string;
+  org_id?: string;
+  org_slug?: string;
+  user_id?: string;
+  api_url?: string;
+  created_at: string;
+}
+
+export interface KnowledgeAuthStatus {
+  authenticated: boolean;
+  source: 'env' | 'file' | 'none';
+  api_url: string;
+  auth_path: string;
+  email: string | null;
+  org_id: string | null;
+  org_slug: string | null;
+  user_id: string | null;
+  api_key_present: boolean;
+}
+
+export const DEFAULT_KNOWLEDGE_API_URL = 'https://knowledge.hasna.xyz';
+
+export function normalizeKnowledgeApiOrigin(apiUrl: string): string {
+  const url = new URL(apiUrl);
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('Knowledge API URL must use http or https.');
+  }
+  const pathname = url.pathname.replace(/\/+$/, '');
+  if (pathname === '/api' || pathname === '/api/v1') {
+    url.pathname = '/';
+  } else if (pathname.endsWith('/api/v1')) {
+    url.pathname = pathname.slice(0, -'/api/v1'.length) || '/';
+  } else if (pathname.endsWith('/api')) {
+    url.pathname = pathname.slice(0, -'/api'.length) || '/';
+  }
+  return url.toString().replace(/\/+$/, '');
+}
+
+export function knowledgeAuthPath(env: Record<string, string | undefined> = process.env): string {
+  if (env.HASNA_KNOWLEDGE_AUTH_PATH) return env.HASNA_KNOWLEDGE_AUTH_PATH;
+  const root = env.HASNA_KNOWLEDGE_AUTH_DIR ?? join(homedir(), '.hasna', 'knowledge');
+  return join(root, 'auth.json');
+}
+
+export function resolveKnowledgeApiUrl(
+  config?: KnowledgeConfig,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  return normalizeKnowledgeApiOrigin(env.KNOWLEDGE_API_URL ?? config?.hosted?.api_url ?? DEFAULT_KNOWLEDGE_API_URL);
+}
+
+export function getKnowledgeAuth(env: Record<string, string | undefined> = process.env): KnowledgeAuthConfig | null {
+  try {
+    const path = knowledgeAuthPath(env);
+    if (!existsSync(path)) return null;
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as KnowledgeAuthConfig;
+    return typeof parsed.api_key === 'string' && parsed.api_key.length > 0 ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveKnowledgeAuth(
+  auth: Omit<KnowledgeAuthConfig, 'created_at'> & { created_at?: string },
+  env: Record<string, string | undefined> = process.env,
+): KnowledgeAuthConfig {
+  const path = knowledgeAuthPath(env);
+  const stored: KnowledgeAuthConfig = {
+    ...auth,
+    api_url: auth.api_url ? normalizeKnowledgeApiOrigin(auth.api_url) : undefined,
+    created_at: auth.created_at ?? new Date().toISOString(),
+  };
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${JSON.stringify(stored, null, 2)}\n`, { mode: 0o600 });
+  return stored;
+}
+
+export function clearKnowledgeAuth(env: Record<string, string | undefined> = process.env): boolean {
+  try {
+    unlinkSync(knowledgeAuthPath(env));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getKnowledgeApiKey(env: Record<string, string | undefined> = process.env): { apiKey: string | null; source: KnowledgeAuthStatus['source'] } {
+  if (env.KNOWLEDGE_API_KEY) return { apiKey: env.KNOWLEDGE_API_KEY, source: 'env' };
+  if (env.HASNA_KNOWLEDGE_API_KEY) return { apiKey: env.HASNA_KNOWLEDGE_API_KEY, source: 'env' };
+  const auth = getKnowledgeAuth(env);
+  return auth?.api_key ? { apiKey: auth.api_key, source: 'file' } : { apiKey: null, source: 'none' };
+}
+
+export function knowledgeAuthStatus(
+  config?: KnowledgeConfig,
+  env: Record<string, string | undefined> = process.env,
+): KnowledgeAuthStatus {
+  const auth = getKnowledgeAuth(env);
+  const key = getKnowledgeApiKey(env);
+  const apiUrl = env.KNOWLEDGE_API_URL
+    ? resolveKnowledgeApiUrl(config, env)
+    : auth?.api_url
+      ? normalizeKnowledgeApiOrigin(auth.api_url)
+      : resolveKnowledgeApiUrl(config, env);
+  return {
+    authenticated: Boolean(key.apiKey),
+    source: key.source,
+    api_url: apiUrl,
+    auth_path: knowledgeAuthPath(env),
+    email: key.source === 'file' ? auth?.email ?? null : null,
+    org_id: key.source === 'file' ? auth?.org_id ?? null : null,
+    org_slug: key.source === 'file' ? auth?.org_slug ?? null : null,
+    user_id: key.source === 'file' ? auth?.user_id ?? null : null,
+    api_key_present: Boolean(key.apiKey),
+  };
+}

package/src/cli.ts

@@ -55,6 +55,13 @@ interface Flags {
   generate?: boolean;
   approveWrite?: boolean;
   provider?: string;
+  mode?: string;
+  apiUrl?: string;
+  apiKey?: string;
+  email?: string;
+  org?: string;
+  orgId?: string;
+  userId?: string;
   domain?: string[];
   fileResults?: boolean;
   full?: boolean;
@@ -72,7 +79,7 @@ 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', 'web', 'ask', 'build', 'embeddings', 'providers', 'safety', 'help'];
+const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'setup', 'auth', 'remote', 'storage', 'db', 'wiki', 'source', 'ingest', 'reindex', 'search', 'web', 'ask', 'build', 'embeddings', 'providers', 'safety', 'help'];
 const COMMAND_ALIASES: Record<string, string> = {
   ls: 'list',
   rm: 'delete',
@@ -116,6 +123,13 @@ function parseArgs(argv: string[]): ParseResult {
       case '--generate': flags.generate = true; break;
       case '--approve-write': flags.approveWrite = true; break;
       case '--provider': flags.provider = argv[i + 1]; i += 1; break;
+      case '--mode': flags.mode = argv[i + 1]; i += 1; break;
+      case '--api-url': flags.apiUrl = argv[i + 1]; i += 1; break;
+      case '--api-key': flags.apiKey = argv[i + 1]; i += 1; break;
+      case '--email': flags.email = argv[i + 1]; i += 1; break;
+      case '--org': flags.org = argv[i + 1]; i += 1; break;
+      case '--org-id': flags.orgId = argv[i + 1]; i += 1; break;
+      case '--user-id': flags.userId = 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 '--full': flags.full = true; break;
@@ -190,9 +204,13 @@ Commands:
   dedupe                       Remove duplicate items by title+content (requires --yes)
   stats                        Show knowledge base statistics
   paths                        Show resolved workspace/store paths
+  setup                        Configure local or hosted mode
+  auth login|whoami|logout     Manage hosted API credentials
+  remote contracts|status      Inspect hosted client contracts/readiness
   storage status|validate      Inspect local/S3 artifact storage contract
   db init|stats                Initialize or inspect local knowledge.db
-  wiki init                    Initialize scalable wiki/schema/index/log artifacts
+  wiki init|compile|file-answer|lint
+                               Initialize, compile, file, or lint wiki artifacts
   source resolve <source-ref>  Resolve read-only source content and citation evidence
   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
@@ -216,6 +234,13 @@ Global Options:
   --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
+  --mode local|hosted          Configure OSS local or hosted-aware mode
+  --api-url <url>              Hosted API origin (or KNOWLEDGE_API_URL)
+  --api-key <key>              Hosted API key for auth login
+  --email <email>              Hosted account email metadata
+  --org <slug>                 Hosted organization slug metadata
+  --org-id <id>                Hosted organization id metadata
+  --user-id <id>               Hosted user id metadata
   --domain <domain>            Restrict provider web search to a domain
   --file-results               File web snippets as web source refs
   --full                       Force full embedding index rebuild
@@ -274,9 +299,12 @@ function printCommandHelp(command: string): void {
   if (command === 'dedupe') { console.log('Usage: open-knowledge dedupe --yes [--json]'); return; }
   if (command === 'stats') { console.log('Usage: open-knowledge stats [--json]'); return; }
   if (command === 'paths') { console.log('Usage: open-knowledge paths [--scope local|global|project] [--json]'); return; }
+  if (command === 'setup') { console.log('Usage: open-knowledge setup --mode local|hosted [--api-url https://...] [--scope local|global|project] [--json]'); return; }
+  if (command === 'auth') { console.log('Usage: open-knowledge auth login|whoami|logout [--api-key <key>] [--email <email>] [--org <slug>] [--api-url https://...] [--scope local|global|project] [--json]'); return; }
+  if (command === 'remote') { console.log('Usage: open-knowledge remote contracts|status [--scope local|global|project] [--json]'); return; }
   if (command === 'storage') { console.log('Usage: open-knowledge storage status|validate [--scope local|global|project] [--json]'); return; }
   if (command === 'db') { console.log('Usage: open-knowledge db init|stats [--scope local|global|project] [--json]'); return; }
-  if (command === 'wiki') { console.log('Usage: open-knowledge wiki init [--scope local|global|project] [--json]'); return; }
+  if (command === 'wiki') { console.log('Usage: open-knowledge wiki init|compile|file-answer|lint [query|prompt] [--title <title>] [--content <answer>] [--approve-write] [--limit <n>] [--scope local|global|project] [--json]'); return; }
   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 status|enqueue|embeddings|outbox [file|s3://bucket/key] [--full] [--fake] [--scope local|global|project] [--json]'); return; }
@@ -330,11 +358,11 @@ 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 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 --full --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 setup auth remote 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 --mode --api-url --api-key --email --org --org-id --user-id --domain --file-results --full --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 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" "(--full)--full" "(--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`);
+      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 setup auth remote 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" "(--full)--full" "(--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]:" "(--mode)--mode"\{local,hosted\}:" "(--api-url)--api-url[hosted API URL]:" "(--api-key)--api-key[hosted API key]:" "(--email)--email[email]:" "(--org)--org[org slug]:" "(--org-id)--org-id[org id]:" "(--user-id)--user-id[user id]:" "(--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 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 full; 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 setup auth remote 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 mode; complete -c open-knowledge -l api-url; complete -c open-knowledge -l api-key; complete -c open-knowledge -l email; complete -c open-knowledge -l org; complete -c open-knowledge -l org-id; complete -c open-knowledge -l user-id; complete -c open-knowledge -l domain; complete -c open-knowledge -l file-results; complete -c open-knowledge -l full; 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'.");
     }
@@ -365,6 +393,84 @@ async function run(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === 'setup') {
+    const result = service.setup({
+      mode: flags.mode,
+      apiUrl: flags.apiUrl,
+    });
+    output(result, flags.json);
+    return;
+  }
+
+  if (command === 'auth') {
+    const action = positional[1] ?? 'whoami';
+    if (action === 'whoami' || action === 'status') {
+      const result = service.authStatus(process.env);
+      output({ ok: true, ...result, message: result.authenticated ? `Authenticated via ${result.source}` : 'Not authenticated' }, flags.json);
+      return;
+    }
+    if (action === 'login') {
+      const apiKey = flags.apiKey ?? process.env.KNOWLEDGE_API_KEY ?? process.env.HASNA_KNOWLEDGE_API_KEY;
+      if (!apiKey) throw new Error('Usage: open-knowledge auth login --api-key <key> [--email <email>]');
+      const auth = service.saveAuth({
+        apiKey,
+        email: flags.email,
+        orgSlug: flags.org,
+        orgId: flags.orgId,
+        userId: flags.userId,
+        apiUrl: flags.apiUrl,
+      }, process.env);
+      output({
+        ok: true,
+        authenticated: true,
+        email: auth.email ?? null,
+        org_slug: auth.org_slug ?? null,
+        api_url: auth.api_url ?? service.authStatus(process.env).api_url,
+        auth_path: service.authStatus(process.env).auth_path,
+        message: `Saved hosted credentials for ${auth.email ?? 'API key'}`,
+      }, flags.json);
+      return;
+    }
+    if (action === 'logout') {
+      const removed = service.clearAuth(process.env);
+      output({ ok: true, removed, message: removed ? 'Removed hosted credentials' : 'No hosted credentials found' }, flags.json);
+      return;
+    }
+    throw new Error("Invalid auth action. Use 'login', 'whoami', or 'logout'.");
+  }
+
+  if (command === 'remote') {
+    const action = positional[1] ?? 'status';
+    if (action === 'contracts' || action === 'contract') {
+      const auth = service.authStatus(process.env);
+      output({
+        ok: true,
+        authenticated: auth.authenticated,
+        api_url: auth.api_url,
+        contract: service.remoteContract(),
+        message: `Remote contract v${service.remoteContract().contract_version}`,
+      }, flags.json);
+      return;
+    }
+    if (action === 'status') {
+      const auth = service.authStatus(process.env);
+      const contract = service.remoteContract();
+      output({
+        ok: true,
+        mode: service.config().mode,
+        authenticated: auth.authenticated,
+        auth_source: auth.source,
+        api_url: auth.api_url,
+        client_ready: Boolean(service.remoteClient(process.env)),
+        contract_version: contract.contract_version,
+        capabilities: contract.capabilities,
+        message: auth.authenticated ? `Remote client ready for ${auth.api_url}` : 'Remote client not authenticated',
+      }, flags.json);
+      return;
+    }
+    throw new Error("Invalid remote action. Use 'contracts' or 'status'.");
+  }
+
   if (command === 'storage') {
     const action = positional[1] ?? 'status';
     if (action === 'status') {
@@ -407,10 +513,47 @@ async function run(argv: string[]): Promise<void> {
 
   if (command === 'wiki') {
     const action = positional[1] ?? 'init';
-    if (action !== 'init') throw new Error("Invalid wiki action. Use 'init'.");
-    const result = await service.initWiki();
-    output({ ok: true, ...result, message: `Initialized wiki layout in ${service.workspace.home}` }, flags.json);
-    return;
+    if (action === 'init') {
+      const result = await service.initWiki();
+      output({ ok: true, ...result, message: `Initialized wiki layout in ${service.workspace.home}` }, flags.json);
+      return;
+    }
+    if (action === 'compile') {
+      const args = positional.slice(2);
+      const sourceRefs = args.filter((arg) => /^(open-files|file|s3|https?):\/\//.test(arg));
+      const query = args.filter((arg) => !/^(open-files|file|s3|https?):\/\//.test(arg)).join(' ');
+      const result = await service.compileWiki({
+        title: flags.title,
+        query: query || flags.search,
+        sourceRefs: sourceRefs.length > 0 ? sourceRefs : undefined,
+        limit: flags.limit,
+      });
+      output({ ok: true, ...result, message: `Compiled wiki page ${result.path}` }, flags.json);
+      return;
+    }
+    if (action === 'file-answer' || action === 'answer') {
+      const prompt = positional.slice(2).join(' ');
+      if (!prompt) throw new Error('Usage: open-knowledge wiki file-answer <prompt> --content <answer> --approve-write');
+      if (!flags.content) throw new Error('Missing --content <answer> for wiki file-answer.');
+      const result = await service.fileAnswer({
+        prompt,
+        answer: flags.content,
+        approveWrite: flags.approveWrite,
+        limit: flags.limit,
+        semantic: flags.semantic,
+        modelRef: flags.model,
+        dimensions: flags.dimensions,
+        fake: flags.fake,
+      });
+      output({ ok: true, ...result }, flags.json);
+      return;
+    }
+    if (action === 'lint') {
+      const result = service.lintWiki();
+      output({ ok: result.ok, ...result, message: result.ok ? 'Wiki lint passed' : `Wiki lint found ${result.issue_count} issue(s)` }, flags.json);
+      return;
+    }
+    throw new Error("Invalid wiki action. Use 'init', 'compile', 'file-answer', or 'lint'.");
   }
 
   if (command === 'safety') {

package/src/remote-client.ts

@@ -0,0 +1,268 @@
+import { getKnowledgeApiKey, resolveKnowledgeApiUrl } from './auth';
+import type { KnowledgeConfig } from './workspace';
+
+export const REMOTE_KNOWLEDGE_CONTRACT_VERSION = 1 as const;
+
+export type RemoteKnowledgeRunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'canceled';
+
+export interface RemoteKnowledgeSourceContract {
+  owner: 'open-files';
+  preferred_ref: 'open-files';
+  allowed_schemes: string[];
+  raw_source_bytes_stored_in_open_knowledge: false;
+}
+
+export interface RemoteKnowledgeArtifactContract {
+  storage_type: 'local' | 's3' | 'managed';
+  uri_prefix: string | null;
+  generated_only: true;
+}
+
+export interface RemoteKnowledgeRegistryContract {
+  contract_version: typeof REMOTE_KNOWLEDGE_CONTRACT_VERSION;
+  service: 'open-knowledge';
+  mode: 'local' | 'hosted';
+  capabilities: string[];
+  endpoints: {
+    registry: string;
+    search: string;
+    ask: string;
+    build: string;
+    sync: string;
+    run_status: string;
+    run_logs: string;
+    run_artifacts: string;
+  };
+  source_contract: RemoteKnowledgeSourceContract;
+  artifact_contract: RemoteKnowledgeArtifactContract;
+}
+
+export interface RemoteKnowledgeRunContract {
+  contract_version: typeof REMOTE_KNOWLEDGE_CONTRACT_VERSION;
+  id?: string;
+  type?: 'search' | 'ask' | 'build' | 'sync' | 'artifact' | 'status';
+  status?: RemoteKnowledgeRunStatus | string;
+  query?: string;
+  prompt?: string;
+  output_preview?: unknown;
+  citations?: unknown[];
+  artifacts?: unknown[];
+  usage?: Record<string, unknown>;
+  created_at?: string;
+  started_at?: string;
+  completed_at?: string;
+  duration_ms?: number;
+  error_code?: string;
+  error_message?: string;
+  error?: string;
+  details?: unknown;
+}
+
+export interface RemoteKnowledgeSearchRequest {
+  query: string;
+  limit?: number;
+  semantic?: boolean;
+  source_refs?: string[];
+}
+
+export interface RemoteKnowledgePromptRequest extends RemoteKnowledgeSearchRequest {
+  prompt: string;
+  generate?: boolean;
+  approve_write?: boolean;
+}
+
+export interface RemoteKnowledgeSyncRequest {
+  source_refs?: string[];
+  artifact_prefix?: string;
+  mode?: 'pull' | 'push' | 'both';
+}
+
+export interface RemoteKnowledgeLogEntry {
+  id?: string;
+  run_id?: string;
+  level?: string;
+  event?: string;
+  metadata?: Record<string, unknown>;
+  created_at?: string;
+}
+
+export interface RemoteKnowledgeArtifact {
+  id?: string;
+  uri?: string;
+  key?: string;
+  kind?: string;
+  content_type?: string;
+  hash?: string;
+  size_bytes?: number;
+  metadata?: Record<string, unknown>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function stringValue(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+function numberValue(record: Record<string, unknown>, key: string): number | undefined {
+  const value = record[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function arrayValue(record: Record<string, unknown>, key: string): unknown[] | undefined {
+  const value = record[key];
+  return Array.isArray(value) ? value : undefined;
+}
+
+export function normalizeRemoteKnowledgeRunContract(payload: unknown, fallback?: Partial<RemoteKnowledgeRunContract>): RemoteKnowledgeRunContract {
+  const record = isRecord(payload) ? payload : {};
+  return {
+    contract_version: REMOTE_KNOWLEDGE_CONTRACT_VERSION,
+    id: stringValue(record, 'id') ?? fallback?.id,
+    type: (stringValue(record, 'type') as RemoteKnowledgeRunContract['type'] | undefined) ?? fallback?.type,
+    status: stringValue(record, 'status') ?? fallback?.status,
+    query: stringValue(record, 'query') ?? fallback?.query,
+    prompt: stringValue(record, 'prompt') ?? fallback?.prompt,
+    output_preview: Object.prototype.hasOwnProperty.call(record, 'output_preview') ? record.output_preview : fallback?.output_preview,
+    citations: arrayValue(record, 'citations') ?? fallback?.citations,
+    artifacts: arrayValue(record, 'artifacts') ?? fallback?.artifacts,
+    usage: isRecord(record.usage) ? record.usage : fallback?.usage,
+    created_at: stringValue(record, 'created_at') ?? fallback?.created_at,
+    started_at: stringValue(record, 'started_at') ?? fallback?.started_at,
+    completed_at: stringValue(record, 'completed_at') ?? fallback?.completed_at,
+    duration_ms: numberValue(record, 'duration_ms') ?? fallback?.duration_ms,
+    error_code: stringValue(record, 'error_code') ?? fallback?.error_code,
+    error_message: stringValue(record, 'error_message') ?? fallback?.error_message,
+    error: stringValue(record, 'error') ?? fallback?.error,
+    details: Object.prototype.hasOwnProperty.call(record, 'details') ? record.details : fallback?.details,
+  };
+}
+
+export function knowledgeRegistryContract(input: {
+  mode: 'local' | 'hosted';
+  sourceSchemes: string[];
+  storageType: 'local' | 's3' | 'managed';
+  artifactUriPrefix: string | null;
+}): RemoteKnowledgeRegistryContract {
+  return {
+    contract_version: REMOTE_KNOWLEDGE_CONTRACT_VERSION,
+    service: 'open-knowledge',
+    mode: input.mode,
+    capabilities: [
+      'registry',
+      'search',
+      'ask',
+      'build',
+      'sync',
+      'status',
+      'logs',
+      'artifacts',
+      'open-files-source-refs',
+      's3-generated-artifacts',
+    ],
+    endpoints: {
+      registry: '/api/v1/knowledge/registry',
+      search: '/api/v1/knowledge/search',
+      ask: '/api/v1/knowledge/ask',
+      build: '/api/v1/knowledge/build',
+      sync: '/api/v1/knowledge/sync',
+      run_status: '/api/v1/knowledge/runs/{run_id}',
+      run_logs: '/api/v1/knowledge/runs/{run_id}/logs',
+      run_artifacts: '/api/v1/knowledge/runs/{run_id}/artifacts',
+    },
+    source_contract: {
+      owner: 'open-files',
+      preferred_ref: 'open-files',
+      allowed_schemes: input.sourceSchemes,
+      raw_source_bytes_stored_in_open_knowledge: false,
+    },
+    artifact_contract: {
+      storage_type: input.storageType,
+      uri_prefix: input.artifactUriPrefix,
+      generated_only: true,
+    },
+  };
+}
+
+export class RemoteKnowledgeClient {
+  constructor(
+    private readonly apiKey: string,
+    private readonly apiUrl: string,
+  ) {}
+
+  static fromConfig(config?: KnowledgeConfig, env: Record<string, string | undefined> = process.env): RemoteKnowledgeClient | null {
+    const key = getKnowledgeApiKey(env);
+    if (!key.apiKey) return null;
+    return new RemoteKnowledgeClient(key.apiKey, resolveKnowledgeApiUrl(config, env));
+  }
+
+  private async request(path: string, options: RequestInit = {}): Promise<Response> {
+    return fetch(`${this.apiUrl}${path}`, {
+      ...options,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+    });
+  }
+
+  async registry(): Promise<RemoteKnowledgeRegistryContract> {
+    const response = await this.request('/api/v1/knowledge/registry');
+    return response.json() as Promise<RemoteKnowledgeRegistryContract>;
+  }
+
+  async search(request: RemoteKnowledgeSearchRequest): Promise<RemoteKnowledgeRunContract> {
+    const response = await this.request('/api/v1/knowledge/search', {
+      method: 'POST',
+      body: JSON.stringify(request),
+    });
+    return normalizeRemoteKnowledgeRunContract(await response.json(), { type: 'search', query: request.query });
+  }
+
+  async ask(request: RemoteKnowledgePromptRequest): Promise<RemoteKnowledgeRunContract> {
+    const response = await this.request('/api/v1/knowledge/ask', {
+      method: 'POST',
+      body: JSON.stringify(request),
+    });
+    return normalizeRemoteKnowledgeRunContract(await response.json(), { type: 'ask', prompt: request.prompt });
+  }
+
+  async build(request: RemoteKnowledgePromptRequest): Promise<RemoteKnowledgeRunContract> {
+    const response = await this.request('/api/v1/knowledge/build', {
+      method: 'POST',
+      body: JSON.stringify(request),
+    });
+    return normalizeRemoteKnowledgeRunContract(await response.json(), { type: 'build', prompt: request.prompt });
+  }
+
+  async sync(request: RemoteKnowledgeSyncRequest = {}): Promise<RemoteKnowledgeRunContract> {
+    const response = await this.request('/api/v1/knowledge/sync', {
+      method: 'POST',
+      body: JSON.stringify(request),
+    });
+    return normalizeRemoteKnowledgeRunContract(await response.json(), { type: 'sync' });
+  }
+
+  async runStatus(runId: string): Promise<RemoteKnowledgeRunContract | null> {
+    const response = await this.request(`/api/v1/knowledge/runs/${encodeURIComponent(runId)}`);
+    if (!response.ok) return null;
+    return normalizeRemoteKnowledgeRunContract(await response.json(), { id: runId, type: 'status' });
+  }
+
+  async runLogs(runId: string): Promise<RemoteKnowledgeLogEntry[]> {
+    const response = await this.request(`/api/v1/knowledge/runs/${encodeURIComponent(runId)}/logs`);
+    if (!response.ok) return [];
+    const payload = await response.json();
+    return Array.isArray(payload) ? payload as RemoteKnowledgeLogEntry[] : [];
+  }
+
+  async runArtifacts(runId: string): Promise<RemoteKnowledgeArtifact[]> {
+    const response = await this.request(`/api/v1/knowledge/runs/${encodeURIComponent(runId)}/artifacts`);
+    if (!response.ok) return [];
+    const payload = await response.json();
+    return Array.isArray(payload) ? payload as RemoteKnowledgeArtifact[] : [];
+  }
+}