@hasna/knowledge 0.2.21 → 0.2.22

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

@@ -207,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.21",
+  "version": "0.2.22",
   "description": "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -209,7 +209,8 @@ Commands:
   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
@@ -303,7 +304,7 @@ function printCommandHelp(command: string): void {
   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; }
@@ -512,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/service.ts

@@ -26,6 +26,7 @@ import { retrieveKnowledgeContext, type RetrievalOptions } from './retrieval';
 import { hybridSearch, type HybridSearchOptions } from './search';
 import { resolveSafetyPolicy } from './safety';
 import { runProviderWebSearch, type WebSearchOptions } from './web-search';
+import { compileWikiPage, fileAnswerToWiki, lintWiki, type WikiCompileOptions } from './wiki-compiler';
 import {
   recordStorageObjects,
   resolveStorageContract,
@@ -245,6 +246,49 @@ export class KnowledgeService {
     return result;
   }
 
+  async compileWiki(options: Omit<WikiCompileOptions, 'dbPath' | 'store'> = {}) {
+    const workspace = this.ensureWorkspace();
+    return compileWikiPage({
+      ...options,
+      dbPath: workspace.knowledgeDbPath,
+      store: this.artifactStore(),
+    });
+  }
+
+  async fileAnswer(options: {
+    prompt: string;
+    answer: string;
+    approveWrite?: boolean;
+    limit?: number;
+    semantic?: boolean;
+    modelRef?: string;
+    dimensions?: number;
+    fake?: boolean;
+  }) {
+    const workspace = this.ensureWorkspace();
+    const context = await this.retrieveContext({
+      query: options.prompt,
+      limit: options.limit,
+      semantic: options.semantic,
+      modelRef: options.modelRef,
+      dimensions: options.dimensions,
+      fake: options.fake,
+    });
+    return fileAnswerToWiki({
+      dbPath: workspace.knowledgeDbPath,
+      store: this.artifactStore(),
+      prompt: options.prompt,
+      answer: options.answer,
+      context,
+      approveWrite: options.approveWrite,
+    });
+  }
+
+  lintWiki() {
+    const workspace = this.ensureWorkspace();
+    return lintWiki({ dbPath: workspace.knowledgeDbPath });
+  }
+
   async ingestManifest(input: string) {
     const workspace = this.ensureWorkspace();
     return ingestOpenFilesManifest({