@hasna/knowledge 0.2.21 → 0.2.23

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:
@@ -237,6 +245,20 @@ 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.
 
+MCP has a stable agent-facing contract layered over the older `ok_*`
+compatibility tools. Agents should prefer `knowledge_search`, `knowledge_ask`,
+`knowledge_build`, `knowledge_get`, `knowledge_ingest`,
+`knowledge_web_search`, `knowledge_lint`, `knowledge_run_status`,
+`knowledge_storage`, and `knowledge_resolve_source`. The same server publishes
+project-scope JSON resources at `knowledge://project/config`,
+`knowledge://project/storage`, `knowledge://project/schema`,
+`knowledge://project/sources`, `knowledge://project/open-files`,
+`knowledge://project/wiki/pages`, `knowledge://project/indexes`,
+`knowledge://project/runs`, and `knowledge://project/decisions`, plus templated
+reads for individual items, sources, wiki pages, indexes, runs, and decisions.
+These resources expose derived chunks, generated wiki artifacts, citations, run
+ledgers, and storage/index metadata without exposing raw source bytes.
+
 Index freshness is explicit. `reindex_queue` tracks missing or stale embedding
 work, `open-knowledge reindex status|enqueue|embeddings` operates the local
 queue, and MCP exposes the same controls through `ok_reindex_status`,

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

@@ -59,11 +59,11 @@ 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`, `knowledge_search`, `ok_embeddings_status`, `ok_embeddings_index`,
-`ok_semantic_search`, `ok_reindex_status`, `ok_reindex_enqueue`, and
-`ok_reindex_embeddings`. Deterministic `--fake` embeddings exist for tests and
-offline verification only.
+lower-level vector-only command. MCP exposes the agent-facing path through
+`knowledge_search`, `knowledge_ask`, `knowledge_build`, `knowledge_get`,
+`knowledge_run_status`, and `knowledge_lint`, with lower-level compatibility
+tools for `ok_search`, embeddings, and reindexing. Deterministic `--fake`
+embeddings exist for tests and offline verification only.
 
 ## Hosted Indexes
 
@@ -144,13 +144,14 @@ 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.
+and MCP `knowledge_ask|knowledge_build` 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.
+search` and MCP `knowledge_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. The lower-level `ok_web_search`
+tool remains for compatibility.
 
 ## Reindexing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/knowledge",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "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') {