@inkeep/open-knowledge 0.63.5 → 0.63.6

package/README.md

@@ -24,7 +24,7 @@ ok start         # serve the editor and open it in your browser
 
 - `ok init` — turn a folder into an OpenKnowledge project and register the MCP server with supported AI tools.
 - `ok start` — run the local server and web editor, then open it in your browser.
-- `ok open <file.md>` — open a single Markdown file in the editor.
+- `ok open <target>` — open a doc, a folder, or a path to a Markdown file in the editor. It prints the project root it resolved; pass `--project <dir>` anywhere in the command to name one yourself.
 - `ok --help` — list every command.
 
 ## Desktop app

package/dist/THIRD_PARTY_NOTICES.md

@@ -6632,6 +6632,7 @@ The following MIT-licensed packages are patched in this repository via pnpm's `p
 | `@pierre/trees@1.0.0-beta.4` | `patches/@pierre%2Ftrees@1.0.0-beta.4.patch` |
 | `@tiptap/extension-drag-handle@3.22.3` | `patches/@tiptap%2Fextension-drag-handle@3.22.3.patch` |
 | `@tiptap/y-tiptap@3.0.3` | `patches/@tiptap%2Fy-tiptap@3.0.3.patch` |
+| `@xterm/xterm@6.0.0` | `patches/@xterm%2Fxterm@6.0.0.patch` |
 | `react-medium-image-zoom@5.4.3` | `patches/react-medium-image-zoom@5.4.3.patch` |
 | `react-resizable-panels@4.12.1` | `patches/react-resizable-panels@4.12.1.patch` |
 | `y-indexeddb@9.0.12` | `patches/y-indexeddb@9.0.12.patch` |

package/dist/{acp-harness-probe-DWsC0HGJ.mjs → acp-harness-probe-Dc4CN4gg.mjs}

@@ -1,7 +1,7 @@
-import{pt as e}from"./sleep-D4NlDISj.mjs";import{Ri as t}from"./src-bhsVUHJJ.mjs";import{F as n,M as r,N as i}from"./fs-traced-Dm4NQ6S5.mjs";import{b as a,g as o,m as s,p as c,s as l}from"./resolve-project-root-BF1NyEri.mjs";import{S as ee,T as u,d as te,o as d,v as f,x as ne}from"./init-wSrUXJrK.mjs";import{t as p}from"./is-object-Bw0-z8qH.mjs";import{execFileSync as m,spawn as h}from"node:child_process";import{basename as re,dirname as g,join as _,resolve as ie,win32 as v}from"node:path";import{existsSync as y,mkdirSync as b,readFileSync as x,readdirSync as ae,statSync as oe,writeFileSync as se}from"node:fs";import{homedir as S}from"node:os";var C=e();const w=`open-knowledge`;function T(e){try{e()}catch{}}var E=class{backend=`keyring`;constructor(e){this.onKeychainRead=e}async get(e){let{Entry:t}=await import(`@napi-rs/keyring`),n;try{n=new t(w,e).getPassword()}catch(t){return T(()=>this.onKeychainRead?.({kind:`read-error`,host:e,error:t instanceof Error?t.name:`unknown`})),null}if(n==null)return T(()=>this.onKeychainRead?.({kind:`absent`,host:e})),null;try{return JSON.parse(n)}catch{return T(()=>this.onKeychainRead?.({kind:`corrupt-entry`,host:e,error:`corrupt-entry`})),null}}async set(e,t,n,r){let{Entry:i}=await import(`@napi-rs/keyring`),a=new i(w,e),o={login:t,token:n,...r};a.setPassword(JSON.stringify(o))}async clear(e){let{Entry:t}=await import(`@napi-rs/keyring`);try{new t(w,e).deletePassword()}catch{}}},D=class{backend=`file`;authFile;constructor(e){this.authFile=e??_(S(),`.ok`,`auth.yml`)}read(){if(!y(this.authFile))return{};try{return(0,C.parse)(x(this.authFile,`utf-8`))??{}}catch(e){let t=e instanceof Error?e.message:`unknown error`;return process.stderr.write(`[auth] Failed to parse ${this.authFile}: ${t}. Starting with empty credentials.\n`),{}}}write(e){let t=g(this.authFile);y(t)||b(t,{recursive:!0,mode:448}),se(this.authFile,(0,C.stringify)(e),{mode:384})}async get(e){return this.read()[e]??null}async set(e,t,n,r){let i=this.read();i[e]={login:t,token:n,...r},this.write(i)}async clear(e){let t=this.read();delete t[e],this.write(t)}},ce=class{backend=`keyring`;constructor(e,t){this.keychain=e,this.file=t}async get(e){let t=await this.keychain.get(e);if(t!=null)return t;let n=await this.file.get(e);if(n==null)return null;try{await this.keychain.set(e,n.login,n.token,{gitProtocol:n.gitProtocol,name:n.name,email:n.email}),await this.file.clear(e),process.stderr.write(`[auth] migrated ${e} credential from ~/.ok/auth.yml to the OS keychain\n`)}catch{}return n}set(e,t,n,r){return this.keychain.set(e,t,n,r)}async clear(e){await this.keychain.clear(e),await this.file.get(e)!=null&&await this.file.clear(e)}};async function O(e,t){try{let{Entry:n}=await import(`@napi-rs/keyring`);return new n(w,`__probe__`),process.stderr.write(`[auth] token storage: OS keychain
+import{yt as e}from"./sleep-DyLEGHvt.mjs";import{Bi as t}from"./src-DKRPWoiG.mjs";import{I as n,N as r,P as i}from"./fs-traced-C5oeVBiQ.mjs";import{b as a,g as o,m as s,p as c,s as l}from"./resolve-project-root-FELgKP-i.mjs";import{S as ee,T as u,d as te,o as d,v as f,x as ne}from"./init-uVQCRG14.mjs";import{t as p}from"./is-object-Bw0-z8qH.mjs";import{execFileSync as m,spawn as h}from"node:child_process";import{basename as re,dirname as g,join as _,resolve as ie,win32 as v}from"node:path";import{existsSync as y,mkdirSync as b,readFileSync as x,readdirSync as ae,statSync as oe,writeFileSync as se}from"node:fs";import{homedir as S}from"node:os";var C=e();const w=`open-knowledge`;function T(e){try{e()}catch{}}var E=class{backend=`keyring`;constructor(e){this.onKeychainRead=e}async get(e){let{Entry:t}=await import(`@napi-rs/keyring`),n;try{n=new t(w,e).getPassword()}catch(t){return T(()=>this.onKeychainRead?.({kind:`read-error`,host:e,error:t instanceof Error?t.name:`unknown`})),null}if(n==null)return T(()=>this.onKeychainRead?.({kind:`absent`,host:e})),null;try{return JSON.parse(n)}catch{return T(()=>this.onKeychainRead?.({kind:`corrupt-entry`,host:e,error:`corrupt-entry`})),null}}async set(e,t,n,r){let{Entry:i}=await import(`@napi-rs/keyring`),a=new i(w,e),o={login:t,token:n,...r};a.setPassword(JSON.stringify(o))}async clear(e){let{Entry:t}=await import(`@napi-rs/keyring`);try{new t(w,e).deletePassword()}catch{}}},D=class{backend=`file`;authFile;constructor(e){this.authFile=e??_(S(),`.ok`,`auth.yml`)}read(){if(!y(this.authFile))return{};try{return(0,C.parse)(x(this.authFile,`utf-8`))??{}}catch(e){let t=e instanceof Error?e.message:`unknown error`;return process.stderr.write(`[auth] Failed to parse ${this.authFile}: ${t}. Starting with empty credentials.\n`),{}}}write(e){let t=g(this.authFile);y(t)||b(t,{recursive:!0,mode:448}),se(this.authFile,(0,C.stringify)(e),{mode:384})}async get(e){return this.read()[e]??null}async set(e,t,n,r){let i=this.read();i[e]={login:t,token:n,...r},this.write(i)}async clear(e){let t=this.read();delete t[e],this.write(t)}},ce=class{backend=`keyring`;constructor(e,t){this.keychain=e,this.file=t}async get(e){let t=await this.keychain.get(e);if(t!=null)return t;let n=await this.file.get(e);if(n==null)return null;try{await this.keychain.set(e,n.login,n.token,{gitProtocol:n.gitProtocol,name:n.name,email:n.email}),await this.file.clear(e),process.stderr.write(`[auth] migrated ${e} credential from ~/.ok/auth.yml to the OS keychain\n`)}catch{}return n}set(e,t,n,r){return this.keychain.set(e,t,n,r)}async clear(e){await this.keychain.clear(e),await this.file.get(e)!=null&&await this.file.clear(e)}};async function O(e,t){try{let{Entry:n}=await import(`@napi-rs/keyring`);return new n(w,`__probe__`),process.stderr.write(`[auth] token storage: OS keychain
 `),T(()=>t?.onBackendSelected?.({backend:`keyring`})),new ce(new E(t?.onKeychainRead),new D(e))}catch(n){let r=n instanceof Error?`${n.name}: ${n.message}`:String(n);return process.stderr.write(`[auth] token storage: file (~/.ok/auth.yml) — OS keychain unavailable: ${r}\n`),T(()=>t?.onBackendSelected?.({backend:`file`,reason:r})),new D(e)}}function k(e){let t=null;return function(){if(t)return t;let n=2e3;return t=(async()=>{let t=null,r=new Promise(r=>{t=setTimeout(()=>{process.stderr.write(`[auth] token storage: keyring init exceeded ${n}ms; falling back to file (~/.ok/auth.yml)\n`),r(new D(e))},n)});try{return await Promise.race([O(e),r])}catch{return new D(e)}finally{t!==null&&clearTimeout(t)}})(),t}}function le(e){let t=k(e);return{async get(e){let n=await(await t()).get(e);return n===null?null:{token:n.token,login:n.login}}}}function ue(e){let t=k(e);return{backend:`file`,async get(e){return(await t()).get(e)},async set(e,n,r,i){return(await t()).set(e,n,r,i)},async clear(e){return(await t()).clear(e)}}}async function de(e,t){let n=[],r=new D(t);await r.get(e)!=null&&(await r.clear(e),n.push(`file`));let i;try{let{Entry:t}=await import(`@napi-rs/keyring`);new t(w,`__probe__`);let r,a=await new E(e=>{e.kind===`read-error`&&(r=e.error??`read-error`)}).get(e);if(r!==void 0)i=r;else if(a!=null)try{new t(w,e).deletePassword(),n.push(`keychain`)}catch(e){i=e instanceof Error?e.name:`delete-error`}}catch{}return{touched:n,keychainError:i}}const fe=[`/opt/homebrew/bin/gh`,`/usr/local/bin/gh`,`/opt/local/bin/gh`,`/snap/bin/gh`,`/usr/bin/gh`],A={encoding:`utf-8`,stdio:[`ignore`,`pipe`,`pipe`],timeout:5e3,windowsHide:!0};function j(e,t={}){let{login:n}=t,r=t._exec??m,i=M(t._fileExists??y),a=e?[`--hostname`,e]:[];if(n){let e=N(r,i,[`auth`,`token`,...a,`--user`,n]);if(e)return{available:!0,token:e,resolvedLogin:n,fallback:!1}}let o=N(r,i,[`auth`,`token`,...a]);return o?n?{available:!0,token:o,fallback:!0}:{available:!0,token:o}:{available:!1}}function M(e){return[`gh`,...fe.filter(e)]}function N(e,t,n){for(let r of t)try{let t=e(r,n,A).toString().trim();if(t.length>0)return t}catch{}}function P(e,t={}){let n=t._exec??m,r=M(t._fileExists??y),i=[`auth`,`status`,...e?[`--hostname`,e]:[]],a=N(n,r,[...i,`--json`,`hosts`]);if(a!==void 0){let t=I(a,e);if(t)return t}let o=N(n,r,i);if(o!==void 0){let e=V(o);if(e.length>0)return e}}function F(e){return typeof e==`object`&&e&&!Array.isArray(e)?e:void 0}function I(e,t){let n;try{n=JSON.parse(e)}catch{return}let r=F(F(n)?.hosts);if(!r||t!==void 0&&r[t]===void 0)return;let i=t===void 0?Object.values(r):[r[t]],a=[];for(let e of i){if(!Array.isArray(e))return;for(let t of e){let e=F(t);if(!e)continue;let n=e.login;typeof n!=`string`||n.length===0||a.push({login:n,active:e.active===!0})}}return a}const L=/Logged in to \S+ account (\S+) \(/,R=/(?:Failed to log in to|Timeout trying to log in to) \S+/,z=/^\s*-\s*Active account:\s*true\s*$/,B=/\u001b\[[0-9;]*m/g;function V(e){let t=[],n;for(let r of e.split(`
 `)){let e=r.replace(B,``),i=L.exec(e)?.[1];if(i){n={login:i,active:!1},t.push(n);continue}if(R.test(e)){n=void 0;continue}n&&z.test(e)&&(n.active=!0)}return t}function pe(e){let t={...e};return delete t.ELECTRON_RUN_AS_NODE,t}function H(e){let t=e?.code;return t===`ENOENT`||t===`EACCES`||t===`EPERM`?{ok:!1,reason:`not-installed`}:{ok:!1,reason:`spawn-error`}}function U(e){return t({detached:!0,stdio:`ignore`,shell:!1,env:pe(e)})}function W(e,t,n={}){let r=(n.spawn??h)(e,[...t],U(n.env??process.env));return r.unref(),r}function me(e,t,n={}){let r=n.spawn??h,i=n.timeoutMs??2e3;return new Promise(a=>{let o=!1,s=e=>{o||(o=!0,a(e))},c=setTimeout(()=>s({ok:!1,reason:`timeout`}),i);try{let i=r(e,[...t],U(n.env??process.env));i.once(`error`,e=>{clearTimeout(c),s(H(e))}),i.once(`spawn`,()=>{clearTimeout(c),s({ok:!0})});try{i.unref()}catch{}}catch(e){clearTimeout(c),s(H(e))}})}const G=`com.inkeep.open-knowledge`,K=`OpenKnowledge.app`,q=`/Applications/${K}`;function he(){return{platform:process.platform,env:process.env,execPath:process.execPath,isTTY:process.stdout.isTTY,statSync:e=>{try{return oe(e,{throwIfNoEntry:!1})??null}catch{return null}}}}function ge(e){if(e.env.ELECTRON_RUN_AS_NODE===`1`){let t=/(.+?\.app)\/Contents\/MacOS\//.exec(e.execPath);if(t?.[1])return t[1]}if(J(e,q))return q;let t=_(e.homeDir??S(),`Applications`,K);return J(e,t)?t:null}function J(e,t){return Y(e,_(t,`Contents`,`MacOS`,`OpenKnowledge`))}function Y(e,t){try{let n=e.statSync(t);return n&&typeof n.isFile==`function`?n.isFile():!1}catch{return!1}}const _e=[`@inkeepopen-knowledge-desktop`,`OpenKnowledge`];function ve(e){if(e.env.ELECTRON_RUN_AS_NODE===`1`&&/\\OpenKnowledge\.exe$/i.test(e.execPath))return e.execPath;let t=e.env.LOCALAPPDATA;if(t)for(let n of _e){let r=v.join(t,`Programs`,n,`OpenKnowledge.exe`);if(Y(e,r))return r}return null}function ye(e){if(e.env.ELECTRON_RUN_AS_NODE===`1`&&e.execPath.endsWith(`/openknowledge`))return e.execPath;let t=`/opt/OpenKnowledge/openknowledge`;return Y(e,t)?t:null}function be(e){if(e.env.OK_FORCE_BROWSER===`1`)return{available:!1,reason:`force-browser`};if(e.platform!==`darwin`&&e.platform!==`win32`&&e.platform!==`linux`)return{available:!1,reason:`unsupported-platform`};let t;try{t=e.platform===`darwin`?ge(e):e.platform===`win32`?ve(e):ye(e)}catch{return{available:!1,reason:`stat-error`}}return t?e.env.OK_FORCE_DESKTOP===`1`?{available:!0,reason:`available`,bundlePath:t}:!(e.isTTY===!0||e.platform===`win32`&&e.isTTY===void 0&&!e.env.CI)||e.env.SSH_CONNECTION||e.env.SSH_TTY||e.platform===`linux`&&!e.env.DISPLAY&&!e.env.WAYLAND_DISPLAY?{available:!1,reason:`headless`,bundlePath:t}:{available:!0,reason:`available`,bundlePath:t}:{available:!1,reason:`no-bundle`}}function xe(e,t){let n=e.log??(e=>console.error(e)),r=e.platform??process.platform;if(n("Launching OpenKnowledge desktop (use `ok start` for the browser server, or `OK_FORCE_BROWSER=1` to always skip)"),r===`darwin`){W(`open`,[`-b`,G],{spawn:e.spawn});return}let i=t?.bundlePath;if(!i){n(`Desktop launch skipped: no resolved desktop executable (caller bug).`);return}W(i,[],{spawn:e.spawn})}function Se(e=`no-bundle`){switch(e){case`no-bundle`:return`Desktop app not found (checked the standard install locations for this OS). Install it from https://openknowledge.ai/download, or omit --mode for browser mode.`;case`darwin-only`:case`unsupported-platform`:return`Desktop app is not available on this platform. Use --mode=browser, or omit --mode for the server fallback.`;case`headless`:return`Desktop launch is gated in headless contexts (CI, SSH, non-TTY stdout). Set OK_FORCE_DESKTOP=1 to override, or use --mode=browser.`;case`force-browser`:return`OK_FORCE_BROWSER=1 is set — desktop dispatch is disabled. Unset it to use --mode=app.`;case`stat-error`:return`Failed to inspect the desktop install (filesystem error). Check permissions or use --mode=browser.`;case`available`:return`Desktop app appears available but launch dispatch did not fire (caller bug).`}}function X(e,t){let n=ie(e),r=t===void 0?a():a({home:t,env:{}});return{cwd:n,bridgePath:l.pi.projectConfigPath?.(n)??``,trustPath:_(r,`trust.json`)}}function Z(e,t,n){let r=d(l.pi,e,n,t);if(r.kind===`absent`)return{state:`absent`,text:null};if(r.kind!==`present`)return{state:`unreadable`,text:null};let i=r.entry,a=Array.isArray(i.args)&&typeof i.args[0]==`string`?i.args[0]:null;return s(i)?{state:`own-current`,text:a}:ee(i)?{state:`own-stale`,text:a}:{state:`foreign`,text:a}}function Q(e,t){let n;try{n=x(e,`utf-8`)}catch(e){let t=e.code;return t===`ENOENT`||t===`ENOTDIR`?{state:`untrusted`,entries:{},trailingNewline:!1}:{state:`unreadable`,entries:null,trailingNewline:!1}}if(n.trim()===``)return{state:`untrusted`,entries:{},trailingNewline:!1};let r;try{r=JSON.parse(n)}catch{return{state:`unreadable`,entries:null,trailingNewline:!1}}return p(r)?{state:r[t]===!0?`trusted`:`untrusted`,entries:r,trailingNewline:n.endsWith(`
 `)}:{state:`unreadable`,entries:null,trailingNewline:!1}}function Ce(e,t){let n=X(e,t),r=Z(n.cwd,n.bridgePath,t).state,i=Q(n.trustPath,n.cwd).state;return{...n,bridge:r,trust:i,bridgeLoadable:(r===`own-current`||r===`own-stale`)&&i===`trusted`,otherExtensions:$(n.bridgePath).names}}function $(e){let t=g(e),n=re(e);try{return{names:ae(t).filter(e=>e!==n&&e.endsWith(`.ts`)).sort(),verified:!0}}catch(e){let t=e.code;return{names:[],verified:t===`ENOENT`||t===`ENOTDIR`}}}async function we(e,t={mode:`published`},n){let r=X(e,n),i=Z(r.cwd,r.bridgePath,n);if(i.state===`foreign`)return{...r,ok:!1,bridge:`refused-foreign`,trust:`skipped`};if(i.state===`unreadable`)return{...r,ok:!1,bridge:`refused-unreadable`,trust:`skipped`};let a;if(i.state===`absent`)a=`written`;else{let e;try{e=ne(t)}catch{e=void 0}a=e!==void 0&&i.text===e?`unchanged`:`refreshed`}if(a!==`unchanged`){let e=f(l.pi,r.cwd,t,n,r.bridgePath);if(e.action!==`written`&&e.action!==`overwritten`)return{...r,ok:!1,bridge:`failed`,trust:`skipped`,error:e.error??`bridge write ${e.action}`}}let o=await Te(r.trustPath,r.cwd);return{...r,ok:o.action===`already-trusted`||o.action===`added`,bridge:a,trust:o.action,...o.error===void 0?{}:{error:o.error}}}async function Te(e,t){try{b(g(e),{recursive:!0})}catch(e){return{action:`failed`,error:e instanceof Error?e.message:String(e)}}let i={action:`added`};try{await r(`${e}.lock`,async()=>{let r=Q(e,t);if(r.state===`trusted`){i.action=`already-trusted`;return}if(r.entries===null){i.action=`refused-unreadable`;return}let a={...r.entries,[t]:!0},o=JSON.stringify(a,null,2)+(r.trailingNewline?`
 `:``),s=u(e);n(e,o,s===void 0?void 0:{mode:s}),i.action=`added`})}catch(e){return{action:`failed`,error:e instanceof Error?e.message:String(e)}}return i.action===`refused-unreadable`?{action:`refused-unreadable`,error:`trust store is not a readable JSON object`}:{action:i.action}}function Ee(e,t){let r=X(e,t),a=$(r.bridgePath);if(!a.verified)return{action:`kept-unverified`,error:`could not read the Pi extensions folder`};if(a.names.length>0)return{action:`kept-shared`};if(!y(r.trustPath))return{action:`not-present`};let o={action:`removed`};try{i(`${r.trustPath}.lock`,()=>{let e=Q(r.trustPath,r.cwd);if(e.entries===null){o.action=e.state===`unreadable`?`refused-unreadable`:`not-present`;return}if(!(r.cwd in e.entries)){o.action=`not-present`;return}let t={...e.entries};delete t[r.cwd];let i=JSON.stringify(t,null,2)+(e.trailingNewline?`
 `:``),a=u(r.trustPath);n(r.trustPath,i,a===void 0?void 0:{mode:a}),o.action=`removed`})}catch(e){return{action:`failed`,error:e instanceof Error?e.message:String(e)}}return o.action===`refused-unreadable`?{action:`refused-unreadable`,error:`trust store is not a readable JSON object`}:{action:o.action}}function De(e){return e===`opencode`?o:c}function Oe(e,t,n){let r=l[e],i=De(e),a=[],o=r.projectConfigPath?.(t);o!==void 0&&a.push({scope:`project`,configPath:o});try{a.push({scope:`user`,configPath:r.configPath(t,n)})}catch{}for(let o of a){let a=te(r,t,n,o.configPath);if(a!==null&&i(a))return{editorId:e,scope:o.scope,configPath:o.configPath}}return null}export{ue as _,G as a,xe as c,me as d,j as f,le as g,O as h,Ee as i,Se as l,de as m,we as n,he as o,P as p,Ce as r,be as s,Oe as t,W as u};
-//# sourceMappingURL=acp-harness-probe-DWsC0HGJ.mjs.map
+//# sourceMappingURL=acp-harness-probe-Dc4CN4gg.mjs.map

package/dist/assets/skills/discovery/SKILL.md

@@ -112,9 +112,18 @@ If the OK MCP server isn't wired into this host there is no `preview_url` to
 call — use the `ok open` path above. Don't reconstruct what `preview_url` does
 by hand (spawning `ok mcp` yourself, scraping ports from `ok ps`).
 
-The path must be absolute (a file outside a project has no cwd to anchor a
-relative path). Re-opening the same file lands on the same session. Never
-construct or guess the URL — use the one `preview_url` returns.
+Give an absolute path. `ok open` prints the absolute project root it resolved
+for that path, and names the enclosing project too when the resolved root sits
+inside another one. Read that line rather than assuming which project you got.
+
+To name the project yourself, pass `--project <dir>`. It is honored wherever it
+appears: `--project <dir>` or `--project=<dir>`, before or after the path, with
+or without the `.md` extension. If it cannot be honored the command exits
+non-zero and says why, so you never need a second command to find out where it
+landed, and never need to stop a server to correct it.
+
+Re-opening the same file lands on the same session. Never construct or guess the
+URL — use the one `preview_url` returns.
 
 ## What else OK does
 

package/dist/assets/skills/packs/codebase-wiki/references/generate-and-refresh.md

@@ -102,10 +102,10 @@ Atomic pages for domain terms and core abstractions (one term each): definition,
 ### Phase 7 — Link-graph activation + audit
 
 1. Confirm **OVERVIEW links every page** (it is the nav hub). Add any missing nav links. This is OVERVIEW's check — it's a *source* (high out-degree), verified by forward links here, not by the `hubs` view below.
-2. Run `links({ kind: ["orphans", "hubs", "dead"] })`:
+2. Run `links({ kind: ["orphans", "hubs"] })`, then `audit`:
    - **orphans** — pages nothing links to. Adopt each by linking it from OVERVIEW or a relevant section page (or, rarely, justify it as intentionally standalone).
    - **hubs** — ranks by *inbound* links. Confirm your **concept/module pages** show up here — that's the signal cross-linking actually happened. Don't expect `OVERVIEW`: a freshly authored nav page has almost no inbound links, so it won't appear (and that's correct — its coverage was checked in step 1).
-   - **dead** — fix or remove every dead link. (Source-file links don't appear in this graph — only `.md`/`.mdx` edges are tracked — but they ARE validated by `brokenLinks` on each write/edit, per the code-reference rule above.)
+   - **`audit`** — returns clean (every lint violation + broken internal link) — fix every finding. (This covers links to source files too, not just `.md`/`.mdx`: it's the `orphans`/`hubs` graph above that tracks doc-to-doc edges only. `brokenLinks` on each write/edit is the same check per-write, per the code-reference rule above.)
 3. Append a `wiki/log.md` entry (see *Log discipline*).
 4. Tell the user the wiki is ready and surface the OVERVIEW preview URL.
 

package/dist/assets/skills/packs/knowledge-base/research/SKILL.md

@@ -336,7 +336,7 @@ Run this checklist before marking complete:
 - File exists at the chosen path under the content directory
 - Frontmatter has `title`, `description`, `type: research-note`, `status: draft`, `date`, and an object-shaped `sources:` list
 - `exec("ls -A <dir>")` lists the new file with frontmatter enrichment
-- `links({ kind: 'dead', sourceDocNames: ['<path-without-ext>'] })` returns clean — zero dead links (fix or remove every one)
+- `audit({ path: "<doc-path>.md" })` returns clean (every lint violation + broken internal link) — fix every finding
 - Every factual claim in Findings cites a source inline
 - Linked source files from Step 3 all exist (broken source links → ingest went wrong somewhere)
 - At least 1-2 neighbor docs now link to this research (per Step 6's "After writing, update ..." rule)

package/dist/assets/skills/packs/okf/SKILL.md

@@ -21,7 +21,7 @@ metadata:
 - Use standard Markdown links for portable relationships. Broken links and a missing index are allowed.
 - `index.md` and `log.md` are reserved at every level. Use lowercase filenames.
 - An `index.md` normally has no frontmatter; only the root index may declare `okf_version: "0.2"`.
-- A `log.md` is newest-first; entry headings begin `## YYYY-MM-DD: Summary`.
+- A `log.md` is newest-first; entry headings begin with an ISO date — `## YYYY-MM-DD: Summary` (the summary after the date is optional; a bare `## YYYY-MM-DD` is equally conformant).
 - OKF consumers read `.md`, not `.mdx`.
 
 ## Authoring judgment

package/dist/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md

@@ -184,7 +184,7 @@ Run before you tell the user it's ready:
 
 - Every referenced decision, spec, or guide is a plain markdown relative link (`[text](./decisions/0004-x.md)`), never backticked, never an HTML anchor.
 - Add backlinks from 1–2 closely related docs so the proposal is discoverable — the accepted decision it revisits, a related spec, the relevant guide. `links({ kind: "backlinks", ... })` to see what already points where.
-- `links({ kind: "dead", sourceDocNames: ["proposals/0007-async-export-pipeline"] })` returns clean — fix or remove every dead link.
+- `audit({ path: "proposals/0007-async-export-pipeline.md" })` returns clean (every lint violation + broken internal link) — fix every finding.
 - Frontmatter complete: `type: proposal`, a one-line `description`, `status: draft`, `authors`, `created`, `tags: [proposal]`.
 - All five H2 sections present and non-empty: `## Motivation`, `## Design`, `## Drawbacks`, `## Alternatives`, `## Unresolved questions`. An empty Drawbacks or a strawman Alternatives fails this check even though the section technically exists.
 - `status` is still `draft`. You do not advance it — see Non-goals.

package/dist/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md

@@ -159,8 +159,8 @@ Then add a line near the top of the old record's Context (or a short `> Supersed
 
 ## Step 8 — Link and validate
 
-- **Backlinks in:** ensure the parent proposal links forward to this decision, and any spec that *implements* this decision links back to it. `links({ kind: "backlinks", docName: "decisions/0012-adopt-event-sourcing-for-orders" })` to see who points here; add the missing ones so the record is discoverable.
-- **Dead links out:** `links({ kind: "dead", sourceDocNames: ["decisions/0012-adopt-event-sourcing-for-orders"] })` returns clean — zero dead links. Fix or remove every one; a broken link to a superseded record defeats the whole chain.
+- **Backlinks in:** ensure the parent proposal links forward to this decision, and any spec that *implements* this decision links back to it. `links({ kind: "backlinks", document: "decisions/0012-adopt-event-sourcing-for-orders" })` to see who points here; add the missing ones so the record is discoverable.
+- **Validate:** `audit({ path: "decisions/0012-adopt-event-sourcing-for-orders.md" })` returns clean (every lint violation + broken internal link) — fix every finding; a broken link to a superseded record defeats the whole chain.
 - **Frontmatter complete:** `type`, `description`, `status`, `date`, `deciders`, `supersedes`, `tags` all present and correct.
 - **Status reflects reality:** if the deciders have accepted, flip `status: proposed` → `accepted`. If they haven't, leave it `proposed` and tell the user it's awaiting sign-off. Do not mark a decision `accepted` on the user's behalf.
 - **Body shape:** exactly `## Context`, `## Decision`, `## Consequences`, in order. No extra top-level sections — depth that doesn't fit these three belongs in a linked spec.

package/dist/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md

@@ -175,7 +175,7 @@ Pre-fill the stub with the **symptom** (how you'd recognize this again — "chec
 - Add a `## Related` section linking **every prior postmortem that shares a subsystem** (from Step 2), plus the `decisions/` and `specs/` implicated — the decision that set the config policy, the spec for the component that failed. `[2024-01-11 payments pool](./postmortems/2024-01-11-payments-pool.md)`, `[connection-pool sizing decision](./decisions/2023-11-04-pool-sizing.md)`.
 - Link the runbook stubs you created in Step 9 from their action items (done above) and from `## Related`.
 - Update the hub of any folder you touched if it has one (an `INDEX.md` in `postmortems/`) so the new incident shows up in the index — the preview becomes a live progress bar.
-- Validate: `links({ kind: "dead", sourceDocNames: ["postmortems/YYYY-MM-DD-name"] })` returns clean — fix or drop every dead link. Confirm frontmatter is complete and the Summary / Timeline / Root cause / What went well / Action items sections are all filled, none left as template placeholder.
+- Validate: `audit({ path: "postmortems/YYYY-MM-DD-name.md" })` returns clean (every lint violation + broken internal link) — fix every finding. Confirm frontmatter is complete and the Summary / Timeline / Root cause / What went well / Action items sections are all filled, none left as template placeholder.
 
 ---
 

package/dist/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md

@@ -262,7 +262,7 @@ Specs that don't link back are islands. Wire the spec into the graph and prove i
 - **Backlink the parent proposal** inline in the spec body: `derived from [Payment retries proposal](./proposals/0004-payment-retries.md)`. Plain markdown relative link — never backticked, never an HTML anchor.
 - **Link every decision the spec depends on** — if the design rests on a frozen record in `decisions/`, link it where it's relied upon.
 - Update the parent proposal (and any hub) to link forward to this spec, so the spec is discoverable via backlinks. `links({ kind: "backlinks", ... })` to confirm the reverse edge registered.
-- `links({ kind: "dead", sourceDocNames: ["specs/004-payment-retries/spec"] })` — returns clean, zero dead links. Fix or remove every one.
+- `audit({ path: "specs/004-payment-retries/spec.md" })` returns clean (every lint violation + broken internal link) — fix every finding.
 - Frontmatter complete: `type`, `description`, `status`, `owner`, `parent_proposal`, `created`, `tags` all present.
 
 ---

package/dist/assets/skills/project/SKILL.md

@@ -21,11 +21,11 @@ OpenKnowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. Th
 3. **Preview / open a doc — determine your ONE surface FIRST (once per session).** Stop at first match: **`OK_DESKTOP_TERMINAL` or `OK_HOSTED_AGENT` set** → you're inside OpenKnowledge (desktop terminal / in-app agent panel) → `ok open <name>` (switches the window the user is already looking at); never paste a `localhost` URL into your reply here · in-app browser (Claude Code Desktop's Browser pane, Cursor, Codex) → `preview_url`, then open/navigate it to the doc · else plain CLI → `ok open <name>`. `ok open <name>` opens a doc or folder (auto-detected); `--skill <name>` for a skill. The `previewUrl` field is a route id, **not** your open mechanism. Don't `preview_screenshot` to confirm edits. Full Step-0 procedure + per-surface how-to: `references/preview.md`.
 4. **Knowledge layers:** capturing a source (ingest), synthesizing findings (research), promoting a decision (consolidate) — procedures, **not tool calls**; there is no `ingest` tool. Ingest ships here (`references/ingest-and-sources.md`); research + consolidate come with the `knowledge-base` pack. Layer model + packs: `references/starter-packs.md`.
 5. **Direct questions:** a plain business question ("which customers…", "what did we decide about…") routes to `search` / `exec` + a cited chat answer — no "research" keyword needed. Persist only when durable + multi-doc + not already covered, and *offer* first. See `references/corpus-qa.md`.
-6. **Authoring or improving a skill** ("write/make a skill", "improve this skill", "turn this into a skill"): STOP and invoke the **`/open-knowledge-write-skill`** skill — it owns scope choice (project vs global), the SKILL.md contract, evaluation, and install; don't improvise here. Author through the `skill` target (`write({ skill })`), never a raw path document. Skills are REAL folders under the editor dirs' `skills/` (`.claude` · `.cursor` · `.codex` · `.github` · `.opencode` · `.pi` · `.agents`): ONE is the source, the rest are managed copies/symlinks. **Read and edit via the tools (`skills`, `edit({ skill })`) — they route to the source.** Never hand-edit a non-source copy: unedited copies refresh from the source, and editing one forks it into its own skill that stops refreshing.
+6. **Authoring or improving a skill** ("write/make/improve a skill", "turn this into a skill"): STOP and invoke **`/open-knowledge-write-skill`** for scope (project/global), contract, evaluation, and install. Author through `write({ skill })`, never a document path. Skills are real folders under editor `skills/` dirs (`.claude` · `.cursor` · `.codex` · `.github` · `.opencode` · `.pi` · `.agents`): one source plus managed copies/symlinks. **Read/edit via `skills` and `edit({ skill })` — they route to the source.** Never hand-edit a non-source copy: managed copies refresh from the source; editing one forks it and stops refresh.
 
 ## Tool index — 21 tools (router; the MCP tool descriptions carry each tool's full contract)
 
-- **Reads** — `exec` (primary; read-only `cat`/`ls`/`grep`/… plus frontmatter/backlink/history enrichment; one command or one pipe, not a shell), `search` (ranked BM25 + recency), `history` (doc versions), `links` (`kind: backlinks|forward|dead|orphans|hubs|suggest`, or an array for one call), `skills` (search + read: `query` → skills.sh; omit `name` to LIST managed (Project + Global); `name` READs one — by `name`+`scope`, never path), `config` (resolved config), `palette` (authoring forms + `html preview` starters + theme tokens; `palette({ components })` for JSX schemas), `preview_url` (browser preview URL on demand), `share_link` (GitHub-substrate share URL; read-only, errors without a GitHub remote), `lint` (markdown-lint violations: `document` for one doc, omit for the project; `fix: true` with `document` auto-fixes fixable rules in place — attributed, live in the preview; the rest need `edit`/`write`), `audit` (every lint violation + broken internal link in one read-only report, by source file with lines; `path` scopes; for link VALIDATION use this, not `links`).
+- **Reads** — `exec` (primary; read-only `cat`/`ls`/`grep`/… plus frontmatter/backlink/history enrichment; one command or one pipe, not a shell), `search` (ranked BM25 + recency), `history` (doc versions), `links` (`kind: backlinks|forward|dead|orphans|hubs|suggest`, or an array for one call), `skills` (search + read: `query` → skills.sh; omit `name` to LIST managed (Project + Global); `name` READs one — by `name`+`scope`, never path), `config` (resolved config), `palette` (authoring forms + `html preview` starters + theme tokens; `palette({ components })` for JSX schemas), `preview_url` (browser preview URL on demand), `share_link` (GitHub-substrate share URL; read-only, errors without a GitHub remote), `lint` (markdown-lint violations: `document` for one doc, omit for the project; `fix: true` with `document` auto-fixes fixable rules in place — attributed, live in the preview; the rest need `edit`/`write`), `audit` (every lint violation + broken internal link in one read-only report, by source file with lines; `path` scopes; for link VALIDATION use this, not `links`; caveats in `references/linking.md`). **Read `ran` on successful `lint`/`audit` results to see which enabled source families were selected. A family absent from `ran` was not checked, and `[]` means no checks were selected at all.**
 - **Writes** — four native CRUD verbs, polymorphic over `document` / `folder` / `template` / `skill` / `asset` (pass EXACTLY ONE target, nested under its address key): `write` (create/overwrite; `write({ skill: {…} })` authors a skill as a REAL folder at the project's default skill home — live immediately for that folder's agent), `edit` (body find/replace/frontmatter merge-patch; no asset), `delete` (remove), `move` (move/rename, rewrites referrers; a skill also takes `scope`/`toScope` for Project↔Global — history resets, re-`install`). Output mirrors the input key; the preview envelope (`previewUrl`, `warning`) stays top-level. Plus `install` (WHERE a `skill` lives: `add`/`remove` locations additively — editor ids, `agents`, or custom roots; `mode` + `convert` re-form ONLY the locations named; `source` moves the real folder. The source folder IS the skill — no "uninstall everywhere"; a skill dies only via `delete`), `import` (acquire a skill-dir into `add`'s locations; scripts never run), `checkpoint` (named version), and `restore_version` (roll back). A folder's frontmatter is open-shape and self-only (does NOT cascade); templates are what new docs start with.
 - **Conflicts** — `conflicts` (`kind: list|content`), `resolve_conflict` (write a resolution + commit; destructive). See `references/conflict-resolution.md`.
 
@@ -83,7 +83,7 @@ Link every noun-phrase that names another document — `[text](./relative/path.m
 
 ## Folders, frontmatter, templates
 
-Every `.md` / `.mdx` needs YAML frontmatter — `title` + `description` required, `tags` recommended. Two **opt-in, nested** folder mechanisms: folder frontmatter (`<folder>/.ok/frontmatter.yml` — the folder's own open-shape properties; self-only, does NOT cascade into child docs) and templates (`<folder>/.ok/templates/` — what new docs start with). Most folders have NO `.ok/`. A doc's frontmatter is exactly its own on-disk YAML. Structural model + the full pre-write checklist: `references/folder-model.md`. Template authoring + folder editing: `references/template-authoring.md`. Frontmatter-vs-body edit rules: `references/doc-editing.md`.
+Every `.md` / `.mdx` needs YAML frontmatter — `title` + `description` required, `tags` recommended. **OKF projects (`okf` pack) are the exception:** pack rules win — a non-root `index.md` carries NO frontmatter (the `frontmatter-reserved-index` lint warns on any key), `log.md` needs none, and concept docs need only a non-empty `type`; `title`/`description` are optional there. Two **opt-in, nested** folder mechanisms: folder frontmatter (`<folder>/.ok/frontmatter.yml` — the folder's own open-shape properties; self-only, does NOT cascade into child docs) and templates (`<folder>/.ok/templates/` — what new docs start with). Most folders have NO `.ok/`. A doc's frontmatter is exactly its own on-disk YAML. Structural model + the full pre-write checklist: `references/folder-model.md`. Template authoring + folder editing: `references/template-authoring.md`. Frontmatter-vs-body edit rules: `references/doc-editing.md`.
 
 - **Read the folder before writing (MUST).** Before creating/editing docs in a folder, call `exec("ls -A <folder>")` once per folder per session — it returns the folder's `title`/`description`/`tags` + `templates_available`. Skipping it lands docs that violate folder discipline. (If a folder has no frontmatter AND no templates AND the repo has substantial content elsewhere, it isn't onboarded — run `references/onboard-existing-repo.md` first.)
 - **Use a template when one fits (MUST).** Instantiate via `write({ document: { path, template } })`; inherited templates count. Skip only when none match or the user asked for free-form (note why in chat). Create templates proactively when a shape recurs.

package/dist/assets/skills/project/references/folder-model.md

@@ -2,7 +2,7 @@
 
 (Core carries the MUST gates: read the folder before writing, use a template when one fits, bake recurring properties into a template. This file is the structural model.)
 
-Every `.md` / `.mdx` file needs YAML frontmatter — `title` + `description` required, `tags` recommended:
+Every `.md` / `.mdx` file needs YAML frontmatter — `title` + `description` required, `tags` recommended (except in OKF projects, where the `okf` pack's reserved-file rules override this — see core):
 
 ```yaml
 ---

package/dist/assets/skills/project/references/linking.md

@@ -10,7 +10,7 @@
 - **Never wrap a link in backticks.** `` `[text](./foo.md)` `` is a bug — the backticks make it render as literal code rather than a link.
 - **Never use HTML anchors** (`<a href="...">`). Markdown link syntax only.
 - **`brokenLinks` on the write/edit response is your primary check — read it before walking away.** Every `write`/`edit` returns `brokenLinks` in the SAME payload: `[]` means every outbound link resolves; a populated list names each broken `href` with its `resolvedTo` + `reason` (`no-such-doc` = resolved to a doc that doesn't exist; `no-such-file` = resolved to a linked asset / source file that isn't on disk at that path; `unresolvable` = the path escapes the content root, usually one `../` too many). This validates **every** local link, not just doc links: a wrong-depth `[src](../../foo.py)` to a source file is caught too. It is report-only — the write landed regardless; fix or remove every one in a follow-up `edit`.
-- **`links({ kind: "dead" })` is the authoritative end-state audit.** For a corpus-wide sweep across many docs: `links({ kind: "dead", sourceDocuments: ["your/doc"] })`. Companion `links` kinds: `backlinks` (incoming), `forward` (outgoing), `orphans` (no incoming), `hubs` (high-incoming), `suggest` (untextualized mentions worth linking).
+- **`audit` is the authoritative end-state link check** — run it once at the end of a multi-doc pass. Caveat: `audit` reports links only while the project's `validation.links` setting is not `off` (at `off` it returns clean with no warning), so if the project has silenced link validation, fall back to `links({ kind: "dead" })` — the unconditional read of the dead-link graph, which also lists sources `audit` excludes, such as skill-bundle docs (optionally scoped: `links({ kind: "dead", sourceDocuments: ["your/doc"] })`). Otherwise `links` is the graph-navigation reader, supplemental to `audit`, not a substitute. Companion `links` kinds: `backlinks` (incoming), `forward` (outgoing), `orphans` (no incoming), `hubs` (high-incoming), `suggest` (untextualized mentions worth linking).
 - **The tool and the editor agree.** Both resolve a bare name the same way — exact, then slug, then folder index, then basename — so a link that opens when you click it is never reported dead, and a link reported dead is genuinely unresolvable. A target that names an asset, or names nothing at all, stays silent rather than being reported as a broken doc link.
 
 **Note on wiki-link syntax (`[[Page]]`):** the parser still handles it for legacy content, but it's NO LONGER the recommended default. Write new content with standard markdown links per above. Seed-pack templates (`ok seed --pack <name>`) may still emit `[[Page]]` placeholders inside template body text — those are legacy. When you instantiate a seed-pack template, replace the legacy placeholders with standard markdown links during the `{shape}`-fill pass.

package/dist/assets/skills/project/references/media-and-assets.md

@@ -2,13 +2,13 @@
 
 - **Markdown syntax only:** `![alt text](./path/to/image.png)`. Do NOT emit HTML `<img>` tags — they don't participate in OK's content graph and don't render consistently across Fumadocs / preview surfaces. Paths resolve relative to the doc.
 - **Always a doc-relative path — never a server URL.** Reference an asset by its path relative to the doc (`./image.png`, `../assets/foo.png`), never an absolute `http://localhost:<port>/…`, `127.0.0.1`, or other server URL. `preview_url`'s `url` navigates the *preview* — it is NOT an asset path; never paste it (or any `localhost` base) into an `![]()`. An asset already in the tree is the same rule: find its path with `exec("ls -A <dir>")` and write the relative link. (Upload via `write({ asset })` hands you the exact relative `![alt](ref)` to copy.)
-- **Save locally, don't hot-link.** Hot-linked external image URLs rot when the source disappears. Fetch (`WebFetch` / `curl`), save to a local path, reference via relative markdown link, cite the source below.
+- **Save locally, don't hot-link.** Hot-linked external image URLs rot when the source disappears. Fetch it through the ingest procedure in `references/ingest-and-sources.md` (SSRF-safe fetch flags, size + executable-extension gates, wrapper frontmatter) — never an ad-hoc `WebFetch` / `curl` into the tree — then reference the local file via a relative markdown link and cite the ingested wrapper below.
 - **Placement model.** Free-form image embeds → co-located alongside the referencing doc (sha256 same-directory dedup). Raw sources via `ingest` → `external-sources/<slug>.<ext>` + `external-sources/<slug>.md` (the wrapper-binary pair). Check via `exec("ls -A")` if the project uses a different convention.
 - **Cannot fetch** (no network, paywall) → don't invent a local path. Omit, or mark inline `(TODO: image needs sourcing from <URL>)`.
 - **Meaningful alt text required** — describes WHAT the image shows, not what it is. `![]()` / `![image]()` / `![filename.png]()` all fail. OK indexes alt text — it's both accessibility AND searchability.
 - **Cite web image sources** below the image (Grounding rule):
   ```markdown
-  ![Aang using the Avatar State to defeat Ozai](./assets/images/aang/avatar-state.png)
-  *Source: [Avatar Wiki — Aang](https://avatar.fandom.com/wiki/Aang#Avatar_State)*
+  ![Aang using the Avatar State to defeat Ozai](./external-sources/avatar-wiki-aang.png)
+  *Source: [Avatar Wiki — Aang](./external-sources/avatar-wiki-aang.md)*
   ```
-  Original diagrams/screenshots may caption `*Original*` or omit. Unattributed web images are equivalent to unsourced factual claims.
+  (Both paths are relative to the citing doc; ingest lands the binary + wrapper pair side by side, so cite the wrapper next to the binary you embedded.) Original diagrams/screenshots may caption `*Original*` or omit. Cite the local ingested wrapper (whose frontmatter carries the original URL), not the external URL — an inline external link is a TODO meaning "still needs ingesting". Unattributed web images are equivalent to unsourced factual claims.

package/dist/assets/skills/project/references/onboard-existing-repo.md

@@ -161,7 +161,7 @@ Six sub-passes, each with its own STOP gate.
 ### 5a. Orphan triage (STOP gate 5a)
 
 1. Run `links({ kind: "orphans" })`.
-2. For each orphan, run `links({ kind: "suggest", docName: <orphan> })`:
+2. For each orphan, run `links({ kind: "suggest", document: <orphan> })`:
    - If `mentions[]` is non-empty → there are docs that mention this orphan without linking. Adoption candidates.
    - If `mentions[]` is empty → the orphan is **genuinely standalone** (no other doc references it at all). Surface as: "this looks intentionally standalone (e.g., a README). Skip / adopt anyway by linking from a hub / add to `.okignore`?"
 3. Confirm per orphan. For each "link" choice, `edit({ document: { path, find, replace } })` on the source doc — find the existing mention text `links({ kind: "suggest" })` surfaced and replace it wrapped in link syntax.
@@ -179,7 +179,7 @@ Six sub-passes, each with its own STOP gate.
 
 ### 5c. Dead-link sweep (STOP gate 5c)
 
-1. Run `links({ kind: "dead" })` (no `sourceDocNames` → audits the whole corpus).
+1. Run `audit` (the authoritative end-state link check; it covers the whole corpus — caveats in `references/linking.md`). `links({ kind: "dead" })` is the graph reader, not the validation step; it is a superset on the source side (it also lists dead links whose source is a skill-bundle doc, which `audit` skips).
 2. For each dead link, propose: a fix candidate (via `search` for the correct target), or deletion (remove the link, or the prose around it). Leaving it as an "intentional redlink" is not an option — every dead link is fixed or removed.
 3. Confirm per dead-link. Apply confirmed fixes via `edit`.
 
@@ -187,7 +187,7 @@ Six sub-passes, each with its own STOP gate.
 
 `links({ kind: "suggest" })` implements server-side detection of prose mentions of a target doc that aren't wrapped in link syntax. Lean on it directly.
 
-1. For each substantial `[KB]` doc, run `links({ kind: "suggest", docName: <target> })`.
+1. For each substantial `[KB]` doc, run `links({ kind: "suggest", document: <target> })`.
 2. Each call returns `mentions[]` with `{ source, excerpt, offset }` — places to insert links pointing TO this target from OTHER docs.
 3. Surface batched **by source doc** (not per-link, to keep cognitive load reasonable):
 
@@ -209,7 +209,7 @@ Harder case: prose discusses a concept covered by another doc without naming it.
 1. For each substantial doc, identify its main concepts. Use frontmatter `subjects:` / `topics:` if present; else extract from heading text + the first 2-3 paragraphs.
 2. For each concept, run `search({ query: <concept> })`. Take the top 1-2 non-self results.
 3. For each candidate sibling:
-   - Verify it is NOT already linked from this doc (`links({ kind: "forward", docName: <doc> })`).
+   - Verify it is NOT already linked from this doc (`links({ kind: "forward", document: <doc> })`).
    - Verify the content is actually relevant (re-read the summary).
 4. Surface to the user with brief justification per pair. Confirm. Apply via `edit` (insert the link in a "Related" or "References" section).
 
@@ -232,7 +232,7 @@ After all confirmed proposals are applied:
 1. Re-run `exec("ls -A <folder>")` on every `[KB]` folder. Verify:
    - the folder's descriptive `title`/`description`/`tags` are populated (folder frontmatter landed)
    - `templates_available` includes the new template (template landed)
-2. Re-run the orphan + dead-link audit in one call — `links({ kind: ["orphans", "dead"] })`. Confirm the orphan count dropped vs. the Phase 5a baseline and that fixed dead links no longer report.
+2. Re-run `audit` to confirm fixed dead links no longer report, and `links({ kind: "orphans" })` to confirm the orphan count dropped vs. the Phase 5a baseline.
 
 If any validation step fails, surface it to the user — do NOT silently pass.
 

package/dist/assets/skills/project/references/preview.md

@@ -41,6 +41,7 @@ Decide once; then every "open / show / preview this doc" this session uses that
 - **`ok open <name>`** — opens a **doc or folder** in the OK Desktop app. The type is auto-detected (a directory on disk → folder, otherwise a doc), so **`--folder` is not needed** (it stays only as an explicit override for a folder that doesn't exist on disk yet). An action you run, not a URL to print.
 - **`ok open <skill-name> --skill [--scope project|global]`** — opens a **skill** in the skill editor (skills are addressed by name + scope, not a content path, so they need the flag).
 - All three deep-link into OK Desktop when a bundle is installed, and fall back to the browser UI (`ok start`) otherwise. No `ok` on PATH or no shell → `preview_url`, then `open <url>` in the system browser as a last resort, and say so plainly. The system browser is the fallback, never the default.
+- **`ok open` prints the absolute project root it resolved**, and names the enclosing project too when that root sits inside another one. Read that line instead of assuming which project you got. To name the project yourself, pass `--project <dir>`; it is honored wherever it appears (`--project <dir>` or `--project=<dir>`, before or after the target, with or without a `.md` extension), or the command exits non-zero saying why.
 
 (The same vendors' *desktop apps* with a built-in browser — Cursor, Codex desktop — are NOT here; they navigate their own browser per the in-app branch above. Codex **IDE extension** / **Cloud** are web-search-only → they're on this CLI track too.) **Running inside OpenKnowledge itself — the desktop built-in terminal (`OK_DESKTOP_TERMINAL`) or the in-app agent panel (`OK_HOSTED_AGENT`)? Same track — `ok open <name>` re-targets the surface you're already in** (switches it to the doc/folder; when that surface is a desktop window there's no second window, and no need to raise it since it's already frontmost). Don't resolve preview URLs in that case; `ok open` is the whole answer.
 

package/dist/cli.d.mts

@@ -1,7 +1 @@
-import { Logger } from "pino";
-
-//#region src/cli.d.ts
-declare function getCliLogger(): Logger | undefined;
-//#endregion
-export { getCliLogger };
-//# sourceMappingURL=cli.d.mts.map
+export { };