@hasna/knowledge 0.2.24 → 0.2.26

package/README.md

@@ -122,6 +122,21 @@ knowledge "How do we cite handbook policy?" --scope project --json
 HASNA_KNOWLEDGE_WEB_SEARCH=1 open-knowledge web search "latest AI SDK web search" --provider openai --json
 ```
 
+## Guides
+
+- [Company wiki workflow](docs/examples/company-wiki-workflow.md): an end-to-end
+  local workflow for open-files manifests, search, prompt runs, cited wiki
+  pages, linting, reindexing, MCP, and optional hosted/S3 mode.
+- [JSON to SQLite migration](docs/migration/json-to-sqlite.md): how legacy
+  JSON notes coexist with the `.hasna/apps/knowledge` workspace and the
+  versioned SQLite catalog.
+- [AI-native architecture](docs/architecture/ai-native-knowledge-base.md):
+  source boundaries, wiki model, search model, provider registry, and non-goals.
+- [Hybrid semantic search](docs/architecture/hybrid-semantic-search.md):
+  keyword/vector/search-context contracts and hosted index options.
+- [Hosted wrapper responsibilities](docs/architecture/hosted-wrapper-responsibilities.md):
+  what a future SaaS layer owns outside the OSS package.
+
 ## Commands
 
 ### add

package/bin/open-knowledge-mcp.js

@@ -13660,7 +13660,7 @@ import { existsSync as existsSync8, readFileSync as readFileSync8, writeFileSync
 // package.json
 var package_default = {
   name: "@hasna/knowledge",
-  version: "0.2.24",
+  version: "0.2.26",
   description: "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   type: "module",
   bin: {

package/bin/open-knowledge.js

@@ -622,7 +622,7 @@ Pages should be concise, cited, and organized for both humans and agents.
          content_hash = excluded.content_hash,
          status = excluded.status,
          metadata_json = excluded.metadata_json,
-         updated_at = excluded.updated_at`,[u,"wiki/README.md","Wiki",s.uri,s.hash??null,"active",JSON.stringify({artifact_key:s.key,provenance:Et(s)}),r,r]),lo(e,u,"Wiki",s,Jn(),r)}}function _o(e){if(!e)return;let t=e.trim().toLowerCase();if(t==="local"||t==="offline")return"local";if(t==="hosted"||t==="remote"||t==="knowledge.hasna.xyz")return"hosted";throw Error("Invalid setup mode. Use hosted or local.")}class Yn{options;ensuredWorkspace;cachedConfig;constructor(e={}){this.options=e}get scope(){return this.options.scope??"global"}get workspace(){return this.ensuredWorkspace??wt(this.options.scope,this.options.cwd)}ensureWorkspace(){if(!this.ensuredWorkspace)this.ensuredWorkspace=bt(this.workspace.home);return this.ensuredWorkspace}jsonStorePath(){return this.ensureWorkspace().jsonStorePath}config(){if(!this.cachedConfig){let e=this.ensureWorkspace();this.cachedConfig=vt(e.configPath)}return this.cachedConfig}safetyPolicy(){return pn(this.config(),this.ensureWorkspace())}artifactStore(){return Lt(this.config(),this.ensureWorkspace())}storageContract(){return Kn(this.config(),this.ensureWorkspace(),this.scope)}validateStorage(){return gt(this.config(),this.ensureWorkspace())}setup(e={}){let t=this.ensureWorkspace(),n=this.config(),r=_o(e.mode)??n.mode,i=e.apiUrl?$(e.apiUrl):n.hosted?.api_url?$(n.hosted.api_url):null,s={...n,mode:r,hosted:{...n.hosted??{},...i?{api_url:i}:{}}};return St(t.configPath,s),this.cachedConfig=s,{ok:!0,mode:r,api_url:s.hosted?.api_url??null,config_path:t.configPath,next:r==="hosted"?["open-knowledge auth login --api-key <key>","open-knowledge remote contracts --json"]:["open-knowledge search <query>","knowledge <prompt>"],message:`Set knowledge mode to ${r}`}}authStatus(e=process.env){return Kt(this.config(),e)}saveAuth(e,t=process.env){let n=e.apiUrl??this.config().hosted?.api_url;return Dt({api_key:e.apiKey,email:e.email,org_id:e.orgId,org_slug:e.orgSlug,user_id:e.userId,api_url:n},t)}clearAuth(e=process.env){return Ut(e)}remoteContract(){let e=this.storageContract();return An({mode:this.config().mode,sourceSchemes:this.config().sources.allowed_schemes,storageType:e.artifact_store.type,artifactUriPrefix:e.artifact_store.uri_prefix})}remoteClient(e=process.env){return We.fromConfig(this.config(),e)}paths(){let e=this.ensureWorkspace();return{ok:!0,scope:this.scope,home:e.home,config_path:e.configPath,json_store_path:e.jsonStorePath,knowledge_db_path:e.knowledgeDbPath,artifacts_dir:e.artifactsDir,indexes_dir:e.indexesDir,logs_dir:e.logsDir,runs_dir:e.runsDir,schemas_dir:e.schemasDir,wiki_dir:e.wikiDir,config:this.config(),message:e.home}}initDb(){return x(this.ensureWorkspace().knowledgeDbPath)}dbStats(){let e=this.ensureWorkspace();return x(e.knowledgeDbPath),Ot(e.knowledgeDbPath)}async initWiki(){let e=this.ensureWorkspace();x(e.knowledgeDbPath);let t=await zn(this.artifactStore()),n=b(e.knowledgeDbPath);try{ge(n,t.artifacts),Gn(n,t.artifacts)}finally{n.close()}return t}async compileWiki(e={}){let t=this.ensureWorkspace();return qn({...e,dbPath:t.knowledgeDbPath,store:this.artifactStore()})}async fileAnswer(e){let t=this.ensureWorkspace(),n=await this.retrieveContext({query:e.prompt,limit:e.limit,semantic:e.semantic,modelRef:e.modelRef,dimensions:e.dimensions,fake:e.fake});return Hn({dbPath:t.knowledgeDbPath,store:this.artifactStore(),prompt:e.prompt,answer:e.answer,context:n,approveWrite:e.approveWrite})}lintWiki(){let e=this.ensureWorkspace();return Bn({dbPath:e.knowledgeDbPath})}async ingestManifest(e){let t=this.ensureWorkspace();return yn({dbPath:t.knowledgeDbPath,input:e,config:this.config(),safetyPolicy:this.safetyPolicy()})}async ingestSource(e,t){let n=this.ensureWorkspace();return vn({dbPath:n.knowledgeDbPath,sourceRef:e,purpose:t,config:this.config(),safetyPolicy:this.safetyPolicy()})}async resolveSource(e,t={}){let n=this.ensureWorkspace();return Ke({dbPath:n.knowledgeDbPath,sourceRef:e,purpose:t.purpose,limit:t.limit,safetyPolicy:this.safetyPolicy()})}async consumeOutbox(e){let t=this.ensureWorkspace();return kn({dbPath:t.knowledgeDbPath,input:e,config:this.config(),safetyPolicy:this.safetyPolicy()})}reindexHealth(e={}){let t=this.ensureWorkspace();return Rn({...e,dbPath:t.knowledgeDbPath,config:this.config()})}enqueueReindex(e={}){let t=this.ensureWorkspace();return ft({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async refreshEmbeddings(e={}){let t=this.ensureWorkspace();return xn({...e,dbPath:t.knowledgeDbPath,config:this.config()})}providerStatus(e=process.env){return $t(this.config(),e)}modelRegistry(){return rt(this.config())}embeddingStatus(){let e=this.ensureWorkspace();return Yt(e.knowledgeDbPath)}async indexEmbeddings(e={}){let t=this.ensureWorkspace();return Te({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async semanticSearch(e){let t=this.ensureWorkspace();return Re({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async search(e){let t=this.ensureWorkspace();return Ae({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async retrieveContext(e){let t=this.ensureWorkspace();return Le({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async runPrompt(e){let t=this.ensureWorkspace();return un({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async webSearch(e){let t=this.ensureWorkspace();return Pn({...e,dbPath:t.knowledgeDbPath,config:this.config(),safetyPolicy:this.safetyPolicy()})}}function Vn(e={}){return new Yn(e)}import{basename as go}from"path";var pe={name:"@hasna/knowledge",version:"0.2.24",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"},files:["bin","src","docs","LICENSE","README.md"],scripts:{test:"bun test","test:cli":"bun test tests/cli.test.ts",build:"bun build --target=bun --outfile=bin/open-knowledge.js --minify --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/cli.ts && bun build --target=bun --outfile=bin/open-knowledge-mcp.js --external @modelcontextprotocol/sdk --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/mcp.js",prepublishOnly:"bun run build",postinstall:"bun run build"},keywords:["knowledge","cli","agents","json","notes","local","store"],license:"Apache-2.0",publishConfig:{registry:"https://registry.npmjs.org",access:"public"},repository:{type:"git",url:"git+https://github.com/hasna/knowledge.git"},bugs:{url:"https://github.com/hasna/knowledge/issues"},author:"Hasna Inc. <hasna@example.com>",engines:{bun:">=1.0",node:">=18"},dependencies:{"@aws-sdk/client-s3":"^3.1063.0","@aws-sdk/credential-providers":"^3.1063.0","@ai-sdk/anthropic":"^3.0.81","@ai-sdk/deepseek":"^2.0.35","@ai-sdk/openai":"^3.0.68","@modelcontextprotocol/sdk":"^1.29.0",ai:"^6.0.197",zod:"^4.3.6"},devDependencies:{"@types/bun":"^1.3.14"}};var Qn={debug:0,info:1,warn:2,error:3},po=()=>{if(process.env.DEBUG)return"debug";if(process.env.LOG_LEVEL==="debug")return"debug";if(process.env.LOG_LEVEL==="warn")return"warn";if(process.env.LOG_LEVEL==="error")return"error";return"info"};function ee(e,t,n){if(Qn[e]<Qn[po()])return;let r={debug:"[DEBUG]",info:"[INFO]",warn:"[WARN]",error:"[ERROR]"}[e],i=n?`${r} ${t} ${JSON.stringify(n)}`:`${r} ${t}`;if(e==="error")console.error(i);else console.error(i)}var Zn=["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"],er={ls:"list",rm:"delete",edit:"update",unarchive:"restore",knowledge:"ask"};function mo(e){let t=[],n={};for(let r=0;r<e.length;r+=1){let i=e[r];if(!i.startsWith("-")){t.push(i);continue}switch(i){case"--json":n.json=!0;break;case"--yes":case"-y":n.yes=!0;break;case"--help":case"-h":n.help=!0;break;case"--version":case"-v":n.version=!0;break;case"--desc":n.desc=!0;break;case"--page":case"-p":n.page=Number(e[r+1]),r+=1;break;case"--limit":case"-l":n.limit=Number(e[r+1]),r+=1;break;case"--search":case"-s":n.search=e[r+1],r+=1;break;case"--sort":n.sort=e[r+1],r+=1;break;case"--id":n.id=e[r+1],r+=1;break;case"--store":n.store=e[r+1],r+=1;break;case"--title":n.title=e[r+1],r+=1;break;case"--content":n.content=e[r+1],r+=1;break;case"--url":n.url=e[r+1],r+=1;break;case"--tag":case"-t":n.tag=e[r+1],r+=1;break;case"--format":n.format=e[r+1],r+=1;break;case"--completions":n.completions=e[r+1],r+=1;break;case"--purpose":n.purpose=e[r+1],r+=1;break;case"--model":n.model=e[r+1],r+=1;break;case"--dimensions":n.dimensions=Number(e[r+1]),r+=1;break;case"--semantic":n.semantic=!0;break;case"--context":n.context=!0;break;case"--generate":n.generate=!0;break;case"--approve-write":n.approveWrite=!0;break;case"--provider":n.provider=e[r+1],r+=1;break;case"--mode":n.mode=e[r+1],r+=1;break;case"--api-url":n.apiUrl=e[r+1],r+=1;break;case"--api-key":n.apiKey=e[r+1],r+=1;break;case"--email":n.email=e[r+1],r+=1;break;case"--org":n.org=e[r+1],r+=1;break;case"--org-id":n.orgId=e[r+1],r+=1;break;case"--user-id":n.userId=e[r+1],r+=1;break;case"--domain":n.domain=[...n.domain??[],e[r+1]],r+=1;break;case"--file-results":n.fileResults=!0;break;case"--full":n.full=!0;break;case"--fake":n.fake=!0;break;case"--no-color":n.noColor=!0;break;case"--scope":n.scope=e[r+1],r+=1;break;case"--older-than":n.olderThan=Number(e[r+1]),r+=1;break;case"--empty":n.empty=!0;break;case"--archived":n.archived=!0;break;case"--include-archived":n.includeArchived=!0;break;default:throw Error(`Unknown flag: ${i}. Run 'open-knowledge --help' for valid options.`)}}return{positional:t,flags:n}}function ho(e){if(!e)return"";return er[e]??e}function Eo(e,t){let n=Array.from({length:e.length+1},()=>Array(t.length+1).fill(0));for(let r=0;r<=e.length;r+=1)n[r][0]=r;for(let r=0;r<=t.length;r+=1)n[0][r]=r;for(let r=1;r<=e.length;r+=1)for(let i=1;i<=t.length;i+=1){let s=e[r-1]===t[i-1]?0:1;n[r][i]=Math.min(n[r-1][i]+1,n[r][i-1]+1,n[r-1][i-1]+s)}return n[e.length][t.length]}function ko(e){if(!e)return"";let t=[...Zn,...Object.keys(er)],n="",r=Number.POSITIVE_INFINITY;for(let i of t){let s=Eo(e,i);if(s<r)r=s,n=i}return r<=3?n:""}function yo(){return go(process.argv[1]??"")==="knowledge"}function bo(){console.log(`open-knowledge - local agent knowledge store
+         updated_at = excluded.updated_at`,[u,"wiki/README.md","Wiki",s.uri,s.hash??null,"active",JSON.stringify({artifact_key:s.key,provenance:Et(s)}),r,r]),lo(e,u,"Wiki",s,Jn(),r)}}function _o(e){if(!e)return;let t=e.trim().toLowerCase();if(t==="local"||t==="offline")return"local";if(t==="hosted"||t==="remote"||t==="knowledge.hasna.xyz")return"hosted";throw Error("Invalid setup mode. Use hosted or local.")}class Yn{options;ensuredWorkspace;cachedConfig;constructor(e={}){this.options=e}get scope(){return this.options.scope??"global"}get workspace(){return this.ensuredWorkspace??wt(this.options.scope,this.options.cwd)}ensureWorkspace(){if(!this.ensuredWorkspace)this.ensuredWorkspace=bt(this.workspace.home);return this.ensuredWorkspace}jsonStorePath(){return this.ensureWorkspace().jsonStorePath}config(){if(!this.cachedConfig){let e=this.ensureWorkspace();this.cachedConfig=vt(e.configPath)}return this.cachedConfig}safetyPolicy(){return pn(this.config(),this.ensureWorkspace())}artifactStore(){return Lt(this.config(),this.ensureWorkspace())}storageContract(){return Kn(this.config(),this.ensureWorkspace(),this.scope)}validateStorage(){return gt(this.config(),this.ensureWorkspace())}setup(e={}){let t=this.ensureWorkspace(),n=this.config(),r=_o(e.mode)??n.mode,i=e.apiUrl?$(e.apiUrl):n.hosted?.api_url?$(n.hosted.api_url):null,s={...n,mode:r,hosted:{...n.hosted??{},...i?{api_url:i}:{}}};return St(t.configPath,s),this.cachedConfig=s,{ok:!0,mode:r,api_url:s.hosted?.api_url??null,config_path:t.configPath,next:r==="hosted"?["open-knowledge auth login --api-key <key>","open-knowledge remote contracts --json"]:["open-knowledge search <query>","knowledge <prompt>"],message:`Set knowledge mode to ${r}`}}authStatus(e=process.env){return Kt(this.config(),e)}saveAuth(e,t=process.env){let n=e.apiUrl??this.config().hosted?.api_url;return Dt({api_key:e.apiKey,email:e.email,org_id:e.orgId,org_slug:e.orgSlug,user_id:e.userId,api_url:n},t)}clearAuth(e=process.env){return Ut(e)}remoteContract(){let e=this.storageContract();return An({mode:this.config().mode,sourceSchemes:this.config().sources.allowed_schemes,storageType:e.artifact_store.type,artifactUriPrefix:e.artifact_store.uri_prefix})}remoteClient(e=process.env){return We.fromConfig(this.config(),e)}paths(){let e=this.ensureWorkspace();return{ok:!0,scope:this.scope,home:e.home,config_path:e.configPath,json_store_path:e.jsonStorePath,knowledge_db_path:e.knowledgeDbPath,artifacts_dir:e.artifactsDir,indexes_dir:e.indexesDir,logs_dir:e.logsDir,runs_dir:e.runsDir,schemas_dir:e.schemasDir,wiki_dir:e.wikiDir,config:this.config(),message:e.home}}initDb(){return x(this.ensureWorkspace().knowledgeDbPath)}dbStats(){let e=this.ensureWorkspace();return x(e.knowledgeDbPath),Ot(e.knowledgeDbPath)}async initWiki(){let e=this.ensureWorkspace();x(e.knowledgeDbPath);let t=await zn(this.artifactStore()),n=b(e.knowledgeDbPath);try{ge(n,t.artifacts),Gn(n,t.artifacts)}finally{n.close()}return t}async compileWiki(e={}){let t=this.ensureWorkspace();return qn({...e,dbPath:t.knowledgeDbPath,store:this.artifactStore()})}async fileAnswer(e){let t=this.ensureWorkspace(),n=await this.retrieveContext({query:e.prompt,limit:e.limit,semantic:e.semantic,modelRef:e.modelRef,dimensions:e.dimensions,fake:e.fake});return Hn({dbPath:t.knowledgeDbPath,store:this.artifactStore(),prompt:e.prompt,answer:e.answer,context:n,approveWrite:e.approveWrite})}lintWiki(){let e=this.ensureWorkspace();return Bn({dbPath:e.knowledgeDbPath})}async ingestManifest(e){let t=this.ensureWorkspace();return yn({dbPath:t.knowledgeDbPath,input:e,config:this.config(),safetyPolicy:this.safetyPolicy()})}async ingestSource(e,t){let n=this.ensureWorkspace();return vn({dbPath:n.knowledgeDbPath,sourceRef:e,purpose:t,config:this.config(),safetyPolicy:this.safetyPolicy()})}async resolveSource(e,t={}){let n=this.ensureWorkspace();return Ke({dbPath:n.knowledgeDbPath,sourceRef:e,purpose:t.purpose,limit:t.limit,safetyPolicy:this.safetyPolicy()})}async consumeOutbox(e){let t=this.ensureWorkspace();return kn({dbPath:t.knowledgeDbPath,input:e,config:this.config(),safetyPolicy:this.safetyPolicy()})}reindexHealth(e={}){let t=this.ensureWorkspace();return Rn({...e,dbPath:t.knowledgeDbPath,config:this.config()})}enqueueReindex(e={}){let t=this.ensureWorkspace();return ft({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async refreshEmbeddings(e={}){let t=this.ensureWorkspace();return xn({...e,dbPath:t.knowledgeDbPath,config:this.config()})}providerStatus(e=process.env){return $t(this.config(),e)}modelRegistry(){return rt(this.config())}embeddingStatus(){let e=this.ensureWorkspace();return Yt(e.knowledgeDbPath)}async indexEmbeddings(e={}){let t=this.ensureWorkspace();return Te({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async semanticSearch(e){let t=this.ensureWorkspace();return Re({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async search(e){let t=this.ensureWorkspace();return Ae({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async retrieveContext(e){let t=this.ensureWorkspace();return Le({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async runPrompt(e){let t=this.ensureWorkspace();return un({...e,dbPath:t.knowledgeDbPath,config:this.config()})}async webSearch(e){let t=this.ensureWorkspace();return Pn({...e,dbPath:t.knowledgeDbPath,config:this.config(),safetyPolicy:this.safetyPolicy()})}}function Vn(e={}){return new Yn(e)}import{basename as go}from"path";var pe={name:"@hasna/knowledge",version:"0.2.26",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"},files:["bin","src","docs","LICENSE","README.md"],scripts:{test:"bun test","test:cli":"bun test tests/cli.test.ts",build:"bun build --target=bun --outfile=bin/open-knowledge.js --minify --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/cli.ts && bun build --target=bun --outfile=bin/open-knowledge-mcp.js --external @modelcontextprotocol/sdk --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/mcp.js",prepublishOnly:"bun run build",postinstall:"bun run build"},keywords:["knowledge","cli","agents","json","notes","local","store"],license:"Apache-2.0",publishConfig:{registry:"https://registry.npmjs.org",access:"public"},repository:{type:"git",url:"git+https://github.com/hasna/knowledge.git"},bugs:{url:"https://github.com/hasna/knowledge/issues"},author:"Hasna Inc. <hasna@example.com>",engines:{bun:">=1.0",node:">=18"},dependencies:{"@aws-sdk/client-s3":"^3.1063.0","@aws-sdk/credential-providers":"^3.1063.0","@ai-sdk/anthropic":"^3.0.81","@ai-sdk/deepseek":"^2.0.35","@ai-sdk/openai":"^3.0.68","@modelcontextprotocol/sdk":"^1.29.0",ai:"^6.0.197",zod:"^4.3.6"},devDependencies:{"@types/bun":"^1.3.14"}};var Qn={debug:0,info:1,warn:2,error:3},po=()=>{if(process.env.DEBUG)return"debug";if(process.env.LOG_LEVEL==="debug")return"debug";if(process.env.LOG_LEVEL==="warn")return"warn";if(process.env.LOG_LEVEL==="error")return"error";return"info"};function ee(e,t,n){if(Qn[e]<Qn[po()])return;let r={debug:"[DEBUG]",info:"[INFO]",warn:"[WARN]",error:"[ERROR]"}[e],i=n?`${r} ${t} ${JSON.stringify(n)}`:`${r} ${t}`;if(e==="error")console.error(i);else console.error(i)}var Zn=["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"],er={ls:"list",rm:"delete",edit:"update",unarchive:"restore",knowledge:"ask"};function mo(e){let t=[],n={};for(let r=0;r<e.length;r+=1){let i=e[r];if(!i.startsWith("-")){t.push(i);continue}switch(i){case"--json":n.json=!0;break;case"--yes":case"-y":n.yes=!0;break;case"--help":case"-h":n.help=!0;break;case"--version":case"-v":n.version=!0;break;case"--desc":n.desc=!0;break;case"--page":case"-p":n.page=Number(e[r+1]),r+=1;break;case"--limit":case"-l":n.limit=Number(e[r+1]),r+=1;break;case"--search":case"-s":n.search=e[r+1],r+=1;break;case"--sort":n.sort=e[r+1],r+=1;break;case"--id":n.id=e[r+1],r+=1;break;case"--store":n.store=e[r+1],r+=1;break;case"--title":n.title=e[r+1],r+=1;break;case"--content":n.content=e[r+1],r+=1;break;case"--url":n.url=e[r+1],r+=1;break;case"--tag":case"-t":n.tag=e[r+1],r+=1;break;case"--format":n.format=e[r+1],r+=1;break;case"--completions":n.completions=e[r+1],r+=1;break;case"--purpose":n.purpose=e[r+1],r+=1;break;case"--model":n.model=e[r+1],r+=1;break;case"--dimensions":n.dimensions=Number(e[r+1]),r+=1;break;case"--semantic":n.semantic=!0;break;case"--context":n.context=!0;break;case"--generate":n.generate=!0;break;case"--approve-write":n.approveWrite=!0;break;case"--provider":n.provider=e[r+1],r+=1;break;case"--mode":n.mode=e[r+1],r+=1;break;case"--api-url":n.apiUrl=e[r+1],r+=1;break;case"--api-key":n.apiKey=e[r+1],r+=1;break;case"--email":n.email=e[r+1],r+=1;break;case"--org":n.org=e[r+1],r+=1;break;case"--org-id":n.orgId=e[r+1],r+=1;break;case"--user-id":n.userId=e[r+1],r+=1;break;case"--domain":n.domain=[...n.domain??[],e[r+1]],r+=1;break;case"--file-results":n.fileResults=!0;break;case"--full":n.full=!0;break;case"--fake":n.fake=!0;break;case"--no-color":n.noColor=!0;break;case"--scope":n.scope=e[r+1],r+=1;break;case"--older-than":n.olderThan=Number(e[r+1]),r+=1;break;case"--empty":n.empty=!0;break;case"--archived":n.archived=!0;break;case"--include-archived":n.includeArchived=!0;break;default:throw Error(`Unknown flag: ${i}. Run 'open-knowledge --help' for valid options.`)}}return{positional:t,flags:n}}function ho(e){if(!e)return"";return er[e]??e}function Eo(e,t){let n=Array.from({length:e.length+1},()=>Array(t.length+1).fill(0));for(let r=0;r<=e.length;r+=1)n[r][0]=r;for(let r=0;r<=t.length;r+=1)n[0][r]=r;for(let r=1;r<=e.length;r+=1)for(let i=1;i<=t.length;i+=1){let s=e[r-1]===t[i-1]?0:1;n[r][i]=Math.min(n[r-1][i]+1,n[r][i-1]+1,n[r-1][i-1]+s)}return n[e.length][t.length]}function ko(e){if(!e)return"";let t=[...Zn,...Object.keys(er)],n="",r=Number.POSITIVE_INFINITY;for(let i of t){let s=Eo(e,i);if(s<r)r=s,n=i}return r<=3?n:""}function yo(){return go(process.argv[1]??"")==="knowledge"}function bo(){console.log(`open-knowledge - local agent knowledge store
 
 Usage:
   open-knowledge <command> [options]

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

@@ -43,6 +43,13 @@ 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 detailed hosted boundary is specified in
+[`hosted-wrapper-responsibilities.md`](./hosted-wrapper-responsibilities.md).
+That document is the source of truth for responsibilities that must stay out of
+the OSS package, including tenants, ACL enforcement, connector credentials,
+bucket provisioning, secrets, queues, billing, admin controls, observability, and
+the hosted web UI.
+
 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

package/docs/architecture/hosted-wrapper-responsibilities.md

@@ -0,0 +1,177 @@
+# Hosted Wrapper Responsibilities
+
+`open-knowledge` stays local-first and open source. A future hosted/SaaS wrapper
+can implement remote APIs around the same contracts, but tenant state,
+infrastructure ownership, and commercial controls must live outside this
+package.
+
+## Boundary
+
+The OSS package owns:
+
+- Local CLI and MCP behavior.
+- `.hasna/apps/knowledge` workspaces.
+- Local SQLite schema, local artifact catalog, generated wiki artifacts, local
+  vector rows, run ledgers, and BYOK provider calls.
+- Source refs, derived chunks, citations, provenance, and read-only resolver
+  contracts.
+- Remote client shapes for `registry`, `search`, `ask`, `build`, `sync`,
+  `run_status`, `run_logs`, and `run_artifacts`.
+
+The hosted wrapper owns:
+
+- Tenants, users, orgs, projects, memberships, roles, invitations, sessions, API
+  keys, and service accounts.
+- Per-tenant permission checks before retrieval, generation, web search,
+  artifact reads, artifact writes, and source sync.
+- Hosted databases, object storage, queue infrastructure, workers, secret
+  storage, web UI, billing, rate limits, moderation, observability, and admin
+  operations.
+
+Local mode must not require hosted identity, billing, queue workers, or hosted
+object storage. Hosted mode is an explicit remote boundary selected through
+`open-knowledge setup --mode hosted` plus `KNOWLEDGE_API_URL` and
+`KNOWLEDGE_API_KEY`.
+
+## Identity And Access
+
+The hosted wrapper should model:
+
+- `users`: human accounts, verified emails, auth identities, MFA state, disabled
+  state, and profile metadata.
+- `orgs`: billing/legal tenants, org slugs, data residency settings, default
+  retention policies, and owner/admin contacts.
+- `projects`: knowledge workspaces under an org, project slugs, connected
+  source scopes, default model/search settings, and artifact storage policy.
+- `memberships`: user to org/project role assignments.
+- `api_keys`: scoped keys for CLI, MCP, CI, workers, and web UI sessions.
+- `service_accounts`: non-human actors for ingestion, sync, indexing, and
+  scheduled maintenance.
+
+Permission checks must happen before context assembly. The wrapper should never
+retrieve broad context and filter after generation. The retrieval API should
+accept caller identity, project id, requested purpose, source refs, and requested
+operations, then return only authorized source chunks, generated artifacts, and
+citations.
+
+## Open-Files Integration
+
+`open-files` remains the source of truth for raw source bytes. The hosted wrapper
+should own connector orchestration and source sync:
+
+- Google Drive, Slack, GitHub, Notion, S3, local-upload, web crawl, and future
+  connector credentials.
+- Connector OAuth flows, refresh tokens, webhook registrations, cursor state,
+  backoff, retries, and error recovery.
+- Source snapshots, immutable object ids, revisions, hashes, MIME metadata,
+  extracted text refs, ACL metadata, and change outboxes.
+- Read-only resolver APIs that expose derived extracted text or allowed chunks
+  to `open-knowledge` without exposing storage credentials.
+
+`open-knowledge` should continue to consume manifests, source refs, and outbox
+events. It should not own connector credentials or raw source object lifecycle.
+
+## Storage And Secrets
+
+The hosted wrapper should provision and enforce:
+
+- Per-org/project generated-artifact prefixes in S3 or another object store.
+- Bucket policies, KMS keys, retention rules, lifecycle rules, replication, and
+  object lock settings where required.
+- Secrets for provider keys, connector keys, AWS roles, RDS URLs, webhook
+  secrets, and encryption material.
+- Migration aliases from legacy bucket and secret names to canonical names.
+
+The OSS package may know a storage contract, bucket name, prefix, region, and
+profile. It must not contain tenant secret values, connector credentials, RDS
+passwords, hosted KMS key material, or privileged AWS role assumptions.
+
+Generated artifacts are safe to sync remotely only when they remain derived:
+wiki pages, index shards, schema files, logs, exports, run payloads, embeddings,
+and citation metadata. Raw source bytes stay in `open-files`.
+
+## Remote Jobs
+
+The wrapper should implement durable jobs for:
+
+- Manifest import and source sync from `open-files`.
+- Extraction and redaction refresh.
+- Embedding index refresh and stale-revision invalidation.
+- Provider-native web search with audit logs and source capture.
+- Wiki compile, answer filing, lint, and maintenance runs.
+- Artifact sync between local clients and hosted storage.
+- Remote search, ask, and build workflows.
+
+Jobs should expose the same run contract as the local package: status, prompt or
+query, provider/model, usage, citations, artifacts, events, logs, errors,
+timestamps, and cost metadata. Workers should be idempotent and keyed by source
+revision, artifact hash, or run id where possible.
+
+## API Surface
+
+The wrapper should implement the contract printed by:
+
+```bash
+open-knowledge remote contracts --scope project --json
+```
+
+Required endpoint families:
+
+- `registry`: service capabilities, contract version, source contract, artifact
+  contract, and limits.
+- `search`: permission-aware hybrid retrieval.
+- `ask`: retrieval plus answer generation.
+- `build`: retrieval plus generated artifact proposals or approved writes.
+- `sync`: source/artifact synchronization.
+- `runs`: status, logs, events, usage, and artifacts.
+- `artifacts`: generated artifact reads and writes with policy checks.
+
+The web UI should use the same API surface as CLI/MCP clients. It should not
+gain hidden write paths that bypass approval gates, source permission checks, or
+run ledgers.
+
+## Billing, Limits, And Abuse Controls
+
+The hosted wrapper owns:
+
+- Plan limits for seats, projects, sources, storage, embeddings, web search,
+  provider tokens, and scheduled jobs.
+- Per-user, per-org, per-project, and per-key rate limits.
+- Provider cost attribution and billing events.
+- Abuse detection for web search, provider calls, bulk exports, connector syncs,
+  and artifact downloads.
+- Admin controls to pause projects, rotate keys, disable connectors, revoke API
+  keys, and quarantine generated artifacts.
+
+Local OSS mode may report provider usage, but it must not require billing.
+
+## Audit And Observability
+
+The hosted wrapper should record:
+
+- Authentication and API-key events.
+- Source connector reads, source resolver reads, and source permission denials.
+- Search, ask, build, compile, lint, web-search, sync, and export runs.
+- Generated artifact writes, approvals, rejections, and rollbacks.
+- Admin and moderation actions.
+- Worker retries, dead-letter events, queue latency, token usage, cost, and
+  storage growth.
+
+Local run ledgers and audit events remain useful for offline workflows. Hosted
+audit logs should add tenant identity, actor identity, IP/user-agent metadata,
+request ids, and retention controls.
+
+## Non-Goals For OSS
+
+The OSS package should not implement:
+
+- Hosted user/org/project management.
+- Billing, plans, commercial rate limits, or invoices.
+- Hosted connector OAuth flows or connector credential storage.
+- Shared multi-tenant ACL enforcement.
+- Hosted queue workers, RDS provisioning, bucket provisioning, KMS management,
+  or admin/moderation workflows.
+- A privileged web UI write path.
+
+The OSS package can expose the contracts and local behavior needed to make those
+systems straightforward to build on top.

package/docs/examples/company-wiki-workflow.md

@@ -0,0 +1,176 @@
+# Company Wiki Workflow
+
+This workflow shows how to use `open-knowledge` as an AI-native company wiki
+layer over source files owned by `open-files`.
+
+## 1. Initialize The Project Workspace
+
+```bash
+open-knowledge paths --scope project --json
+open-knowledge db init --scope project --json
+open-knowledge wiki init --scope project --json
+```
+
+Project state is created under:
+
+```text
+.hasna/apps/knowledge/
+  config.json
+  knowledge.db
+  artifacts/
+  indexes/
+  logs/
+  runs/
+  schemas/
+  wiki/
+```
+
+## 2. Import Source Metadata From Open-Files
+
+Use an `open-files` manifest with source refs, revisions, permissions, hashes,
+and extracted text:
+
+```json
+{
+  "source_ref": "open-files://file/file_handbook/revision/rev_20260608",
+  "file_id": "file_handbook",
+  "path": "Handbook/Policy.md",
+  "name": "Policy.md",
+  "mime": "text/markdown",
+  "hash": "sha256:...",
+  "status": "active",
+  "permissions": {
+    "mode": "read_only",
+    "allowed_purposes": ["knowledge_answer", "knowledge_index"]
+  },
+  "extracted_text": "Policy text..."
+}
+```
+
+Then ingest it:
+
+```bash
+open-knowledge ingest manifest ./open-files-manifest.jsonl --scope project --json
+```
+
+The knowledge app stores source refs, revisions, redacted chunks, offsets, and
+citations. It does not store raw source bytes or connector credentials.
+
+## 3. Search And Build Context
+
+Run local keyword/catalog search first:
+
+```bash
+open-knowledge search "expense policy" --scope project --json
+```
+
+Add deterministic local semantic indexing for a smoke test:
+
+```bash
+open-knowledge embeddings index --scope project --fake --dimensions 8 --json
+open-knowledge search "expense policy" --scope project --semantic --fake --dimensions 8 --json
+```
+
+Ask for an agent-ready context pack:
+
+```bash
+open-knowledge search "expense policy" --scope project --context --json
+```
+
+## 4. Answer With Citations
+
+Create a local citation draft:
+
+```bash
+knowledge "How do we approve expenses?" --scope project --json
+```
+
+Use provider generation explicitly:
+
+```bash
+OPENAI_API_KEY=... \
+knowledge "How do we approve expenses?" \
+  --scope project \
+  --generate \
+  --model openai:gpt-5-mini \
+  --json
+```
+
+Every prompt run records `runs`, `run_events`, provider/model metadata, usage,
+citations, and proposed wiki updates.
+
+## 5. Compile Durable Wiki Pages
+
+Compile a cited page from indexed chunks:
+
+```bash
+open-knowledge wiki compile "expense policy" \
+  --title "Expense Policy" \
+  --scope project \
+  --json
+```
+
+File an approved answer note:
+
+```bash
+open-knowledge wiki file-answer "How do we approve expenses?" \
+  --content "Use manager approval and cite the policy source." \
+  --approve-write \
+  --scope project \
+  --json
+```
+
+Lint the generated wiki:
+
+```bash
+open-knowledge wiki lint --scope project --json
+```
+
+Generated pages are written through the artifact store and cataloged in
+`knowledge.db`; index rows and logs are sharded rather than stored in one large
+Markdown file.
+
+## 6. Keep Sources Fresh
+
+Consume open-files outbox events after source changes:
+
+```bash
+open-knowledge reindex outbox ./open-files-outbox.jsonl --scope project --json
+open-knowledge reindex enqueue --scope project --json
+open-knowledge reindex embeddings --scope project --fake --dimensions 8 --json
+```
+
+This invalidates stale source chunks and refreshes embeddings without losing the
+source refs and citation provenance.
+
+## 7. Expose The Wiki To Agents Through MCP
+
+Run MCP over stdio:
+
+```bash
+open-knowledge-mcp
+```
+
+Or run local Streamable HTTP:
+
+```bash
+open-knowledge-mcp --http --port 8819
+```
+
+Agents should prefer stable tools such as `knowledge_search`, `knowledge_ask`,
+`knowledge_build`, `knowledge_get`, `knowledge_lint`, and
+`knowledge_run_status`. They can inspect project resources such as
+`knowledge://project/wiki/pages`, `knowledge://project/runs`, and
+`knowledge://project/open-files`.
+
+## 8. Optional Hosted And S3 Mode
+
+Hosted mode is only a remote client boundary:
+
+```bash
+open-knowledge setup --mode hosted --api-url https://knowledge.hasna.xyz --scope project --json
+open-knowledge remote contracts --scope project --json
+```
+
+Generated artifacts may use S3 when configured, but raw source files still stay
+in `open-files`.

package/docs/migration/json-to-sqlite.md

@@ -0,0 +1,151 @@
+# JSON To SQLite Migration
+
+`open-knowledge` began as a simple JSON note store. Current project mode uses a
+Hasna app workspace and a versioned SQLite catalog:
+
+```text
+.hasna/apps/knowledge/
+  db.json
+  knowledge.db
+  artifacts/
+  indexes/
+  logs/
+  runs/
+  schemas/
+  wiki/
+```
+
+The JSON store remains available for compatibility with note commands such as
+`add`, `list`, `get`, `update`, `delete`, and `export`. The SQLite catalog is
+used for source refs, source revisions, chunks, citations, embeddings, wiki
+pages, generated artifacts, runs, audit events, and reindex jobs.
+
+## What Migrates Automatically
+
+Global legacy notes are migrated on first use:
+
+```text
+~/.open-knowledge/db.json
+```
+
+to:
+
+```text
+~/.hasna/apps/knowledge/db.json
+```
+
+This happens only when the new Hasna JSON store does not already exist. The
+legacy file is not deleted.
+
+Project mode writes directly to:
+
+```text
+<project>/.hasna/apps/knowledge/db.json
+```
+
+when compatibility note commands are used with `--scope project`.
+
+## What Requires Explicit Ingestion
+
+SQLite knowledge records are not inferred from old JSON notes automatically.
+Use explicit commands so provenance, permissions, citations, and redaction are
+recorded correctly.
+
+Initialize the project catalog:
+
+```bash
+open-knowledge db init --scope project --json
+open-knowledge wiki init --scope project --json
+```
+
+Import open-files manifests:
+
+```bash
+open-knowledge ingest manifest ./open-files-manifest.jsonl --scope project --json
+```
+
+Import one allowed source ref:
+
+```bash
+open-knowledge ingest source file:///absolute/path/to/handbook.md \
+  --purpose knowledge_index \
+  --scope project \
+  --json
+```
+
+Resolve indexed source evidence:
+
+```bash
+open-knowledge source resolve open-files://file/file_123/revision/rev_456 \
+  --purpose knowledge_answer \
+  --scope project \
+  --json
+```
+
+## Recommended Migration Path
+
+1. Keep the legacy JSON note store as an exportable compatibility layer.
+2. Run `open-knowledge paths --scope project --json` and confirm the project
+   workspace is `.hasna/apps/knowledge`.
+3. Initialize `knowledge.db` with `open-knowledge db init --scope project`.
+4. Ingest source manifests from `open-files` rather than copying raw files into
+   `open-knowledge`.
+5. Run `open-knowledge search --scope project --json` to verify source chunks.
+6. Run `open-knowledge wiki compile` for durable cited pages.
+7. Run `open-knowledge wiki lint --scope project --json` before treating pages
+   as company knowledge.
+8. Use `open-knowledge export --format jsonl` if legacy notes need to be
+   archived or transformed outside the app.
+
+## JSON Output Contracts
+
+Use `--json` during migration. Commands return stable objects with `ok: true`
+when successful and command-specific fields such as:
+
+- `paths`: workspace paths and config.
+- `db stats`: schema version and table counts.
+- `ingest manifest`: sources, revisions, chunks, redactions, and skipped rows.
+- `source resolve`: read-only source metadata, chunks, citations, and evidence.
+- `search --context`: excerpts, citations, graph evidence, and warnings.
+- `ask|build`: run id, answer, context, citations, proposed wiki updates, write
+  policy, usage, and warnings.
+- `wiki compile`: page id, artifact URI, citations written, index updates, and
+  log shard key.
+
+## Safety Rules During Migration
+
+- Prefer `open-files://` refs for durable company sources.
+- Keep raw source bytes in `open-files`; do not import them as generated wiki
+  artifacts.
+- Enable S3 reads only for allowed buckets:
+
+```bash
+HASNA_KNOWLEDGE_ALLOW_S3_READS=1 \
+HASNA_KNOWLEDGE_ALLOWED_S3_BUCKETS=my-bucket \
+open-knowledge ingest manifest s3://my-bucket/path/manifest.jsonl \
+  --scope project \
+  --json
+```
+
+- Enable web search only when current external context is required:
+
+```bash
+HASNA_KNOWLEDGE_WEB_SEARCH=1 \
+open-knowledge web search "current policy source" --provider openai --json
+```
+
+- Use `--approve-write` only when a generated wiki artifact should be durable.
+
+## Hosted Migration
+
+Hosted mode should not change local migration semantics. It only records a
+remote API boundary:
+
+```bash
+open-knowledge setup --mode hosted --api-url https://knowledge.hasna.xyz --scope project --json
+open-knowledge remote contracts --scope project --json
+```
+
+A SaaS wrapper can later sync generated artifacts, run jobs, enforce tenant ACLs,
+and store artifacts in S3, but the local package remains usable without a hosted
+account.

package/package.json

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