@inkeep/open-knowledge 0.0.0-dev-20260424044137 → 0.0.0-dev-20260424150009

package/dist/src-lFQj9tkB.mjs

@@ -0,0 +1 @@
+import"./src-CB-sXsMW.mjs";import{Bt as e,ct as t,dt as n,ft as r,i,lt as a,n as o,r as s,ut as c}from"./src-DIoA15kL.mjs";import{f as l,r as u}from"./server-lock-4vgF5yho.mjs";export{o as ProjectGitInitError,t as UiLockCollisionError,a as acquireUiLock,i as bootServer,s as ensureProjectGit,e as getLogger,l as isProcessAlive,u as readServerLock,c as readUiLock,n as releaseUiLock,r as updateUiLockPort};

package/dist/start-B9LXLMio.mjs

@@ -0,0 +1 @@
+import{o as e}from"./start-C79L5QTe.mjs";export{e as startCommand};

package/dist/{start-B0vMn8zP.mjs → start-C79L5QTe.mjs}

@@ -1,2 +1,2 @@
-import{a as e}from"./constants-XSxfsuBx.mjs";import{O as t}from"./src-CB-sXsMW.mjs";import{Command as n}from"commander";import{closeSync as r,existsSync as i,mkdirSync as a,openSync as o}from"node:fs";import{join as s}from"node:path";import{spawn as c}from"node:child_process";function l(){let e=process.execPath,t=process.argv[1];return t?{command:e,prefixArgs:[t]}:(console.warn(`[self-spawn] process.argv[1] is empty — falling back to \`npx @inkeep/open-knowledge\`. This re-introduces the version-drift surface that re-exec was fixing. Observed argv: ${JSON.stringify(process.argv)}`),{command:`npx`,prefixArgs:[`@inkeep/open-knowledge`]})}function u(e){return e.uiLock?e.isAlive(e.uiLock.pid)?{action:`skip`,reason:`alive`,pid:e.uiLock.pid,port:e.uiLock.port}:{action:`spawn`,reason:`stale`,stalePid:e.uiLock.pid}:{action:`spawn`,reason:`absent`}}function d(e){i(e.lockDir)||a(e.lockDir,{recursive:!0});let t=o(s(e.lockDir,`last-spawn-error.log`),`w`),n=e.spawn??c,{PORT:u,...d}=process.env,f=l();try{let r=n(f.command,[...f.prefixArgs,...e.args??[`ui`]],{detached:!0,stdio:[`ignore`,`ignore`,t],cwd:e.cwd,env:d});return r.unref(),r}finally{try{r(t)}catch{}}}async function f(e){let t=e.now()+e.timeoutMs;for(;e.now()<t;){let t=e.readUiLock();if(t&&t.port>0)return t.port;await e.sleep(e.pollIntervalMs)}let n=e.readUiLock();return n&&n.port>0?n.port:null}function p(e){let t=e.sigtermGraceMs??1e4,n=e.sigtermPollIntervalMs??200,r=e.sleep??(e=>new Promise(t=>setTimeout(t,e)));return async()=>{try{let i=e.readUiLock();if(i&&e.isAlive(i.pid))try{e.killPid(i.pid,`SIGTERM`),e.log?.info({pid:i.pid,port:i.port},`idle-shutdown: SIGTERM UI sibling`);let a=Date.now()+t;for(;Date.now()<a&&e.isAlive(i.pid);)await r(n);if(e.isAlive(i.pid))try{e.killPid(i.pid,`SIGKILL`),e.log?.warn({pid:i.pid,graceMs:t},`idle-shutdown: SIGTERM grace expired — escalated to SIGKILL`)}catch(t){e.log?.error({pid:i.pid,err:t instanceof Error?t.message:String(t)},`idle-shutdown: SIGKILL failed`)}}catch(t){e.log?.warn({pid:i.pid,err:t instanceof Error?t.message:String(t)},`idle-shutdown: failed to SIGTERM UI sibling`)}}catch(t){e.log?.warn({err:t instanceof Error?t.message:String(t)},`idle-shutdown: UI lookup failed; proceeding with destroy`)}await e.destroy()}}async function m(e){let{config:n,cwd:r}=e,i=e.skipAutoInit??!1,a=e.skipUiAutoSpawn??!1,o=e.idleThresholdMs??18e5,{existsSync:s,mkdirSync:c}=await import(`node:fs`),{resolve:l}=await import(`node:path`),{bootServer:m,ensureProjectGit:h,getLogger:g,isProcessAlive:_,readUiLock:v}=await import(`./src-DuGm387u.mjs`),{resolveContentDir:y}=await import(`./paths-vQp9sH9q.mjs`),b=e.log??g(`start`),x=y(n,r);s(x)||(c(x,{recursive:!0}),b.info({contentDir:x},`Created content directory`));let S=!s(l(r,t)),C=i?void 0:async()=>{try{let{initContent:e}=await import(`./init-CJTyH3QE.mjs`),t=e(r);return S||t.created.length>0}catch(e){return console.warn(`Auto-init failed:`,e instanceof Error?e.message:e),!1}},w=!1,T=l(x,t),E=n.server.openOnAgentEdit?()=>{if(w)return;let e=v(T);if(!e||e.port<=0||!_(e.pid))return;w=!0;let t=`http://localhost:${e.port}`;import(`./open-browser-T-bOz6ZQ.mjs`).then(({openBrowser:e})=>e(t)).catch(()=>{})}:void 0,D=null,O=await m({contentDir:x,projectDir:r,contentRoot:n.content.dir,port:n.server.port,host:n.server.host,quiet:!1,debounce:n.persistence.debounceMs,maxDebounce:n.persistence.maxDebounceMs,includePatterns:n.content.include,excludePatterns:n.content.exclude,onAgentWrite:E,localOpCliArgs:[process.execPath,process.argv[1]],attachUiSibling:!0,idleShutdownMs:o,skipAutoInit:i,autoInitFn:C,ensureProjectGitFn:i?void 0:()=>h(r),spawnUiSiblingFn:async({lockDir:t})=>{if(D=u({uiLock:v(t),isAlive:_}),D.action===`spawn`&&!a)try{d({lockDir:t,cwd:r,spawn:e.spawn}),b.info({reason:D.reason},`[start] auto-spawned ok ui sibling`)}catch(e){console.warn(`[start] failed to auto-spawn ok ui: ${e instanceof Error?e.message:String(e)}`)}else D.action===`skip`&&b.info({port:D.port,pid:D.pid},`UI already running at port ${D.port}`)},idleShutdownHandler:e=>p({readUiLock:()=>v(O.lockDir),isAlive:_,killPid:(e,t)=>{process.kill(e,t)},destroy:e,log:b}),log:b});D||={action:`skip`,reason:`alive`,pid:0,port:0};let k=D,A=null;if(k.action===`skip`)A=k.port>0?k.port:null;else if(!a){let t=e.uiBindTimeoutMs??3e3;A=await f({readUiLock:()=>v(O.lockDir),now:Date.now,sleep:e=>new Promise(t=>setTimeout(t,e)),timeoutMs:t,pollIntervalMs:50}),A===null&&b.warn({timeoutMs:t},`[start] ok ui did not bind within timeout — banner falls back to API URL`)}return{httpServer:O.httpServer,destroy:O.destroy,lockDir:O.lockDir,contentDir:x,port:O.port,ready:O.ready,degraded:O.degraded,uiSpawnDecision:D,resolvedUiPort:A,didAutoInit:O.didAutoInit,didGitInit:O.didGitInit}}function h(r){return new n(`start`).description(`Start the knowledge base collab server`).option(`-p, --port <port>`,`Server port`,void 0).option(`-H, --host <host>`,`Server host`,void 0).option(`--open`,`Open browser after start`).option(`--no-init`,`Skip auto-scaffolding of ${t}/`).action(async n=>{let{renderBanner:i}=await import(`./banner-cxbl_Ely.mjs`),{dim:a,error:o,info:s,warning:c}=await import(`./colors-CDmFQ1jq.mjs`),l=r(),u=process.cwd();n.port!==void 0&&(l.server.port=Number(n.port)),n.host!==void 0&&(l.server.host=n.host);let d;try{d=await m({config:l,cwd:u,skipAutoInit:n.init===!1})}catch(e){let{ProjectGitInitError:t}=await import(`./src-DuGm387u.mjs`);e instanceof t&&(console.error(o(`open-knowledge requires git to initialize a parent repo. Install git or run 'git init' yourself, then re-run.`)),e.stderr&&console.error(a(e.stderr.trim())),process.exit(1)),console.error(`${o(`Failed to start:`)} ${e instanceof Error?e.stack??e.message:String(e)}`),process.exit(1)}let f=!1,p=async e=>{if(!f){f=!0,console.log(a(`\nShutting down (${e})...`));try{await d.destroy()}catch(e){console.error(`${o(`destroy() failed:`)} ${e instanceof Error?e.stack??e.message:String(e)}`),process.exitCode=1}process.exit(process.exitCode??0)}};process.once(`SIGINT`,()=>{p(`SIGINT`)}),process.once(`SIGTERM`,()=>{p(`SIGTERM`)});let h=`http://${l.server.host}:${d.port}`,g=l.server.host===`0.0.0.0`||l.server.host===`::`?`http://0.0.0.0:${d.port}`:void 0,_=d.resolvedUiPort,v=_!==null&&_>0?`http://${l.server.host}:${_}`:h;console.log(i({name:`open-knowledge`,version:e,localUrl:v,apiUrl:v===h?void 0:h,networkUrl:g})),d.didAutoInit&&(console.log(`  ${s(`✓`)} Scaffolded ${t}/ (first run)`),console.log(`  ${a("Tip: Run `open-knowledge init` to register MCP tools for Claude Code")}\n`));let y={"shadow-repo":`Version history and branch-switch safety unavailable`,"file-watcher":`External file changes will not sync to the editor`,"head-watcher":`Git branch switches may cause document inconsistency`};d.ready.then(async()=>{if(d.degraded.length>0){console.log();for(let e of d.degraded){let t=y[e]??`${e} (check server logs for details)`;console.warn(`  ${c(`⚠`)} ${c(e)}: ${a(t)}`)}console.log()}if(d.didAutoInit||d.didGitInit)if(d.didGitInit&&console.log(`\n  ${s(`✓`)} Initialized git repo at ${u}/.git/ (default branch: main)`),d.didAutoInit)try{let{previewContent:e,formatPreviewBlock:t}=await import(`./preview-DllU-SIf.mjs`),n=e({projectDir:u,contentDir:d.contentDir,include:l.content.include,exclude:l.content.exclude});console.log(`\n${t(n,u)}\n`)}catch(e){console.warn(`Content preview unavailable: ${e instanceof Error?e.message:String(e)}`)}else console.log();if(n.open){let{openBrowser:e}=await import(`./open-browser-T-bOz6ZQ.mjs`);e(v)}}).catch(e=>{console.error(`  ${o(`Server initialization failed:`)} ${e instanceof Error?e.message:String(e)}`)})})}export{d as a,u as i,m as n,h as o,p as r,l as s,f as t};
-//# sourceMappingURL=start-B0vMn8zP.mjs.map
+import{i as e}from"./constants-QFqPbiZ7.mjs";import{O as t}from"./src-CB-sXsMW.mjs";import{Command as n}from"commander";import{closeSync as r,existsSync as i,mkdirSync as a,openSync as o}from"node:fs";import{join as s}from"node:path";import{spawn as c}from"node:child_process";function l(){let e=process.execPath,t=process.argv[1];return t?{command:e,prefixArgs:[t]}:(console.warn(`[self-spawn] process.argv[1] is empty — falling back to \`npx @inkeep/open-knowledge\`. This re-introduces the version-drift surface that re-exec was fixing. Observed argv: ${JSON.stringify(process.argv)}`),{command:`npx`,prefixArgs:[`@inkeep/open-knowledge`]})}function u(e){return e.uiLock?e.isAlive(e.uiLock.pid)?{action:`skip`,reason:`alive`,pid:e.uiLock.pid,port:e.uiLock.port}:{action:`spawn`,reason:`stale`,stalePid:e.uiLock.pid}:{action:`spawn`,reason:`absent`}}function d(e){i(e.lockDir)||a(e.lockDir,{recursive:!0});let t=o(s(e.lockDir,`last-spawn-error.log`),`w`),n=e.spawn??c,{PORT:u,...d}=process.env,f=l();try{let r=n(f.command,[...f.prefixArgs,...e.args??[`ui`]],{detached:!0,stdio:[`ignore`,`ignore`,t],cwd:e.cwd,env:d});return r.unref(),r}finally{try{r(t)}catch{}}}async function f(e){let t=e.now()+e.timeoutMs;for(;e.now()<t;){let t=e.readUiLock();if(t&&t.port>0)return t.port;await e.sleep(e.pollIntervalMs)}let n=e.readUiLock();return n&&n.port>0?n.port:null}function p(e){let t=e.sigtermGraceMs??1e4,n=e.sigtermPollIntervalMs??200,r=e.sleep??(e=>new Promise(t=>setTimeout(t,e)));return async()=>{try{let i=e.readUiLock();if(i&&e.isAlive(i.pid))try{e.killPid(i.pid,`SIGTERM`),e.log?.info({pid:i.pid,port:i.port},`idle-shutdown: SIGTERM UI sibling`);let a=Date.now()+t;for(;Date.now()<a&&e.isAlive(i.pid);)await r(n);if(e.isAlive(i.pid))try{e.killPid(i.pid,`SIGKILL`),e.log?.warn({pid:i.pid,graceMs:t},`idle-shutdown: SIGTERM grace expired — escalated to SIGKILL`)}catch(t){e.log?.error({pid:i.pid,err:t instanceof Error?t.message:String(t)},`idle-shutdown: SIGKILL failed`)}}catch(t){e.log?.warn({pid:i.pid,err:t instanceof Error?t.message:String(t)},`idle-shutdown: failed to SIGTERM UI sibling`)}}catch(t){e.log?.warn({err:t instanceof Error?t.message:String(t)},`idle-shutdown: UI lookup failed; proceeding with destroy`)}await e.destroy()}}async function m(e){let{config:n,cwd:r}=e,i=e.skipAutoInit??!1,a=e.skipUiAutoSpawn??!1,o=e.idleThresholdMs??18e5,{existsSync:s,mkdirSync:c}=await import(`node:fs`),{resolve:l}=await import(`node:path`),{bootServer:m,ensureProjectGit:h,getLogger:g,isProcessAlive:_,readUiLock:v}=await import(`./src-lFQj9tkB.mjs`),{resolveContentDir:y}=await import(`./paths-ORyeejxG.mjs`),b=e.log??g(`start`),x=y(n,r);s(x)||(c(x,{recursive:!0}),b.info({contentDir:x},`Created content directory`));let S=!s(l(r,t)),C=i?void 0:async()=>{try{let{initContent:e}=await import(`./init-D0FupYPY.mjs`),t=e(r);return S||t.created.length>0}catch(e){return console.warn(`Auto-init failed:`,e instanceof Error?e.message:e),!1}},w=!1,T=l(x,t),E=n.server.openOnAgentEdit?()=>{if(w)return;let e=v(T);if(!e||e.port<=0||!_(e.pid))return;w=!0;let t=`http://localhost:${e.port}`;import(`./open-browser-T-bOz6ZQ.mjs`).then(({openBrowser:e})=>e(t)).catch(()=>{})}:void 0,D=null,O=await m({contentDir:x,projectDir:r,contentRoot:n.content.dir,port:n.server.port,host:n.server.host,quiet:!1,debounce:n.persistence.debounceMs,maxDebounce:n.persistence.maxDebounceMs,includePatterns:n.content.include,excludePatterns:n.content.exclude,onAgentWrite:E,localOpCliArgs:[process.execPath,process.argv[1]],attachUiSibling:!0,idleShutdownMs:o,skipAutoInit:i,autoInitFn:C,ensureProjectGitFn:i?void 0:()=>h(r),spawnUiSiblingFn:async({lockDir:t})=>{if(D=u({uiLock:v(t),isAlive:_}),D.action===`spawn`&&!a)try{d({lockDir:t,cwd:r,spawn:e.spawn}),b.info({reason:D.reason},`[start] auto-spawned ok ui sibling`)}catch(e){console.warn(`[start] failed to auto-spawn ok ui: ${e instanceof Error?e.message:String(e)}`)}else D.action===`skip`&&b.info({port:D.port,pid:D.pid},`UI already running at port ${D.port}`)},idleShutdownHandler:e=>p({readUiLock:()=>v(O.lockDir),isAlive:_,killPid:(e,t)=>{process.kill(e,t)},destroy:e,log:b}),log:b});D||={action:`skip`,reason:`alive`,pid:0,port:0};let k=D,A=null;if(k.action===`skip`)A=k.port>0?k.port:null;else if(!a){let t=e.uiBindTimeoutMs??3e3;A=await f({readUiLock:()=>v(O.lockDir),now:Date.now,sleep:e=>new Promise(t=>setTimeout(t,e)),timeoutMs:t,pollIntervalMs:50}),A===null&&b.warn({timeoutMs:t},`[start] ok ui did not bind within timeout — banner falls back to API URL`)}return{httpServer:O.httpServer,destroy:O.destroy,lockDir:O.lockDir,contentDir:x,port:O.port,ready:O.ready,degraded:O.degraded,uiSpawnDecision:D,resolvedUiPort:A,didAutoInit:O.didAutoInit,didGitInit:O.didGitInit}}function h(r){return new n(`start`).description(`Start the knowledge base collab server`).option(`-p, --port <port>`,`Server port`,void 0).option(`-H, --host <host>`,`Server host`,void 0).option(`--open`,`Open browser after start`).option(`--no-init`,`Skip auto-scaffolding of ${t}/`).action(async n=>{let{renderBanner:i}=await import(`./banner-CI3--er0.mjs`),{dim:a,error:o,info:s,warning:c}=await import(`./colors-CxLEz90E.mjs`),l=r(),u=process.cwd();n.port!==void 0&&(l.server.port=Number(n.port)),n.host!==void 0&&(l.server.host=n.host);let d;try{d=await m({config:l,cwd:u,skipAutoInit:n.init===!1})}catch(e){let{ProjectGitInitError:t}=await import(`./src-lFQj9tkB.mjs`);e instanceof t&&(console.error(o(`open-knowledge requires git to initialize a parent repo. Install git or run 'git init' yourself, then re-run.`)),e.stderr&&console.error(a(e.stderr.trim())),process.exit(1)),console.error(`${o(`Failed to start:`)} ${e instanceof Error?e.stack??e.message:String(e)}`),process.exit(1)}let f=!1,p=async e=>{if(!f){f=!0,console.log(a(`\nShutting down (${e})...`));try{await d.destroy()}catch(e){console.error(`${o(`destroy() failed:`)} ${e instanceof Error?e.stack??e.message:String(e)}`),process.exitCode=1}process.exit(process.exitCode??0)}};process.once(`SIGINT`,()=>{p(`SIGINT`)}),process.once(`SIGTERM`,()=>{p(`SIGTERM`)});let h=`http://${l.server.host}:${d.port}`,g=l.server.host===`0.0.0.0`||l.server.host===`::`?`http://0.0.0.0:${d.port}`:void 0,_=d.resolvedUiPort,v=_!==null&&_>0?`http://${l.server.host}:${_}`:h;console.log(i({name:`open-knowledge`,version:e,localUrl:v,apiUrl:v===h?void 0:h,networkUrl:g})),d.didAutoInit&&(console.log(`  ${s(`✓`)} Scaffolded ${t}/ (first run)`),console.log(`  ${a("Tip: Run `open-knowledge init` to register MCP tools for Claude Code")}\n`));let y={"shadow-repo":`Version history and branch-switch safety unavailable`,"file-watcher":`External file changes will not sync to the editor`,"head-watcher":`Git branch switches may cause document inconsistency`};d.ready.then(async()=>{if(d.degraded.length>0){console.log();for(let e of d.degraded){let t=y[e]??`${e} (check server logs for details)`;console.warn(`  ${c(`⚠`)} ${c(e)}: ${a(t)}`)}console.log()}if(d.didAutoInit||d.didGitInit)if(d.didGitInit&&console.log(`\n  ${s(`✓`)} Initialized git repo at ${u}/.git/ (default branch: main)`),d.didAutoInit)try{let{previewContent:e,formatPreviewBlock:t}=await import(`./preview-BR34uHnQ.mjs`),n=e({projectDir:u,contentDir:d.contentDir,include:l.content.include,exclude:l.content.exclude});console.log(`\n${t(n,u)}\n`)}catch(e){console.warn(`Content preview unavailable: ${e instanceof Error?e.message:String(e)}`)}else console.log();if(n.open){let{openBrowser:e}=await import(`./open-browser-T-bOz6ZQ.mjs`);e(v)}}).catch(e=>{console.error(`  ${o(`Server initialization failed:`)} ${e instanceof Error?e.message:String(e)}`)})})}export{d as a,u as i,m as n,h as o,p as r,l as s,f as t};
+//# sourceMappingURL=start-C79L5QTe.mjs.map

package/dist/{wrapper-DhAZwCvI.mjs → wrapper-BlhyhsXg.mjs}

@@ -4,4 +4,4 @@ import{i as e,o as t,t as n}from"./chunk-FK9Q3tQk.mjs";var r=n(((e,t)=>{let n=[`
 `)+`\r
 \r
 `+n)}function w(e,t,n,r,i,a){if(e.listenerCount(`wsClientError`)){let r=Error(i);Error.captureStackTrace(r,w),e.emit(`wsClientError`,r,n,t)}else C(n,r,i,a)}}));p(),d(),o(),c(),l(),m(),f();var g=t(h(),1).default;export{g as WebSocketServer};
-//# sourceMappingURL=wrapper-DhAZwCvI.mjs.map
+//# sourceMappingURL=wrapper-BlhyhsXg.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkeep/open-knowledge",
-  "version": "0.0.0-dev-20260424044137",
+  "version": "0.0.0-dev-20260424150009",
   "private": false,
   "type": "module",
   "exports": {
@@ -20,6 +20,7 @@
   },
   "files": [
     "dist",
+    "scripts",
     "!dist/**/*.map"
   ],
   "engines": {
@@ -30,8 +31,11 @@
   },
   "scripts": {
     "build:cli": "tsdown",
-    "build:assets": "cp -r ../app/dist dist/public",
+    "build:app": "cp -r ../app/dist dist/public",
+    "build:skill-asset": "mkdir -p dist/assets/skills/open-knowledge && cp ../server/assets/skills/open-knowledge/SKILL.md dist/assets/skills/open-knowledge/SKILL.md",
+    "build:assets": "bun run build:app && bun run build:skill-asset",
     "build": "bun run build:cli && bun run build:assets",
+    "postinstall": "node scripts/postinstall.mjs",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run build && bun run test"

package/scripts/postinstall.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * `@inkeep/open-knowledge` postinstall hook.
+ *
+ * Fires `installUserSkill()` once per `npm install` / `bun install` / `npx`
+ * cache population. Non-fatal: any failure is swallowed so the host install
+ * never blocks.
+ *
+ * Spec: 2026-04-22-mcp-guidance-no-project-pollution (FR12 / D20).
+ */
+
+async function run() {
+  let installUserSkill;
+  try {
+    // Relative import resolves inside the published npm tarball at
+    // <pkg-root>/dist/index.mjs — the tsdown-bundled entry that re-exports
+    // `installUserSkill` from @inkeep/open-knowledge-server.
+    const mod = await import('../dist/index.mjs');
+    installUserSkill = mod.installUserSkill;
+  } catch {
+    // Dev-install scenarios (e.g. running `npm install` against a tarball
+    // where dist/ is missing, `--ignore-scripts`, or source-only installs)
+    // never block — fall through to exit 0.
+    return;
+  }
+
+  if (typeof installUserSkill !== 'function') return;
+
+  let result;
+  try {
+    result = await installUserSkill();
+  } catch {
+    // installUserSkill is documented as never-throws; this catch is pure
+    // defensive hardening so a broken build never blocks `npm install`.
+    return;
+  }
+
+  if (result === 'installed') {
+    process.stdout.write('[open-knowledge] Agent Skill installed to detected agent hosts.\n');
+  } else if (result === 'failed') {
+    process.stderr.write(
+      '[open-knowledge] Agent Skill auto-install failed; run manually: ' +
+        "npx skills@~1.5.0 add <bundled-path> --agent '*' -g -y --copy\n",
+    );
+  }
+  // result === 'skip-current' → silent.
+}
+
+// Fire-and-forget. Always exit 0 regardless of outcome per SPEC D20 —
+// `npm install` must never fail because skill-install hit an edge case.
+run().finally(() => {
+  process.exit(0);
+});

package/scripts/probe-exec.ts

@@ -0,0 +1,100 @@
+/**
+ * End-to-end probe: buildExecResult through the full pipeline
+ * (parseCommand → just-bash → extractPaths → enrichPath → dual-channel
+ * response). Hand-runnable — not part of the test suite.
+ *
+ * Run via: `bun run packages/cli/scripts/probe-exec.ts`
+ */
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { commitWip, initShadowRepo, type WriterIdentity } from '@inkeep/open-knowledge-server';
+import simpleGit from 'simple-git';
+import { buildExecResult, type ExecStructuredResult } from '../src/mcp/tools/exec.ts';
+
+const root = resolve(tmpdir(), `ok-exec-probe-${Date.now()}`);
+mkdirSync(root, { recursive: true });
+
+async function main(): Promise<void> {
+  const git = simpleGit(root);
+  await git.init();
+  await git.raw('config', 'user.name', 'Probe');
+  await git.raw('config', 'user.email', 'probe@t.test');
+  writeFileSync(resolve(root, 'README.md'), '# probe\n');
+  await git.add('README.md');
+  await git.commit('init');
+
+  const contentDir = resolve(root, 'articles');
+  mkdirSync(contentDir, { recursive: true });
+  writeFileSync(
+    resolve(contentDir, 'auth.md'),
+    '---\ntitle: Auth\ndescription: OAuth 2.0 flow\ntags:\n  - auth\n  - oauth\n---\n\n# Auth\n\nOAuth is...\n',
+  );
+  writeFileSync(
+    resolve(contentDir, 'sso.md'),
+    '---\ntitle: SSO\ntags:\n  - auth\n---\n\n# SSO\n\noauth provider...\n',
+  );
+
+  // Shadow-repo activity
+  const shadow = await initShadowRepo(root);
+  const branch = (await simpleGit(root).revparse(['--abbrev-ref', 'HEAD'])).trim();
+  const agent: WriterIdentity = { id: 'agent-claude-7x', name: 'Claude (Tim)', email: 'a@ok.test' };
+  const human: WriterIdentity = { id: 'human-tim', name: 'Tim Cardona', email: 't@ok.test' };
+  await commitWip(shadow, human, contentDir, 'initial auth doc', branch);
+  await new Promise((r) => setTimeout(r, 1100));
+  writeFileSync(resolve(contentDir, 'auth.md'), '# Auth v2\n\noauth rewrite.\n');
+  await commitWip(shadow, agent, contentDir, 'rewrite §3 oauth examples', branch);
+
+  const deps = { projectDir: root, serverUrl: undefined as string | undefined };
+
+  const runs: Array<{ label: string; cmd: string }> = [
+    { label: 'cat single file (rich enrichment)', cmd: 'cat articles/auth.md' },
+    { label: 'ls directory (slim enrichment each)', cmd: 'ls articles/' },
+    { label: 'grep | head pipe', cmd: 'grep -rn oauth articles/ | head -5' },
+    { label: 'denied: awk (unknown_command)', cmd: 'awk BEGIN{print}' },
+    { label: 'denied: redirection (write_blocked)', cmd: 'cat articles/auth.md > out.txt' },
+    { label: 'denied: subshell (shell_construct_blocked)', cmd: 'cat `ls`' },
+  ];
+
+  for (const { label, cmd } of runs) {
+    console.log('\n═══════════════════════════════════════════════════════════');
+    console.log(`  ${label}`);
+    console.log(`  exec(${JSON.stringify(cmd)})`);
+    console.log('═══════════════════════════════════════════════════════════');
+    const result = (await buildExecResult({ command: cmd }, deps)) as {
+      content: Array<{ text: string }>;
+      structuredContent: ExecStructuredResult;
+      isError?: boolean;
+    };
+    console.log(result.content[0].text.slice(0, 900));
+    if (result.structuredContent.error) {
+      console.log(`\n  [error.category] ${result.structuredContent.error.category}`);
+    } else {
+      console.log(`\n  [enrichedPaths] ${result.structuredContent.enrichedPaths.length} path(s)`);
+      for (const m of result.structuredContent.enrichedPaths) {
+        if ((m as { type?: string }).type === 'directory') {
+          const d = m as {
+            path: string;
+            recursiveMdCount: number;
+            childDirCount: number;
+          };
+          console.log(
+            `    - ${d.path}/ (directory): ${d.recursiveMdCount} md, ${d.childDirCount} subdirs`,
+          );
+        } else {
+          const f = m as { path: string; title?: string; historySource: unknown };
+          const rich = f.historySource !== null ? ' (rich)' : '';
+          console.log(`    - ${f.path}${rich}: ${f.title ?? '(no title)'}`);
+        }
+      }
+    }
+  }
+
+  console.log('\n═══════════════════════════════════════════════════════════');
+}
+
+try {
+  await main();
+} finally {
+  rmSync(root, { recursive: true, force: true });
+}

package/scripts/probe-read-document.ts

@@ -0,0 +1,111 @@
+/**
+ * End-to-end probe: buildReadResult flowing through the shared enrichPath
+ * → readShadowLog → shadow-repo bare git reads. Confirms agent/human
+ * attribution lands in the rendered output (FR15/D12/D13/R3).
+ *
+ * Run via: `bun run packages/cli/scripts/probe-read-document.ts`
+ * Not part of the test suite — a hand-runnable probe.
+ */
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import {
+  commitUpstreamImport,
+  commitWip,
+  initShadowRepo,
+  type WriterIdentity,
+} from '@inkeep/open-knowledge-server';
+import simpleGit from 'simple-git';
+import { buildReadResult } from '../src/mcp/tools/read-document.ts';
+
+const root = resolve(tmpdir(), `ok-probe-${Date.now()}`);
+mkdirSync(root, { recursive: true });
+
+async function main(): Promise<void> {
+  // 1. Set up a real git-backed project
+  const git = simpleGit(root);
+  await git.init();
+  await git.raw('config', 'user.name', 'Probe');
+  await git.raw('config', 'user.email', 'probe@t.test');
+  writeFileSync(resolve(root, 'README.md'), '# probe\n');
+  await git.add('README.md');
+  await git.commit('init');
+
+  const contentDir = resolve(root, 'content');
+  mkdirSync(contentDir, { recursive: true });
+  writeFileSync(
+    resolve(contentDir, 'auth.md'),
+    `---
+title: Auth
+description: OAuth 2.0 flow for SSO
+tags:
+  - auth
+  - oauth
+---
+
+# Auth
+
+OAuth is a protocol that...
+`,
+  );
+
+  // 2. Initialize the shadow repo and record some activity
+  const shadow = await initShadowRepo(root);
+  const branch = (await simpleGit(root).revparse(['--abbrev-ref', 'HEAD'])).trim();
+
+  const agent: WriterIdentity = {
+    id: 'agent-claude-code-7x',
+    name: 'Claude Code (Tim)',
+    email: 'agent@ok.test',
+  };
+  const human: WriterIdentity = {
+    id: 'human-tim',
+    name: 'Tim Cardona',
+    email: 'tim@ok.test',
+  };
+
+  await commitWip(shadow, human, contentDir, 'initial draft of auth doc', branch);
+  await new Promise((r) => setTimeout(r, 1100));
+  writeFileSync(resolve(contentDir, 'auth.md'), '# Auth v2\n\nRewrote §3 oauth examples.\n');
+  await commitWip(shadow, agent, contentDir, 'rewrite §3 oauth examples', branch);
+  await new Promise((r) => setTimeout(r, 1100));
+  writeFileSync(resolve(contentDir, 'auth.md'), '# Auth v3\n\nFixed typo.\n');
+  await commitWip(shadow, human, contentDir, 'typo fix', branch);
+  await new Promise((r) => setTimeout(r, 1100));
+  // And a fake "upstream" git pull import
+  const oldHead = 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0';
+  const newHead = 'f0e1d2c3b4a5f6e7d8c9b0a1f2e3d4c5b6a7f8e9';
+  await commitUpstreamImport(shadow, contentDir, oldHead, newHead, branch);
+
+  // 3. Call buildReadResult — the actual MCP-tool body, end to end
+  const output = await buildReadResult(
+    { path: 'content/auth.md' },
+    {
+      projectDir: root,
+      serverUrl: undefined, // disk-only, no Hocuspocus → backlinkCount stays null
+      config: {
+        mcp: {
+          tools: {
+            read_document: { historyDepth: 5 },
+            // biome-ignore lint/suspicious/noExplicitAny: probe-only cast; full config not needed
+          } as any,
+          // biome-ignore lint/suspicious/noExplicitAny: probe-only cast
+        } as any,
+        // biome-ignore lint/suspicious/noExplicitAny: probe-only cast
+      } as any,
+    },
+  );
+
+  console.log('═══════════════════════════════════════════════════════════');
+  console.log('  end-to-end probe: buildReadResult via shadow-repo');
+  console.log('═══════════════════════════════════════════════════════════');
+  console.log(output);
+  console.log('═══════════════════════════════════════════════════════════');
+  console.log(`  project root: ${root}`);
+}
+
+try {
+  await main();
+} finally {
+  rmSync(root, { recursive: true, force: true });
+}

package/dist/colors-CDmFQ1jq.mjs

@@ -1 +0,0 @@
-import{i as e,n as t,o as n,r}from"./colors-CEQEtnHQ.mjs";export{t as dim,r as error,e as info,n as warning};

package/dist/colors-CEQEtnHQ.mjs

@@ -1,2 +0,0 @@
-import e from"picocolors";const t=t=>e.red(t),n=t=>e.yellow(t),r=t=>e.cyan(t),i=t=>e.gray(t),a=t=>e.bold(t);function o(t,n){return e.isColorSupported?`\u001B]8;;${n}\u0007${t}\u001B]8;;\u0007`:t}export{o as a,r as i,i as n,n as o,t as r,a as t};
-//# sourceMappingURL=colors-CEQEtnHQ.mjs.map

package/dist/constants-XSxfsuBx.mjs

@@ -1,2 +0,0 @@
-import"./src-CB-sXsMW.mjs";var e=`0.0.0-dev-20260424044137`;const t=`AGENTS.md`,n=`config.yml`,r=`cache`,i=e,a=`open-knowledge`;export{i as a,a as i,r as n,n as r,t};
-//# sourceMappingURL=constants-XSxfsuBx.mjs.map

package/dist/init-BVuRoDMn.mjs

@@ -1,230 +0,0 @@
-import{n as e,r as t,t as n}from"./constants-XSxfsuBx.mjs";import{O as r}from"./src-CB-sXsMW.mjs";import{existsSync as i,mkdirSync as a,readFileSync as o,realpathSync as s,writeFileSync as c}from"node:fs";import{join as l,resolve as u}from"node:path";const d=`<!-- open-knowledge:begin -->`,f=`<!-- open-knowledge:end -->`,p=/<!-- open-knowledge:begin -->[\s\S]*?<!-- open-knowledge:end -->/,m=`# ${r}/ — Open Knowledge config
-
-This directory holds Open Knowledge's configuration for this project. It's **not** where content lives — content lives wherever \`content.dir\` + \`content.include\` in \`config.yml\` point. The default is the repo root with \`**/*.md\`, so any markdown file in the project is fair game. Inspect \`config.yml\` for the actual setting.
-
-## What's in here
-
-- \`config.yml\` — workspace config (content dir, include/exclude globs, MCP tool settings)
-- \`AGENTS.md\` — this file
-- \`cache/\` — derived data (gitignored)
-
-No scaffolded content directories. Organize knowledge wherever makes sense for the project — existing docs trees, topic-grouped subfolders, whatever. \`exec("ls <dir>")\` + per-file enrichment gives you a live overview of any directory on demand; there's no INDEX.md catalog to maintain.
-
-## Navigation — prefer \`exec\` for all reads
-
-\`exec\` is the primary MCP read surface. It runs a read-only bash command (cat, ls, grep, find, head, tail, wc, sort, uniq, cut — pipes OK) and returns raw stdout plus enriched metadata per file: title, description, tags, backlink count, recent shadow-repo activity with agent-vs-human attribution, and project git history.
-
-Examples (adapt paths to this project's layout):
-
-- Read a file: \`exec("cat <path>.md")\` — contents + full rich enrichment
-- List a directory: \`exec("ls <dir>")\` — names + slim per-file enrichment
-- Search: \`exec("grep -rn <term> <dir> | head -5")\` — matches + enrichment on matched files
-
-Typed tools (\`read_document\`, \`search\`, \`list_documents\`, etc.) remain available as "Typed call sites (advanced)" — use them when you need the typed \`structuredContent\` shape for programmatic parsing.
-
-## Suggested lifecycle (optional pattern)
-
-Projects that want an explicit knowledge-maturation flow can organize as three tiers **relative to the content directory** — create the subfolders only when you need them:
-
-1. **External sources** (e.g., \`external-sources/\` under \`content.dir\`) — raw content fetched from URLs, PDFs. No analysis, just preservation. Use the \`ingest\` MCP tool.
-2. **Research** (e.g., \`research/\` under \`content.dir\`) — analysis and synthesis. Provisional findings, trade-offs, open questions. Use the \`research\` MCP tool.
-3. **Articles** (e.g., \`articles/\` under \`content.dir\`) — canonical knowledge. Use the \`consolidate\` MCP tool to promote research → articles once decisions are made.
-
-This is a pattern, not a requirement. Projects with existing layouts (\`specs/\`, \`reports/\`, \`docs/\`, etc.) should use those; the lifecycle exists as mental scaffolding, not as enforced filesystem structure.
-
-## Linking — use \`[[wiki-links]]\` aggressively
-
-**When writing or editing any document, link liberally to every other document it relates to.** Open Knowledge's value compounds with link density: backlinks surface cross-document context in every read, graph queries (\`get_hubs\` / \`get_orphans\`) reveal structure, and agents navigate the knowledge base by following links. A document with no outbound links is an island.
-
-**Defaults when writing:**
-
-- Every noun-phrase that names another document is a link. Write \`[[Page Title]]\` instead of plain prose when mentioning concepts, projects, decisions, or entities that have (or should have) their own page. Redlinks are fine — they signal "this should exist."
-- Cross-link siblings: when creating a document in a folder, link to the 2–3 most related neighbors.
-- Link back to sources instead of re-summarizing — the reader can follow.
-- Prefer \`[[Page]]\` over Markdown \`[text](./page.md)\`. Wiki-links resolve by docName and participate in the backlinks index; Markdown links to other wiki files don't.
-
-**Rule of thumb:** if a human reader would want to click a term to learn more, make it a link. Err on the side of too many links.
-
-## Frontmatter Conventions
-
-Open Knowledge has two metadata surfaces that merge at read time:
-
-**Per-file frontmatter.** Every \`.md\` file that's part of the knowledge base should have YAML frontmatter:
-
-\`\`\`yaml
----
-title: Article Title (required)
-description: Brief summary (required)
-tags:
-  - relevant
-  - tags
----
-\`\`\`
-
-**Folder-level defaults via \`config.yml\` \`folders:\`.** Declare per-folder title/description/tags keyed by glob \`match:\` — see \`config.yml\` for the commented example. Rules apply in declaration order (later matches override earlier scalars), tags concat + dedup across all matching rules, and the file's own frontmatter always wins per-scalar. Folder defaults fill in blanks.
-
-Folder metadata lives in \`config.yml\`, **not** in content files — this is intentionally different from the rejected \`INDEX.md\`-inside-content pattern. The merge is computed on every \`exec("ls <dir>")\` / \`read_document\` / \`search\` call and is never written back to disk.
-
-## Scaffolding (first-time setup)
-
-This directory was scaffolded by running \`open-knowledge init\` (or \`npx @inkeep/open-knowledge init\`) in the project root. That command:
-
-1. Creates \`${r}/\` (config-only — no content subdirs)
-2. Writes \`AGENTS.md\`, \`.gitignore\`, and \`config.yml\`
-3. Registers the Open Knowledge MCP server in your selected editors' MCP config files (user-scoped by default)
-
-If you're onboarding a new project and \`${r}/\` doesn't exist yet, run \`open-knowledge init\` from a terminal.
-
-## Tools
-
-- **\`exec\`** — primary read surface (cat / ls / grep / find / pipes) with enriched output
-- **\`init-content\`** — bootstrap this knowledge base from the codebase
-- **\`ingest\`** — capture an external source as raw reference material
-- **\`research\`** — gather sources + write provisional findings
-- **\`consolidate\`** — promote research into canonical articles
-- **Writes** via \`write_document\` / \`edit_document\` — route through the server so shadow-repo attribution (agent vs human) is captured
-- **Graph queries** via \`get_backlinks\`, \`get_forward_links\`, \`get_orphans\`, \`get_hubs\`
-
-These tools are discovered via the standard MCP \`tools/list\` handshake and work in any MCP client (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Codex, etc.). \`open-knowledge init\` registers a single global \`open-knowledge\` entry in each selected editor's config, and the server resolves the active project per tool call from explicit \`cwd\` values or client-reported workspace roots. Claude Desktop requires a full quit + relaunch to pick up new MCP servers; other clients may need a new session or editor restart if they are already open.
-`,h=`# Open Knowledge — workspace configuration
-#
-# This file overrides built-in defaults for this workspace. Every key below
-# is commented out and shows its current default value. Uncomment any key
-# to override it.
-#
-# Precedence (lowest -> highest):
-#   Built-in defaults
-#     -> ~/${r}/config.yml         (user defaults)
-#     -> ./${r}/config.yml         (this file)
-#
-# Schema reference: packages/cli/src/config/schema.ts
-
-
-# --- Content ---------------------------------------------------------------
-# dir: where the CRDT editor reads/writes documents. Relative to the project
-# root (the directory containing ${r}/), NOT to this file.
-#
-# include/exclude: glob patterns for tracked content files. Relative to the
-# content directory (content.dir).
-#
-# content:
-#   dir: .
-#   include:
-#     - "**/*.md"
-#   exclude: []
-
-
-# --- Server ----------------------------------------------------------------
-# HTTP/WebSocket listener for the Hocuspocus server + static React app.
-#
-# openOnAgentEdit: when true, the browser opens automatically the first time
-# an agent writes to the knowledge base in this server session. Debounced to
-# one open per boot. Useful for pairing with Claude Code — you see the edit
-# land live. Leave false for headless/CI.
-#
-# server:
-#   port: 3000
-#   host: localhost
-#   openOnAgentEdit: false
-
-
-# --- Persistence -----------------------------------------------------------
-# How aggressively CRDT updates are flushed to disk.
-# persistence:
-#   debounceMs: 2000
-#   maxDebounceMs: 10000
-
-
-# --- Folders: per-folder frontmatter defaults -------------------------------
-#
-# TL;DR glob gotcha: \`**\` is ONLY a multi-segment wildcard when it is a
-# standalone path segment. \`foo-**\` behaves like \`foo-*\` (single segment, NOT
-# descendants). Use \`foo/**\` or \`foo-*/**\` to match descendants.
-#
-# Declare title/description/tags defaults keyed by glob \`match:\`. Rules merge
-# with a file's own frontmatter at read time:
-#   - Per scalar (title, description): the FILE wins when declared; folder
-#     rule fills in blanks.
-#   - Tags: concatenated across ALL matching rules (in declaration order) with
-#     file tags last; first-occurrence preserved on dedup.
-#   - Evaluation is positional — LATER rules in this array override earlier
-#     rules for scalars. Put general rules first, specific rules last.
-#
-# Picomatch glob cheatsheet:
-#   \`match: 'foo'\`         — matches ONLY the folder \`foo\` itself
-#   \`match: 'foo/**'\`      — matches \`foo\` AND all descendants (files + dirs)
-#   \`match: 'foo-*'\`       — matches \`foo-1\`, \`foo-bar\` (single segment)
-#   \`match: 'foo-**'\`      — behaves like \`foo-*\` (NOT multi-segment); see
-#                              TL;DR above. Use \`foo-*/**\` if you want
-#                              \`foo-X\` plus its descendants.
-#
-# Example:
-# folders:
-#   - match: 'specs/**'
-#     frontmatter:
-#       title: Specifications
-#       description: Feature specifications and design documents
-#       tags: [spec]
-#   - match: 'specs/2026-*/**'
-#     frontmatter:
-#       title: 2026 Specifications
-#       tags: [2026]
-`,g="**Preview before edit (REQUIRED).** You MUST follow this sequence every time you call `write_document` or `edit_document`:\n1. Call `get_preview_url` to obtain the browser URL for the target doc.\n   - If it returns `null`, the UI isn't running yet. Start it with `open-knowledge ui` from a terminal — or in Claude Code, call `preview_start(\"open-knowledge-ui\")` (the `open-knowledge init` command scaffolds this `.claude/launch.json` entry, so it's ready to go). `open-knowledge ui` auto-spawns the collab server in the background; you don't need to run `open-knowledge start` separately. Then call `get_preview_url` again — the UI writes a lock file that this tool reads.\n   - NEVER guess or manually construct the preview URL — always use the URL returned by `get_preview_url`.\n2. Open that URL in your preview browser so the user can see the document.\n3. Only then call `write_document` / `edit_document` — the CRDT edit will stream live into the already-open editor.\n\nNEVER call `write_document` or `edit_document` without first navigating the preview browser to the doc. The user expects to watch every edit land in real time. Write-tool responses include `previewUrl` (when resolvable) and a `warning` when no client is currently attached to the doc.",_=`${d}
-## Open Knowledge
-
-This repo uses Open Knowledge — collaborative markdown via MCP. **\`${r}/config.yml\`** (with optional \`~/${r}/config.yml\`; CLI/env may override) is the **path contract**: \`content.dir\` is the root for relative paths; \`content.include\` lists globs that **add** markdown; \`content.exclude\` lists globs that **remove** paths. Nothing else defines scope — not folder names, not "docs vs code." \`.gitignore\` still applies. When MCP is connected, the server's instructions echo the **resolved** \`dir\` / \`include\` / \`exclude\` for this session — treat that table and the YAML as two views of the same rules.
-
-**Default mental model (no jargon):** unless this project narrowed \`content.include\`, **every \`.md\` and \`.mdx\` under \`content.dir\`** is an Open Knowledge document — including under \`specs/\`, \`reports/\`, \`docs/\`, etc. If \`content.include\` is non-default, read \`config.yml\` once per turn so you do not mis-classify paths.
-
-**STOP — your host's built-in file tools on in-scope \`.md\` / \`.mdx\`.** When this workspace has Open Knowledge MCP configured (for example via a user-scoped editor config such as \`~/.claude.json\` or \`~/.cursor/mcp.json\`), you **must not** reach for native tools on in-scope markdown. Same failure mode as native \`Edit\` on them: no frontmatter, no backlinks, no shadow-repo activity, no recent-edit signal. The ban is broader than just \`Read\` / \`Grep\` / \`Glob\` — it names every common rationalization:
-
-- **Native \`Read\` / \`Grep\` / \`Glob\` on in-scope \`.md\` / \`.mdx\`** — the original case.
-- **\`Bash ls\` / \`Bash find\` / \`Bash cat\` on dirs containing in-scope markdown** — use \`exec("ls …")\` / \`exec("find … -name '*.md'")\` / \`exec("cat …")\` instead. Native returns bare names; \`exec\` returns frontmatter, backlink counts, and recent-activity per child.
-- **Glob patterns that target markdown** (\`**/*.md\`, \`**/SPEC.md\`, or any dir known to be markdown-heavy like \`specs/**\`, \`reports/**\`, \`stories/**\`, \`projects/**\`, \`docs/**\`) — use \`exec\` with \`find\`, or \`list_documents({ dir })\`.
-- **Dispatching the Explore / general-purpose subagent for markdown-heavy exploration** — subagents use native \`Read\` / \`Grep\` / \`Glob\` internally and bypass Open Knowledge entirely. Do markdown exploration yourself via \`exec\` / \`search\`. Subagents remain appropriate for **source-code** exploration (\`.ts\`, \`.py\`, configs, etc.).
-
-**MCP wiring varies by client:** Claude Code, Codex, Cursor, Windsurf, VS Code–class clients, and others surface MCP differently — server labels are user-defined; tools may not appear as a top-level symbol named \`exec\`. **If Open Knowledge is registered**, route markdown reads through its \`exec\` / \`search\` / \`read_document\` tools using **your client's documented MCP invocation** (including any generic "call MCP tool" flow). **That counts as available.** Not seeing \`exec\` in a flat tool list is **not** the escape hatch.
-
-**Escape hatch (narrow).** Native \`Read\` / \`Grep\` / \`Glob\` on \`.md\` / \`.mdx\` is allowed **only** when no Open Knowledge MCP server is registered for this project, **or** immediately after you **tried** an MCP call and it failed — then start a user-visible sentence with \`Open Knowledge MCP unavailable:\`. Never use the hatch because you skipped your client's MCP path.
-
-**Reads and searches on markdown:** Open Knowledge \`exec\` (or \`read_document\` / \`search\`) — same payloads whether your client invokes them directly or through MCP. Examples: \`exec("cat docs/auth.md")\`, \`exec("ls reports/")\`, \`exec("grep -rn karpathy specs/ | head -10")\`.
-
-**Listings too.** \`exec("ls <dir>/")\` is how you list a directory — it returns per-child frontmatter, recursive markdown counts, and the most-recently-updated doc per subdir. Plain \`Bash ls\` returns just names.
-
-**Anti-patterns at a glance:**
-
-| Task                             | Don't                        | Do                                              |
-| -------------------------------- | ---------------------------- | ----------------------------------------------- |
-| List a markdown-heavy dir        | \`Bash: ls specs/\`            | \`exec("ls specs/")\`                             |
-| Find all SPEC.md files           | \`Glob: **/SPEC.md\`           | \`exec("find specs -name SPEC.md")\`              |
-| Summarize specs across the repo  | \`Agent(Explore): "…"\`        | \`exec("head -25 specs/*/SPEC.md")\` + \`search\`   |
-| Search a phrase across markdown  | \`Grep: "pattern" *.md\`       | \`search({ query: "pattern" })\`                  |
-| Read an individual spec          | \`Read: specs/foo/SPEC.md\`    | \`read_document({ path: "specs/foo/SPEC.md" })\`  |
-
-**Source code and everything else** (\`.ts\`, \`.py\`, \`package.json\`, …): native \`Read\` / \`Grep\` / \`Glob\`.
-
-**Writing.** Edits to in-scope \`.md\` / \`.mdx\` go through \`write_document\` / \`edit_document\` only. Native \`Edit\` / \`sed\` land as anonymous \`upstream\` imports — you lose agent attribution in the shadow repo.
-
-${g}
-
-**No screenshots after edits.** Do NOT take \`preview_screenshot\` after every \`edit_document\` / \`write_document\`. Trust the CRDT tool response as confirmation the edit landed. Only screenshot when debugging a visual issue or when explicitly asked.
-
-**Linking.** Link liberally with \`[[wiki-links]]\` — every noun-phrase naming another document should be a link; redlinks are fine and signal "this should exist." Backlink density is how this knowledge base stays navigable for the next agent.
-
-- **What goes in the brackets:** the target's **docName** — folder path + filename without \`.md\` / \`.mdx\` (e.g. the file \`guides/auth-setup.md\` is linked as \`[[guides/auth-setup]]\`). NOT the human-readable title, NOT \`title:\` frontmatter, NOT \`aliases:\`. Wiki-links are absolute from the content root, never relative — \`[[foo]]\` means root-level \`foo.md\`, never \`guides/foo.md\` from inside \`guides/\`. Cross-folder links always need the full path.
-- **Display text different from the key:** \`[[guides/auth-setup|Auth Setup]]\` — pipe separator, target on the left, rendered label on the right. Anchors work the same way: \`[[guides/auth-setup#quickstart]]\`, or combined: \`[[guides/auth-setup#quickstart|see the quickstart]]\`.
-- **Verify before walking away:** after writing a doc, call \`get_dead_links({ sourceDocNames: ['your/doc/name'] })\` — every unresolved bracket-target in that doc is listed. Fix or accept the redlinks deliberately. The editor's red-underline visual tolerates a slug fallback (\`[[Auth Setup]]\` may look resolved if \`auth-setup.md\` exists at root), but the backlink graph is strict-exact — trust \`get_dead_links\`, not the visual.
-
-**Organize by folders, not hub files.** Folders are the organizational unit — group related docs in a shared folder and let the directory listing do the cataloging. Per-folder metadata (title, description, tags) lives in \`.open-knowledge/config.yml\` under the \`folders:\` key (glob \`match:\` + frontmatter defaults that merge with each file's own frontmatter at read time). Don't maintain an \`INDEX.md\` / \`README.md\` hub file inside a folder solely to catalog its children — \`exec("ls <folder>")\` returns the same view live, with per-file frontmatter + backlink counts.
-
-**Server must be running.** If \`write_document\` or \`edit_document\` returns a "Hocuspocus server is not running" error, start it with \`open-knowledge start\` (via Bash) and retry. NEVER fall back to native \`Edit\` / \`Write\` for in-scope markdown — always use the MCP write tools so edits go through the CRDT layer with proper attribution.
-
-**Non-markdown files.** Use native \`Read\` / \`Edit\` / \`Grep\` / \`Bash\` for source code, configs, and anything outside the path contract in \`config.yml\`: under \`content.dir\`, matching \`content.include\`, not removed by \`content.exclude\` or \`.gitignore\`.
-${f}`;function v(e,t,r){let a=[n,...r??[]],u=new Set,d=[];for(let n of a){let r=l(e,n),a=i(r),f=a?s(r):r;if(u.has(f)){d.push({file:n,path:r,action:`skipped-symlink`});continue}if(u.add(f),!a){c(r,`${_}\n`,`utf-8`),d.push({file:n,path:r,action:`created`});continue}let m=o(r,`utf-8`),h=p.test(m);if(h&&!t){d.push({file:n,path:r,action:`skipped-existing`});continue}if(h){c(r,m.replace(p,_),`utf-8`),d.push({file:n,path:r,action:`replaced`});continue}c(r,`${m.replace(/\n*$/,``)}\n\n${_}\n`,`utf-8`),d.push({file:n,path:r,action:`appended`})}return d}function y(e,t){return i(e)?!1:(c(e,t,`utf-8`),!0)}function b(e){let t=l(e,`.gitignore`),n=`# Open Knowledge — local editor config (not tracked upstream)\n${r}/\n`;if(!i(t))return c(t,n,`utf-8`),`created`;let a=o(t,`utf-8`),s=new Set([r,`${r}/`,`/${r}`,`/${r}/`]);return a.split(`
-`).map(e=>e.trim()).some(e=>s.has(e))?`already-present`:(c(t,`${a}${a.length===0||a.endsWith(`
-`)?``:`
-`}${a.length>0&&!a.endsWith(`
-
-`)?`
-`:``}${n}`,`utf-8`),`appended`)}const x=[{name:n,content:m},{name:`.gitignore`,content:`${e}/\nserver.lock\nui.lock\nsync-state.json\n`},{name:t,content:h}];function S(t){let n=u(t,r),i=[],o=[];a(n,{recursive:!0}),a(l(n,e),{recursive:!0});for(let e of x)y(l(n,e.name),e.content)?i.push(e.name):o.push(e.name);return{created:i,skipped:o}}export{b as a,g as i,d as n,S as o,f as r,v as s,_ as t};
-//# sourceMappingURL=init-BVuRoDMn.mjs.map

package/dist/init-CJTyH3QE.mjs

@@ -1 +0,0 @@
-import{a as e,i as t,n,o as r,r as i,s as a,t as o}from"./init-BVuRoDMn.mjs";export{o as CLAUDE_MD_SECTION,n as OK_MARKER_BEGIN,i as OK_MARKER_END,t as PREVIEW_GUIDANCE,e as ensureOkGitignoredAtRoot,r as initContent,a as upsertRootInstructions};