@vpxa/kb 0.1.32 → 0.1.34

package/packages/server/dist/tools/present.tool.js

@@ -1,114 +1 @@
-import{getToolMeta as e}from"../tool-metadata.js";import{escHtml as t}from"./present-utils.js";import{renderChecklistHtml as n,renderComparisonHtml as r,renderProgressHtml as i,renderPromptHtml as a,renderStatusBoardHtml as o,renderTimelineHtml as s}from"./present-blocks.js";import{renderChartAsHtml as c}from"./present-charts.js";import{FONT_LINK as l,getDesignSystemCSS as u}from"./present-theme.js";import{readFileSync as d}from"node:fs";import{dirname as f,join as p}from"node:path";import{fileURLToPath as m}from"node:url";import{z as h}from"zod";import{exec as g}from"node:child_process";import{createServer as _}from"node:http";import{createUIResource as v}from"@mcp-ui/server";import{RESOURCE_MIME_TYPE as y,registerAppResource as b,registerAppTool as x}from"@modelcontextprotocol/ext-apps/server";import{marked as S}from"marked";S.setOptions({async:!1,gfm:!0,breaks:!0}),S.use({renderer:{html(e){return t(e.text)}}});const C=import.meta.dirname??f(m(import.meta.url)),w=`ui://kb/present.html`;function T(){return p(C,`..`,`..`,`..`,`present`,`dist`,`index.html`)}let E;function D(){if(!E)try{E=d(T(),`utf-8`)}catch{E=``}return E}const O=h.object({type:h.enum([`button`,`select`]).describe(`Action type`),id:h.string().describe(`Unique action identifier`),label:h.string().describe(`Display label`),variant:h.enum([`primary`,`danger`,`default`]).optional().describe(`Button style variant`),options:h.array(h.union([h.string(),h.object({label:h.string(),value:h.string()})])).optional().describe(`Select options (for type=select)`)}),k={format:h.enum([`html`,`browser`]).default(`html`).describe(`Output format.
-- "html" (default): Rich markdown in chat + embedded UIResource for MCP-UI hosts. Actions shown as numbered choices.
-- "browser": Rich markdown in chat + opens beautiful themed dashboard in the browser. When actions are provided, the browser shows interactive buttons and the tool blocks until the user clicks, returning their selection.`),title:h.string().optional().describe(`Optional heading`),content:h.any().describe(`Content to present. Accepts: markdown string, array of objects (→ table), { nodes, edges } (→ mermaid graph), typed blocks [{ type, value }], or any JSON (→ tree).`),actions:h.array(O).optional().describe(`Interactive actions (buttons/selects). In html mode, shown as numbered choices. In browser mode, rendered as clickable buttons and the tool blocks until user clicks.`)};let A=!1;function j(t,n){let r=e(`present`);A||=(b(t,`KB Present App`,w,{description:`Rich interactive content viewer for KB tools`},async()=>({contents:[{uri:w,mimeType:y,text:D()}]})),!0),x(t,`present`,{title:r.title,description:`Present content to the user in the best format. Two modes:
-- "html" (default): Rich markdown in chat + embedded UIResource. Actions shown as numbered choices for display.
-- "browser": Rich markdown in chat + serves a themed dashboard on a local URL that auto-opens in your system browser. If openBrowserPage is available, also call it with the returned URL. When actions are provided, browser shows interactive buttons and the tool blocks until user clicks.
-Use "html" for in-chat display. Use "browser" for visual dashboards and when you need interactive user input back.
-After calling present with format "browser", extract the URL from the response and call openBrowserPage({ url }) to open it in VS Code.`,annotations:r.annotations,inputSchema:k,_meta:{ui:{resourceUri:w}}},async({format:e,title:t,content:r,actions:i})=>(e??`html`)===`browser`?await N(t,r,i,n):J(t,r,i))}let M=null;process.on(`exit`,()=>{if(M){try{M.close()}catch{}M=null}});async function N(e,t,n,r){let i=P(e,t),a=q(e,t,n),o,s,c=Array.isArray(n)?n:[],l=``;try{M&&=(M.close(),null),c.length>0&&(o=new Promise(e=>{s=e})),l=await new Promise((e,t)=>{let n=_((e,t)=>{if(e.method===`POST`&&e.url===`/callback`){let n=``;e.on(`data`,e=>{n+=e.toString()}),e.on(`end`,()=>{t.writeHead(200,{"Content-Type":`application/json`,"Access-Control-Allow-Origin":`*`}),t.end(`{"ok":true}`);try{let e=JSON.parse(n);s?.(e)}catch{}});return}if(e.method===`OPTIONS`){t.writeHead(204,{"Access-Control-Allow-Origin":`*`,"Access-Control-Allow-Methods":`POST`,"Access-Control-Allow-Headers":`Content-Type`}),t.end();return}t.writeHead(200,{"Content-Type":`text/html; charset=utf-8`}),t.end(a)});n.listen(0,`127.0.0.1`,()=>{let r=n.address();typeof r==`object`&&r?(M=n,e(`http://127.0.0.1:${r.port}`)):t(Error(`Failed to start present server`))}),setTimeout(()=>{n.close(),M===n&&(M=null)},300*1e3).unref()});try{g(process.platform===`win32`?`start "" "${l}"`:process.platform===`darwin`?`open "${l}"`:`xdg-open "${l}"`)}catch{}}catch{}let u=v({uri:`ui://kb/present-static.html`,content:{type:`rawHtml`,htmlString:a},encoding:`text`,adapters:{mcpApps:{enabled:!0}}}),d=l?`${i}\n\n---\n🌐 **Dashboard opened in browser:** ${l}`:i;if(c.length>0&&r?.available&&o)try{let e=await Promise.race([o,new Promise((e,t)=>setTimeout(()=>t(Error(`timeout`)),300*1e3))]);return{content:[{type:`text`,text:`${d}\n\n✅ **Selected:** ${e.actionId} = \`${e.value}\``},u]}}catch{return{content:[{type:`text`,text:`${d}\n\n⚠️ *No selection received (timed out).*`},u]}}return{content:[{type:`text`,text:d},u]}}function P(e,t){let n=[];if(e&&n.push(`# ${e}\n`),typeof t==`string`)n.push(t);else if(Array.isArray(t))if(t.length===0)n.push(`*(empty)*`);else if(Z(t[0]))for(let e of t)n.push(F(e));else if(typeof t[0]==`object`&&t[0]!==null)n.push(I(t));else for(let e of t)n.push(`- ${String(e)}`);else if(typeof t==`object`&&t){let e=t;Array.isArray(e.nodes)&&Array.isArray(e.edges)?n.push(R(e)):Array.isArray(e.metrics)?n.push(L(e.metrics)):n.push(z(e))}else n.push(String(t));return n.join(`
-`)}function F(e){let t=[];switch(e.title&&t.push(`## ${e.title}\n`),e.type){case`markdown`:t.push(String(e.value??``));break;case`code`:t.push(`\`\`\`${e.language??``}\n${String(e.value??``)}\n\`\`\``);break;case`mermaid`:t.push(`\`\`\`mermaid\n${String(e.value??``)}\n\`\`\``);break;case`table`:Array.isArray(e.value)&&t.push(I(e.value));break;case`metrics`:Array.isArray(e.value)&&t.push(L(e.value));break;case`graph`:e.value&&typeof e.value==`object`&&t.push(R(e.value));break;case`cards`:if(Array.isArray(e.value))for(let n of e.value)t.push(`### ${n.title??`Card`}`),(n.body||n.description)&&t.push(String(n.body??n.description)),(n.badge||n.status)&&t.push(`> **${n.badge??n.status}**`),t.push(``);break;case`tree`:e.value&&typeof e.value==`object`&&t.push(z(e.value));break;case`chart`:{let n=e.value;n?.data&&Array.isArray(n.data)&&t.push(`*${String(n.chartType??`chart`)} chart — ${n.data.length} data points*`);break}case`timeline`:{let n=e.value;if(n?.items)for(let e of n.items){let n=e.status===`done`?`✅`:e.status===`active`?`🔄`:e.status===`error`?`❌`:`⬜`;t.push(`${n} **${e.title}**${e.description?` — ${e.description}`:``}`)}break}case`checklist`:{let n=e.value;if(n?.items)for(let e of n.items)t.push(`- [${e.checked?`x`:` `}] ${e.label}${e.note?` — ${e.note}`:``}`);break}case`comparison`:{let n=e.value;if(n?.columns&&n.columns.length>0){let e=Math.max(...n.columns.map(e=>e.items?.length??0)),r=n.columns.map(e=>e.title);t.push(`| ${r.join(` | `)} |`),t.push(`| ${r.map(()=>`---`).join(` | `)} |`);for(let r=0;r<e;r++)t.push(`| ${n.columns.map(e=>e.items?.[r]??``).join(` | `)} |`)}break}case`status-board`:{let n=e.value;if(n?.items)for(let e of n.items){let n=e.status===`success`?`🟢`:e.status===`warning`?`🟡`:e.status===`error`?`🔴`:e.status===`info`?`🔵`:`⚪`;t.push(`${n} **${e.label}**${e.detail?` — ${e.detail}`:``}`)}break}case`prompt`:{let n=e.value;n?.question&&(t.push(`> **${n.question}**`),n.context&&t.push(`> ${n.context}`));break}case`progress`:{let n=e.value;if(n?.items)for(let e of n.items){let n=e.max??100,r=n>0?Math.round(e.value/n*100):0,i=`█`.repeat(Math.round(r/5))+`░`.repeat(20-Math.round(r/5));t.push(`${e.label}: ${i} ${r}%`)}break}case`text`:t.push(String(e.value??``));break;case`heading`:t.push(`## ${String(e.value??``)}\n`);break;case`separator`:t.push(`---
-`);break;default:t.push(JSON.stringify(e.value,null,2))}return t.push(``),t.join(`
-`)}function I(e){if(e.length===0)return`*(empty table)*`;let t=Object.keys(e[0]),n=[];n.push(`| ${t.join(` | `)} |`),n.push(`| ${t.map(()=>`---`).join(` | `)} |`);for(let r of e)n.push(`| ${t.map(e=>String(r[e]??``)).join(` | `)} |`);return n.join(`
-`)}function L(e){return e.map(e=>`- **${e.label}**: ${e.value}`).join(`
-`)}function R(e){let t=["```mermaid",`graph LR`];for(let n of e.nodes){let e=X(String(n.id??n.name??``)),r=String(n.label??n.name??e);t.push(`  ${e}["${r}"]`)}for(let n of e.edges){let e=X(String(n.source??n.from??``)),r=X(String(n.target??n.to??``)),i=n.label?`|${String(n.label)}|`:``;t.push(`  ${e} -->${i} ${r}`)}return t.push("```"),t.join(`
-`)}function z(e,t=0){let n=`  `.repeat(t),r=[];for(let[i,a]of Object.entries(e))typeof a==`object`&&a&&!Array.isArray(a)?(r.push(`${n}- **${i}**:`),r.push(z(a,t+1))):r.push(`${n}- **${i}**: ${Y(a)}`);return r.join(`
-`)}function B(e,n){let r=[];if(e&&r.push(`<h1>${t(e)}</h1>`),typeof n==`string`)r.push(`<div class="md-content">${S.parse(n)}</div>`);else if(Array.isArray(n))if(n.length===0)r.push(`<p><em>empty</em></p>`);else if(Z(n[0]))for(let e of n)r.push(V(e));else typeof n[0]==`object`&&n[0]!==null?r.push(H(n)):r.push(`<ul>${n.map(e=>`<li>${t(String(e))}</li>`).join(``)}</ul>`);else if(typeof n==`object`&&n){let e=n;Array.isArray(e.metrics)?r.push(U(e.metrics)):Array.isArray(e.nodes)&&Array.isArray(e.edges)?(r.push(`<pre class="mermaid">${t(K(e))}</pre>`),r.push(`<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"><\/script>`),r.push(`<script>mermaid.run();<\/script>`)):r.push(G(e))}else r.push(`<p>${t(String(n))}</p>`);return r.join(`
-`)}function V(e){let l=[];switch(e.title&&l.push(`<h2>${t(e.title)}</h2>`),e.type){case`markdown`:l.push(`<div class="md-content">${S.parse(String(e.value??``))}</div>`);break;case`code`:l.push(`<pre><code>${t(String(e.value??``))}</code></pre>`);break;case`mermaid`:l.push(`<pre class="mermaid">${t(String(e.value??``))}</pre>`);break;case`table`:if(Array.isArray(e.value)){let t=e.value;if(t.length>0&&Array.isArray(t[0])){let e=t,n=e[0].map(String),r=e.slice(1).map(e=>Object.fromEntries(n.map((t,n)=>[t,e[n]])));l.push(H(r))}else l.push(H(t))}break;case`metrics`:{let t;Array.isArray(e.value)?t=e.value:e.value&&typeof e.value==`object`&&(t=Object.entries(e.value).map(([e,t])=>({label:e,value:String(t)}))),t&&l.push(U(t))}break;case`cards`:Array.isArray(e.value)&&l.push(W(e.value));break;case`tree`:e.value&&typeof e.value==`object`&&l.push(G(e.value));break;case`graph`:e.value&&typeof e.value==`object`&&l.push(`<pre class="mermaid">${t(K(e.value))}</pre>`);break;case`chart`:{let t=e.value;if(t&&!t.chartType&&t.type&&Array.isArray(t.labels)&&Array.isArray(t.datasets)){let n=t.labels,r=t.datasets,i=r.map((e,t)=>e.label??`series${t+1}`),a=n.map((e,t)=>{let n={_label:e};return r.forEach((e,r)=>{n[i[r]]=e.data[t]??0}),n}),o={type:`chart`,title:e.title,value:{chartType:String(t.type),data:a,xKey:`_label`,yKeys:i}};l.push(c(o))}else l.push(c(e));break}case`timeline`:{let t=e.value;Array.isArray(t)&&(t={items:t.map(e=>({title:String(e.event??e.title??``),phase:e.date==null?e.phase==null?void 0:String(e.phase):String(e.date),description:e.description==null?void 0:String(e.description),status:e.status??`done`}))}),t&&l.push(s(t));break}case`checklist`:e.value&&l.push(n(e.value));break;case`comparison`:e.value&&l.push(r(e.value));break;case`status-board`:e.value&&l.push(o(e.value));break;case`prompt`:e.value&&l.push(a(e.value));break;case`progress`:e.value&&l.push(i(e.value));break;case`text`:l.push(`<div class="md-content">${S.parse(String(e.value??``))}</div>`);break;case`heading`:l.push(`<h2>${t(String(e.value??``))}</h2>`);break;case`separator`:l.push(`<hr class="separator">`);break;default:l.push(`<pre>${t(JSON.stringify(e.value,null,2))}</pre>`)}return l.join(`
-`)}function H(e){if(e.length===0)return`<p><em>empty table</em></p>`;let n=Object.keys(e[0]);return`<div class="table-wrap"><table><thead><tr>${n.map(e=>`<th>${t(e)}</th>`).join(``)}</tr></thead><tbody>${e.map(e=>`<tr>${n.map(n=>`<td>${t(String(e[n]??``))}</td>`).join(``)}</tr>`).join(`
-`)}</tbody></table></div>`}function U(e){return`<div class="metric-grid">${e.map(e=>`<div class="metric"><div class="metric-value">${t(String(e.value))}</div><div class="metric-label">${t(e.label)}</div></div>`).join(``)}</div>`}function W(e){return`<div class="card-grid">${e.map(e=>{let n=[`<div class="card">`];return e.title&&n.push(`<div class="card-title">${t(String(e.title))}</div>`),(e.body||e.description)&&n.push(`<div class="card-body">${t(String(e.body??e.description))}</div>`),(e.badge||e.status)&&n.push(`<span class="badge">${t(String(e.badge??e.status))}</span>`),n.push(`</div>`),n.join(``)}).join(``)}</div>`}function G(e){let n=[];for(let[r,i]of Object.entries(e))typeof i==`object`&&i&&!Array.isArray(i)?n.push(`<div class="tree-node"><span class="tree-key">${t(r)}:</span><div class="tree-children">${G(i)}</div></div>`):n.push(`<div class="tree-node"><span class="tree-key">${t(r)}:</span> ${t(Y(i))}</div>`);return n.join(``)}function K(e){let t=[`graph LR`];for(let n of e.nodes){let e=X(String(n.id??n.name??``)),r=String(n.label??n.name??e);t.push(`  ${e}["${r}"]`)}for(let n of e.edges){let e=X(String(n.source??n.from??``)),r=X(String(n.target??n.to??``)),i=n.label?`|${String(n.label)}|`:``;t.push(`  ${e} -->${i} ${r}`)}return t.join(`
-`)}function q(e,n,r){let i=B(e,n);return`<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width,initial-scale=1.0">
-<title>${t(e??`KB Dashboard`)}</title>
-${l}
-<style>${u()}</style>
-</head>
-<body>
-<div class="dashboard">
-  <div class="header">
-    <h1>${t(e??`KB Dashboard`)}</h1>
-    <div class="subtitle">Knowledge Base</div>
-  </div>
-  ${i}
-  ${(()=>{let e=Array.isArray(r)?r:[];return e.length===0?``:`
-  <div class="actions-bar">
-    <h2>Actions</h2>
-    <div class="actions-grid">${e.map(e=>{let n=String(e.id??``);if(e.type===`select`&&Array.isArray(e.options)){let r=e.options.map(e=>{let n=typeof e==`string`?e:e.label;return`<option value="${t(typeof e==`string`?e:e.value)}">${t(n)}</option>`}).join(``);return`<div class="action-group"><label>${t(String(e.label??``))}</label><select data-action-id="${t(n)}" onchange="sendCallback(${t(JSON.stringify(n))},this.value)">${r}</select></div>`}return`<button class="action-btn action-${String(e.variant??`default`)}" onclick="sendCallback(${t(JSON.stringify(n))},'clicked')">${t(String(e.label??``))}</button>`}).join(`
-`)}</div>
-    <div id="action-feedback" class="action-feedback"></div>
-  </div>
-  <script>
-  let _cbSent=false;
-  function sendCallback(actionId,value){
-    if(_cbSent)return;
-    _cbSent=true;
-    document.querySelectorAll('.action-btn,.action-group select').forEach(el=>{el.disabled=true;el.style.opacity='0.5'});
-    const fb=document.getElementById('action-feedback');
-    fb.textContent='⏳ Sending selection: '+actionId+' = '+value;
-    fb.className='action-feedback sent';
-    fetch('/callback',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({actionId,value})})
-      .then(()=>{
-        fb.textContent='✓ Selection sent: '+actionId+' = '+value;
-      })
-      .catch(e=>{
-        fb.textContent='✗ Callback failed — '+e.message;
-        fb.style.color='var(--error)';
-        _cbSent=false;
-        document.querySelectorAll('.action-btn,.action-group select').forEach(el=>{el.disabled=false;el.style.opacity='1'});
-      });
-  }
-  <\/script>`})()}
-  <div class="footer">KB MCP Server &middot; Generated ${new Date().toLocaleString()}</div>
-</div>
-<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"><\/script>
-<script>
-// Mermaid initialization
-if(document.querySelector('.mermaid'))mermaid.initialize({theme:'dark',startOnLoad:true});
-
-// Table sorting
-document.querySelectorAll('table').forEach(table=>{
-  const headers=table.querySelectorAll('th');
-  headers.forEach((th,i)=>{
-    let asc=true;
-    th.addEventListener('click',()=>{
-      const tbody=table.querySelector('tbody')||table;
-      const rows=[...tbody.querySelectorAll('tr')].filter(r=>r.querySelector('td'));
-      rows.sort((a,b)=>{
-        const at=(a.cells[i]?.textContent||'').trim();
-        const bt=(b.cells[i]?.textContent||'').trim();
-        return asc?at.localeCompare(bt,undefined,{numeric:true}):bt.localeCompare(at,undefined,{numeric:true});
-      });
-      rows.forEach(r=>tbody.appendChild(r));
-      asc=!asc;
-      headers.forEach(h=>h.style.color='');
-      th.style.color='var(--primary)';
-    });
-  });
-});
-
-// Table search/filter
-document.querySelectorAll('.table-wrap').forEach(wrap=>{
-  const table=wrap.querySelector('table');
-  if(!table||table.querySelectorAll('tr').length<5)return;
-  const bar=document.createElement('div');
-  bar.className='search-bar';
-  const input=document.createElement('input');
-  input.placeholder='Filter rows...';
-  const count=document.createElement('span');
-  count.className='count';
-  bar.appendChild(input);bar.appendChild(count);
-  wrap.parentNode.insertBefore(bar,wrap);
-  const rows=[...table.querySelectorAll('tbody tr, tr')].filter(r=>r.querySelector('td'));
-  const updateCount=()=>{const v=rows.filter(r=>r.style.display!=='none').length;count.textContent=v+'/'+rows.length};
-  updateCount();
-  input.addEventListener('input',()=>{
-    const q=input.value.toLowerCase();
-    rows.forEach(r=>{r.style.display=r.textContent.toLowerCase().includes(q)?'':'none'});
-    updateCount();
-  });
-});
-<\/script>
-</body>
-</html>`}function J(e,t,n){let r=Array.isArray(n)?n:[],i=[];if(e&&i.push(`## ${e}\n`),Array.isArray(t)){for(let e of t)if(e&&typeof e==`object`&&typeof e.type==`string`)if(e.type===`metrics`&&e.value&&typeof e.value==`object`){let t=e.value;i.push(Object.entries(t).map(([e,t])=>`**${e}**: ${String(t)}`).join(`  ·  `))}else e.type===`text`&&typeof e.value==`string`?i.push(e.value):i.push(`*${e.type}${e.title?`: ${String(e.title)}`:``}*`)}else typeof t==`string`&&i.push(t);if(r.length>0){i.push(``);for(let e=0;e<r.length;e++){let t=r[e],n=typeof t.label==`string`?t.label:`Action ${e+1}`;if(t.type===`select`&&Array.isArray(t.options)){let r=t.options.map(e=>typeof e==`string`?e:e.label).join(`, `);i.push(`${e+1}. **${n}** — choose: ${r}`)}else i.push(`${e+1}. **${n}**`)}}let a={title:e,content:t};return r.length>0&&(a.actions=r),{content:[{type:`text`,text:i.join(`
-`)}],structuredContent:a}}function Y(e){return e==null?`null`:Array.isArray(e)?`[${e.map(Y).join(`, `)}]`:String(e)}function X(e){return e.replace(/[^a-zA-Z0-9_]/g,`_`)}function Z(e){return typeof e==`object`&&!!e&&`type`in e&&`value`in e}export{j as registerPresentTool};
+import{registerPresentTool as e}from"./present/tool.js";import"./present/index.js";export{e as registerPresentTool};

package/packages/tools/dist/compact.js

@@ -1,3 +1,3 @@
-import{bookendReorder as e,cosineSimilarity as t,segment as n}from"./text-utils.js";import{readFile as r,stat as i}from"node:fs/promises";async function a(a,o){let{query:s,maxChars:c=3e3,minScore:l=.3,segmentation:u=`paragraph`}=o,d=o.tokenBudget?o.tokenBudget*4:c,f;if(o.text)f=o.text;else if(o.path){let e;try{e=await i(o.path)}catch(e){let t=e.code;throw t===`ENOENT`?Error(`File not found: ${o.path}. Check the path and try again.`):t===`EACCES`||t===`EPERM`?Error(`Permission denied reading ${o.path}. The file exists but is not accessible.`):e}if(e.size>1e7)throw Error(`File too large (${(e.size/1e6).toFixed(1)}MB). compact supports files up to 10MB. Consider splitting or using search instead.`);f=o.cache?(await o.cache.get(o.path)).content:await r(o.path,`utf-8`)}else throw Error(`Either "text" or "path" must be provided`);if(f.length<=d)return{text:f,originalChars:f.length,compressedChars:f.length,ratio:1,segmentsKept:1,segmentsTotal:1};let p=n(f,u);if(p.length===0)return{text:``,originalChars:f.length,compressedChars:0,ratio:0,segmentsKept:0,segmentsTotal:0};let m=await a.embed(s),h=[];for(let e=0;e<p.length;e++){let n=t(m,await a.embed(p[e]));h.push({text:p[e],score:n,index:e})}let g=h.filter(e=>e.score>=l).sort((e,t)=>t.score-e.score),_=[],v=0;for(let e of g){if(v+e.text.length>d){v===0&&(_.push({...e,text:e.text.slice(0,d)}),v=d);break}_.push(e),v+=e.text.length+2}let y=e(_.sort((e,t)=>t.score-e.score)).map(e=>e.text).join(`
+import{bookendReorder as e,cosineSimilarity as t,segment as n}from"./text-utils.js";import{readFile as r,stat as i}from"node:fs/promises";async function a(a,o){let{query:s,maxChars:c=3e3,minScore:l=.3,segmentation:u=`paragraph`}=o,d=o.tokenBudget?o.tokenBudget*4:c,f;if(o.text)f=o.text;else if(o.path){let e;try{e=await i(o.path)}catch(e){let t=e.code;throw t===`ENOENT`?Error(`File not found: ${o.path}. Check the path and try again.`):t===`EACCES`||t===`EPERM`?Error(`Permission denied reading ${o.path}. The file exists but is not accessible.`):e}if(e.isDirectory())throw Error(`Path is a directory: ${o.path}. compact requires a file path, not a directory. Use analyze_structure or find to explore directories.`);if(e.size>1e7)throw Error(`File too large (${(e.size/1e6).toFixed(1)}MB). compact supports files up to 10MB. Consider splitting or using search instead.`);f=o.cache?(await o.cache.get(o.path)).content:await r(o.path,`utf-8`)}else throw Error(`Either "text" or "path" must be provided`);if(f.length<=d)return{text:f,originalChars:f.length,compressedChars:f.length,ratio:1,segmentsKept:1,segmentsTotal:1};let p=n(f,u);if(p.length===0)return{text:``,originalChars:f.length,compressedChars:0,ratio:0,segmentsKept:0,segmentsTotal:0};let m=await a.embed(s),h=[];for(let e=0;e<p.length;e++){let n=t(m,await a.embed(p[e]));h.push({text:p[e],score:n,index:e})}let g=h.filter(e=>e.score>=l).sort((e,t)=>t.score-e.score),_=[],v=0;for(let e of g){if(v+e.text.length>d){v===0&&(_.push({...e,text:e.text.slice(0,d)}),v=d);break}_.push(e),v+=e.text.length+2}let y=e(_.sort((e,t)=>t.score-e.score)).map(e=>e.text).join(`
 
 `);return{text:y,originalChars:f.length,compressedChars:y.length,ratio:y.length/f.length,segmentsKept:_.length,segmentsTotal:p.length}}export{a as compact};

package/packages/tools/dist/file-cache.js

@@ -1,3 +1,3 @@
-import{estimateTokens as e}from"./text-utils.js";import{readFile as t,stat as n}from"node:fs/promises";import{resolve as r}from"node:path";import{createHash as i}from"node:crypto";var a=class i{cache=new Map;totalReads=0;cacheHits=0;static MAX_ENTRIES=500;async get(a){let s=r(a);this.totalReads++;let c=(await n(s)).mtimeMs,l=this.cache.get(s);if(l){if(l.mtimeMs===c)return this.cacheHits++,l.hitCount++,{content:l.content,hash:l.hash,lines:l.lines,estimatedTokens:l.estimatedTokens,hitCount:l.hitCount,changed:!1};let n=await t(s,`utf-8`),r=o(n);if(r===l.hash)return this.cacheHits++,l.hitCount++,l.mtimeMs=c,{content:l.content,hash:l.hash,lines:l.lines,estimatedTokens:l.estimatedTokens,hitCount:l.hitCount,changed:!1};let i=n.split(`
-`).length,a=e(n);return l.content=n,l.hash=r,l.lines=i,l.estimatedTokens=a,l.hitCount++,l.mtimeMs=c,{content:n,hash:r,lines:i,estimatedTokens:a,hitCount:l.hitCount,changed:!0}}let u=await t(s,`utf-8`),d=o(u),f=u.split(`
-`).length,p=e(u);if(this.cache.set(s,{content:u,hash:d,lines:f,estimatedTokens:p,hitCount:1,mtimeMs:c}),this.cache.size>i.MAX_ENTRIES){let e=this.cache.keys().next().value;e&&this.cache.delete(e)}return{content:u,hash:d,lines:f,estimatedTokens:p,hitCount:1,changed:!0}}invalidate(e){return this.cache.delete(r(e))}clear(){let e=this.cache.size;return this.cache.clear(),e}stats(){return{totalReads:this.totalReads,cacheHits:this.cacheHits,filesTracked:this.cache.size}}};function o(e){return i(`sha256`).update(e).digest(`hex`)}export{a as FileCache};
+import{estimateTokens as e}from"./text-utils.js";import{readFile as t,stat as n}from"node:fs/promises";import{resolve as r}from"node:path";import{createHash as i}from"node:crypto";var a=class i{cache=new Map;totalReads=0;cacheHits=0;static MAX_ENTRIES=500;async get(a){let s=r(a);this.totalReads++;let c=await n(s);if(c.isDirectory())throw Error(`Path is a directory: ${a}. Expected a file path, not a directory. Use analyze_structure or find to explore directories.`);let l=c.mtimeMs,u=this.cache.get(s);if(u){if(u.mtimeMs===l)return this.cacheHits++,u.hitCount++,{content:u.content,hash:u.hash,lines:u.lines,estimatedTokens:u.estimatedTokens,hitCount:u.hitCount,changed:!1};let n=await t(s,`utf-8`),r=o(n);if(r===u.hash)return this.cacheHits++,u.hitCount++,u.mtimeMs=l,{content:u.content,hash:u.hash,lines:u.lines,estimatedTokens:u.estimatedTokens,hitCount:u.hitCount,changed:!1};let i=n.split(`
+`).length,a=e(n);return u.content=n,u.hash=r,u.lines=i,u.estimatedTokens=a,u.hitCount++,u.mtimeMs=l,{content:n,hash:r,lines:i,estimatedTokens:a,hitCount:u.hitCount,changed:!0}}let d=await t(s,`utf-8`),f=o(d),p=d.split(`
+`).length,m=e(d);if(this.cache.set(s,{content:d,hash:f,lines:p,estimatedTokens:m,hitCount:1,mtimeMs:l}),this.cache.size>i.MAX_ENTRIES){let e=this.cache.keys().next().value;e&&this.cache.delete(e)}return{content:d,hash:f,lines:p,estimatedTokens:m,hitCount:1,changed:!0}}invalidate(e){return this.cache.delete(r(e))}clear(){let e=this.cache.size;return this.cache.clear(),e}stats(){return{totalReads:this.totalReads,cacheHits:this.cacheHits,filesTracked:this.cache.size}}};function o(e){return i(`sha256`).update(e).digest(`hex`)}export{a as FileCache};

package/packages/tools/dist/file-summary.js

@@ -1,2 +1,2 @@
-import{readFile as e,stat as t}from"node:fs/promises";import{extname as n}from"node:path";import{SUPPORTED_EXTENSIONS as r,WasmRuntime as i,extractCalls as a,extractImports as o,extractSymbols as s}from"../../chunker/dist/index.js";async function c(a){let{path:o,previewLines:s=3}=a;if(!a.content){let e;try{e=await t(o)}catch(e){let t=e.code;throw t===`ENOENT`?Error(`File not found: ${o}. Check the path and try again.`):t===`EACCES`||t===`EPERM`?Error(`Permission denied reading ${o}. The file exists but is not accessible.`):e}if(e.size>1e7)throw Error(`File too large (${(e.size/1e6).toFixed(1)}MB). file_summary supports files up to 10MB. Use search or compact with a query instead.`)}let c=a.content??await e(o,`utf-8`),d=c.split(`
+import{readFile as e,stat as t}from"node:fs/promises";import{extname as n}from"node:path";import{SUPPORTED_EXTENSIONS as r,WasmRuntime as i,extractCalls as a,extractImports as o,extractSymbols as s}from"../../chunker/dist/index.js";async function c(a){let{path:o,previewLines:s=3}=a;if(!a.content){let e;try{e=await t(o)}catch(e){let t=e.code;throw t===`ENOENT`?Error(`File not found: ${o}. Check the path and try again.`):t===`EACCES`||t===`EPERM`?Error(`Permission denied reading ${o}. The file exists but is not accessible.`):e}if(e.isDirectory())throw Error(`Path is a directory: ${o}. file_summary requires a file path, not a directory. Use analyze_structure or find to explore directories.`);if(e.size>1e7)throw Error(`File too large (${(e.size/1e6).toFixed(1)}MB). file_summary supports files up to 10MB. Use search or compact with a query instead.`)}let c=a.content??await e(o,`utf-8`),d=c.split(`
 `),f=o.split(`.`).pop()??``,p=n(o);return i.get()&&r.has(p)?l(o,c,d,f,p):u(o,c,d,f)}async function l(e,t,n,r,i){let[c,l,u]=await Promise.all([s(t,i,e),o(t,i,e),a(t,i,e).catch(()=>[])]),f=l.map(e=>`import ${e.specifiers.length>0?`{ ${e.specifiers.join(`, `)} }`:`*`} from '${e.source}'`),p=[],m=[],h=[],g=[],_=[];for(let e of c)switch(e.exported&&p.push(e.name),e.kind){case`function`:case`method`:m.push({name:e.name,line:e.line,exported:e.exported,signature:e.signature});break;case`class`:h.push({name:e.name,line:e.line,exported:e.exported,signature:e.signature});break;case`interface`:g.push({name:e.name,line:e.line,exported:e.exported});break;case`type`:_.push({name:e.name,line:e.line,exported:e.exported});break}let v=l.map(e=>({source:e.source,specifiers:e.specifiers,isExternal:e.isExternal})),y=u.map(e=>({caller:e.callerName,callee:e.calleeName,line:e.line}));return{path:e,lines:n.length,language:d(r),imports:f,exports:p,functions:m,classes:h,interfaces:g,types:_,importDetails:v,callEdges:y.length>0?y:void 0,estimatedTokens:Math.ceil(t.length/4)}}function u(e,t,n,r){let i=[],a=[],o=[],s=[],c=[],l=[];for(let e=0;e<n.length;e+=1){let t=n[e],r=e+1;if(/^import\s+.+/.test(t)){i.push(t.trim());continue}let u=t.match(/^export\s+(?:async\s+)?function\s+(\w+)/);if(u){o.push({name:u[1],line:r,exported:!0}),a.push(u[1]);continue}let d=t.match(/^(?:async\s+)?function\s+(\w+)/);if(d){o.push({name:d[1],line:r,exported:!1});continue}let f=t.match(/^(export\s+)?const\s+(\w+)\s*=.*(?:=>|\bfunction\b)/);if(f){let e=!!f[1];o.push({name:f[2],line:r,exported:e}),e&&a.push(f[2]);continue}let p=t.match(/^export\s+const\s+(\w+)\s*=/);if(p){a.push(p[1]);continue}let m=t.match(/^(export\s+)?(?:abstract\s+)?class\s+(\w+)/);if(m){let e=!!m[1];s.push({name:m[2],line:r,exported:e}),e&&a.push(m[2]);continue}let h=t.match(/^(export\s+)?interface\s+(\w+)/);if(h){let e=!!h[1];c.push({name:h[2],line:r,exported:e}),e&&a.push(h[2]);continue}let g=t.match(/^(export\s+)?type\s+(\w+)/);if(g){let e=!!g[1];l.push({name:g[2],line:r,exported:e}),e&&a.push(g[2]);continue}let _=t.match(/^export\s+\{(.+)\}/);if(_){let e=_[1].split(`,`).map(e=>e.trim().split(/\s+as\s+/).pop()?.trim()??``).filter(Boolean);a.push(...e)}}return{path:e,lines:n.length,language:d(r),imports:i,exports:a,functions:o,classes:s,interfaces:c,types:l,estimatedTokens:Math.ceil(t.length/4)}}function d(e){return{ts:`typescript`,tsx:`typescript-jsx`,js:`javascript`,jsx:`javascript-jsx`,py:`python`,rs:`rust`,go:`go`,java:`java`,rb:`ruby`,md:`markdown`,json:`json`,yaml:`yaml`,yml:`yaml`,css:`css`,html:`html`,sh:`shell`,bash:`shell`}[e]??e}export{c as fileSummary};

package/packages/tools/dist/onboard.d.ts

@@ -34,6 +34,13 @@ interface OnboardResult {
   outDir?: string;
   /** Total duration in ms */
   totalDurationMs: number;
+  /** Auto-generated knowledge entries for curated store persistence */
+  autoRemember?: Array<{
+    title: string;
+    content: string;
+    category: string;
+    tags: string[];
+  }>;
 }
 /**
  * Run all onboarding analyses in parallel and return combined results.

package/packages/tools/dist/onboard.js

@@ -1,4 +1,4 @@
-import{extractConfigValues as e}from"./config-extractor.js";import{buildDiagrams as t}from"./diagram-builder.js";import{buildCodeMap as n,buildSynthesisGuide as r}from"./synthesis-engine.js";import{DependencyAnalyzer as i,DiagramGenerator as a,EntryPointAnalyzer as o,PatternAnalyzer as s,StructureAnalyzer as c,SymbolAnalyzer as l,extractRegexCallGraph as u,extractTsCallGraph as d}from"../../analyzers/dist/index.js";import{basename as f,join as p,resolve as m}from"node:path";import{existsSync as h,mkdirSync as g,readdirSync as _,rmSync as v,writeFileSync as y}from"node:fs";import{KB_PATHS as b}from"../../core/dist/index.js";const x={structure:`Project Structure`,dependencies:`Dependencies`,"entry-points":`Entry Points`,symbols:`Symbols`,patterns:`Patterns`,diagram:`C4 Container Diagram`,"code-map":`Code Map (Module Graph)`,"config-values":`Configuration Values`,"synthesis-guide":`Synthesis Guide`,"api-surface":`API Surface`,"type-inventory":`Type Inventory`};function S(e){let t=e.get(`symbols`);if(!t?.symbols?.length)return`# API Surface
+import{extractConfigValues as e}from"./config-extractor.js";import{buildDiagrams as t}from"./diagram-builder.js";import{buildCodeMap as n,buildSynthesisGuide as r}from"./synthesis-engine.js";import{DependencyAnalyzer as i,DiagramGenerator as a,EntryPointAnalyzer as o,PatternAnalyzer as ee,StructureAnalyzer as s,SymbolAnalyzer as c,extractRegexCallGraph as l,extractTsCallGraph as u}from"../../analyzers/dist/index.js";import{basename as d,join as f,resolve as p}from"node:path";import{existsSync as m,mkdirSync as h,readdirSync as g,rmSync as _,writeFileSync as v}from"node:fs";import{KB_PATHS as y}from"../../core/dist/index.js";const b={structure:`Project Structure`,dependencies:`Dependencies`,"entry-points":`Entry Points`,symbols:`Symbols`,patterns:`Patterns`,diagram:`C4 Container Diagram`,"code-map":`Code Map (Module Graph)`,"config-values":`Configuration Values`,"synthesis-guide":`Synthesis Guide`,"api-surface":`API Surface`,"type-inventory":`Type Inventory`};function x(e){let t=e.get(`symbols`);if(!t?.symbols?.length)return`# API Surface
 
 *No symbol data available.*
 `;let n=t.symbols.filter(e=>e.exported);if(n.length===0)return`# API Surface
@@ -6,7 +6,7 @@ import{extractConfigValues as e}from"./config-extractor.js";import{buildDiagrams
 *No exported symbols found.*
 `;let r=new Map;for(let e of n){let t=r.get(e.filePath)??[];t.push(e),r.set(e.filePath,t)}let i=[`# API Surface
 `];for(let[e,t]of[...r.entries()].sort(([e],[t])=>e.localeCompare(t))){i.push(`## ${e}\n`);for(let e of t){e.decorators?.length&&i.push(e.decorators.join(` `));let t=e.signature??``,n=e.returnType?`: ${e.returnType}`:``;if(e.kind===`function`||e.kind===`method`)i.push(`### \`${e.name}${t}${n}\``);else if(e.kind===`class`)i.push(`### class \`${e.name}\`${t?` ${t}`:``}`);else if(e.kind===`interface`||e.kind===`type`){let t=e.typeBody?` ${e.typeBody}`:``;i.push(`### ${e.kind} \`${e.name}\`${t}`)}else i.push(`### ${e.kind} \`${e.name}\`${t?`: ${t}`:``}`);e.jsdoc&&i.push(`> ${e.jsdoc}`),i.push(``)}}let a=i.join(`
-`);return a.length>1e5?`${a.slice(0,1e5)}\n\n*[truncated]*`:a}function C(e){let t=e.get(`symbols`);if(!t?.symbols?.length)return`# Type Inventory
+`);return a.length>1e5?`${a.slice(0,1e5)}\n\n*[truncated]*`:a}function S(e){let t=e.get(`symbols`);if(!t?.symbols?.length)return`# Type Inventory
 
 *No symbol data available.*
 `;let n=t.symbols.filter(e=>e.exported&&(e.kind===`interface`||e.kind===`type`||e.kind===`enum`));if(n.length===0)return`# Type Inventory
@@ -14,5 +14,5 @@ import{extractConfigValues as e}from"./config-extractor.js";import{buildDiagrams
 *No exported types/interfaces found.*
 `;let r=new Map;for(let e of n){let t=r.get(e.filePath)??[];t.push(e),r.set(e.filePath,t)}let i=[`# Type Inventory
 `];for(let[e,t]of[...r.entries()].sort(([e],[t])=>e.localeCompare(t))){i.push(`## ${e}\n`);for(let e of t){let t=e.typeBody??`*body not available*`;e.jsdoc&&i.push(`> ${e.jsdoc}`),i.push(`### ${e.kind} \`${e.name}\``),i.push("```"),i.push(t),i.push("```\n")}}let a=i.join(`
-`);return a.length>1e5?`${a.slice(0,1e5)}\n\n*[truncated]*`:a}async function w(w){let T=Date.now(),E=m(w.path),D=f(E),O=w.mode??`generate`,k=w.outDir??p(E,b.aiKb),A=new c,j=new i,M=new l,N=new s,P=new o,F=new a,I=[{name:`structure`,fn:()=>A.analyze(E,{format:`markdown`,maxDepth:3,sourceOnly:!0})},{name:`dependencies`,fn:()=>j.analyze(E,{format:`markdown`})},{name:`entry-points`,fn:()=>P.analyze(E)},{name:`symbols`,fn:()=>M.analyze(E,{format:`markdown`})},{name:`patterns`,fn:()=>N.analyze(E)},{name:`diagram`,fn:()=>F.analyze(E,{diagramType:`architecture`})}],L=await Promise.allSettled(I.map(async e=>{let t=Date.now(),n=await e.fn();return{name:e.name,result:n,durationMs:Date.now()-t}})),R=[],z=new Map,B=new Map;for(let e of L)if(e.status===`fulfilled`){let{name:t,result:n,durationMs:r}=e.value,i=n;R.push({name:t,status:`success`,output:i.output,durationMs:r}),z.set(t,i.output),B.set(t,i.data)}else{let t=e.reason,n=I[L.indexOf(e)].name;R.push({name:n,status:`failed`,output:``,durationMs:0,error:t.message})}let V=Date.now(),H=null;try{let e=await d(E);if((!e||e.edges.length===0)&&(e=await u(E)),e&&e.edges.length>0){H=new Map;for(let t of e.edges){let e=H.get(t.from);e||(e=new Map,H.set(t.from,e));let n=e.get(t.to);if(n)for(let e of t.symbols)n.includes(e)||n.push(e);else e.set(t.to,[...t.symbols])}}}catch{}let U=Date.now()-V,W=Date.now(),G=n(B,D,H),K=Date.now()-W+U;if(R.push({name:`code-map`,status:`success`,output:G,durationMs:K}),z.set(`code-map`,G),H&&H.size>0){let e=t(H,B,D),n=R.find(e=>e.name===`diagram`);n&&(n.output=e,z.set(`diagram`,e))}let q=Date.now(),J=await e(E,D),Y=Date.now()-q;R.push({name:`config-values`,status:`success`,output:J,durationMs:Y}),z.set(`config-values`,J);let X=r(R,O,D,B);R.push({name:`synthesis-guide`,status:`success`,output:X,durationMs:0}),z.set(`synthesis-guide`,X);let Z=S(B);R.push({name:`api-surface`,status:`success`,output:Z,durationMs:0}),z.set(`api-surface`,Z);let Q=C(B);if(R.push({name:`type-inventory`,status:`success`,output:Q,durationMs:0}),z.set(`type-inventory`,Q),O===`generate`){if(h(k))for(let e of _(k))(e.endsWith(`.md`)||e.endsWith(`.json`))&&v(p(k,e),{force:!0});g(k,{recursive:!0});let e=new Date().toISOString();for(let[t,n]of z){let r=p(k,`${t}.md`),i=n.replaceAll(E,D);y(r,`<!-- Generated: ${e} -->\n<!-- Project: ${D} -->\n<!-- Source: ${E} -->\n\n`+i,`utf-8`)}let t=[`<!-- Generated: ${e} -->`,`<!-- Project: ${D} -->`,`<!-- Source: ${E} -->`,``,`# ${D} — Codebase Knowledge`,``,`## Contents`,``];for(let e of R){let n=`${e.name}.md`,r=x[e.name]??e.name,i=e.status===`success`?`✓`:`✗`,a=e.durationMs>0?` (${e.durationMs}ms)`:``;t.push(`- ${i} [${r}](./${n})${a}`)}t.push(``),y(p(k,`README.md`),t.join(`
-`),`utf-8`)}return{path:E,mode:O,steps:R,outDir:O===`generate`?k:void 0,totalDurationMs:Date.now()-T}}export{w as onboard};
+`);return a.length>1e5?`${a.slice(0,1e5)}\n\n*[truncated]*`:a}async function C(C){let w=Date.now(),T=p(C.path),E=d(T),D=C.mode??`generate`,O=C.outDir??f(T,y.aiKb),k=new s,A=new i,j=new c,M=new ee,N=new o,P=new a,F=[{name:`structure`,fn:()=>k.analyze(T,{format:`markdown`,maxDepth:3,sourceOnly:!0})},{name:`dependencies`,fn:()=>A.analyze(T,{format:`markdown`})},{name:`entry-points`,fn:()=>N.analyze(T)},{name:`symbols`,fn:()=>j.analyze(T,{format:`markdown`})},{name:`patterns`,fn:()=>M.analyze(T)},{name:`diagram`,fn:()=>P.analyze(T,{diagramType:`architecture`})}],I=await Promise.allSettled(F.map(async e=>{let t=Date.now(),n=await e.fn();return{name:e.name,result:n,durationMs:Date.now()-t}})),L=[],R=new Map,z=new Map;for(let e of I)if(e.status===`fulfilled`){let{name:t,result:n,durationMs:r}=e.value,i=n;L.push({name:t,status:`success`,output:i.output,durationMs:r}),R.set(t,i.output),z.set(t,i.data)}else{let t=e.reason,n=F[I.indexOf(e)].name;L.push({name:n,status:`failed`,output:``,durationMs:0,error:t.message})}let B=Date.now(),V=null;try{let e=await u(T);if((!e||e.edges.length===0)&&(e=await l(T)),e&&e.edges.length>0){V=new Map;for(let t of e.edges){let e=V.get(t.from);e||(e=new Map,V.set(t.from,e));let n=e.get(t.to);if(n)for(let e of t.symbols)n.includes(e)||n.push(e);else e.set(t.to,[...t.symbols])}}}catch{}let H=Date.now()-B,U=Date.now(),W=n(z,E,V),G=Date.now()-U+H;if(L.push({name:`code-map`,status:`success`,output:W,durationMs:G}),R.set(`code-map`,W),V&&V.size>0){let e=t(V,z,E),n=L.find(e=>e.name===`diagram`);n&&(n.output=e,R.set(`diagram`,e))}let K=Date.now(),q=await e(T,E),J=Date.now()-K;L.push({name:`config-values`,status:`success`,output:q,durationMs:J}),R.set(`config-values`,q);let Y=r(L,D,E,z);L.push({name:`synthesis-guide`,status:`success`,output:Y,durationMs:0}),R.set(`synthesis-guide`,Y);let X=x(z);L.push({name:`api-surface`,status:`success`,output:X,durationMs:0}),R.set(`api-surface`,X);let Z=S(z);if(L.push({name:`type-inventory`,status:`success`,output:Z,durationMs:0}),R.set(`type-inventory`,Z),D===`generate`){if(m(O))for(let e of g(O))(e.endsWith(`.md`)||e.endsWith(`.json`))&&_(f(O,e),{force:!0});h(O,{recursive:!0});let e=new Date().toISOString();for(let[t,n]of R){let r=f(O,`${t}.md`),i=n.replaceAll(T,E);v(r,`<!-- Generated: ${e} -->\n<!-- Project: ${E} -->\n<!-- Source: ${T} -->\n\n`+i,`utf-8`)}let t=[`<!-- Generated: ${e} -->`,`<!-- Project: ${E} -->`,`<!-- Source: ${T} -->`,``,`# ${E} — Codebase Knowledge`,``,`## Contents`,``];for(let e of L){let n=`${e.name}.md`,r=b[e.name]??e.name,i=e.status===`success`?`✓`:`✗`,a=e.durationMs>0?` (${e.durationMs}ms)`:``;t.push(`- ${i} [${r}](./${n})${a}`)}t.push(``),v(f(O,`README.md`),t.join(`
+`),`utf-8`)}let Q=[];Q.push({title:`Onboard: ${E} project overview`,content:Y.slice(0,2e3),category:`conventions`,tags:[`onboard`,`project-overview`,E]});let $=L.find(e=>e.name===`patterns`);return $?.status===`success`&&$.output&&Q.push({title:`Onboard: ${E} detected patterns`,content:$.output.slice(0,1500),category:`patterns`,tags:[`onboard`,`patterns`,E]}),q&&Q.push({title:`Onboard: ${E} config and commands`,content:q.slice(0,1500),category:`conventions`,tags:[`onboard`,`config`,`commands`,E]}),{path:T,mode:D,steps:L,outDir:D===`generate`?O:void 0,totalDurationMs:Date.now()-w,autoRemember:Q}}export{C as onboard};

package/skills/present/SKILL.md

@@ -1,36 +1,48 @@
 ---
 name: present
-description: "Use the KB `present` tool to display rich interactive dashboards, charts, timelines, status boards, and data visualizations in the browser or in-chat. Covers all block types, chart types, actions, and composition patterns. Load this skill before calling the present tool to ensure professional output."
-argument-hint: "Content to present — data, analysis results, status report, comparison"
+description: "Use the KB `present` tool to display rich interactive dashboards, charts, timelines, status boards, and data visualizations in the browser or in-chat. Covers all block types, chart types, actions, composition patterns, and MCP Apps templates (list-sort, data-table, picker, flame-graph, form, timeline, kanban, tree, diff-view, dashboard). Load this skill before calling the present tool to ensure professional output."
+argument-hint: "Content to present — data, analysis results, status report, comparison, or interactive MCP App"
 ---
 
 # Present Tool — Rich Interactive Dashboards
 
 The `present` tool renders structured content as a professional dark-themed dashboard. It supports two output modes:
 
-- **`browser`** (recommended) — Serves a themed dashboard on a local URL and returns it in the response. **You must open the URL** using the `openBrowserPage` browser tool to display it in VS Code's integrated browser. Supports interactive action buttons that block until the user clicks.
-- **`html`** — Renders an embedded UIResource for MCP-UI hosts. Actions shown as numbered text choices.
+- **`html`** — Renders an embedded UIResource for MCP-UI hosts (in-chat). Best for display-only content.
+- **`browser`** — Serves a themed dashboard on a local URL. Best when you need **user interaction** (buttons, selections, form input). The tool blocks until the user clicks an action, then returns their selection.
 
-**Always prefer `format: "browser"`** for rich content. Use `"html"` only when the host doesn't support browser mode.
+## Format Selection Rules (MUST FOLLOW)
+
+| Situation | Format | Why |
+|-----------|--------|-----|
+| Display-only content (tables, charts, reports, status boards) | **`html`** | No interaction needed — render in-chat |
+| Need user input back (confirmations, selections, form data) | **`browser`** | Browser supports blocking actions that return data |
+| Rich visual dashboards without interaction | **`html`** | Prefer in-chat when no response is needed |
+| User explicitly asks for browser | **`browser`** | Respect explicit preference |
+
+**Rule: If no user interaction is needed, use `format: "html"`. If you need user interaction, use `format: "browser"`.**
 
 ---
 
-## Browser Workflow (IMPORTANT)
+## Browser Workflow (IMPORTANT — read carefully)
 
-When using `format: "browser"`, the `present` tool does **not** open the page automatically. Follow this workflow:
+When using `format: "browser"`, the tool starts a local HTTP server and returns a URL. **You MUST open the URL** so the user can see and interact with the dashboard.
 
-1. Call `present` with `format: "browser"` — it returns text containing `🌐 **Dashboard opened in browser:** http://127.0.0.1:{port}`
-2. Extract the URL from the response
-3. Call `openBrowserPage` with that URL to display the dashboard in VS Code's integrated browser
+### Steps:
+1. Call `present` with `format: "browser"` and `actions` — it returns text containing `🌐 **Dashboard opened in browser:** http://127.0.0.1:{port}`
+2. **Extract the URL from the response**
+3. **Call `openBrowserPage({ url: "http://127.0.0.1:{port}" })` to open it in VS Code's Simple Browser**
 
 ```
 // Step 1: Call present
-result = present({ format: "browser", title: "...", content: [...] })
+result = present({ format: "browser", title: "...", content: [...], actions: [...] })
 
-// Step 2: Open in VS Code integrated browser
+// Step 2: MUST open in VS Code Simple Browser
 openBrowserPage({ url: "http://127.0.0.1:{port}" })
 ```
 
+> **Fallback**: The server also auto-opens the system browser as a safety net. But you should ALWAYS call `openBrowserPage` yourself so the user sees it inside VS Code.
+
 **Note:** The HTTP server auto-closes after 5 minutes. Open the page promptly after receiving the URL.
 
 ---
@@ -151,3 +163,262 @@ The dashboard uses a professional dark theme:
    - Use `donut` for proportions/distributions
    - Use `sparkline` inline with metrics for mini trends
 7. **Table auto-features:** Tables with 5+ rows get automatic search/filter. Columns are sortable by click.
+
+---
+
+## MCP Apps Templates (VS Code Chat Widgets)
+
+When `chat.mcp.apps.enabled` is true in VS Code settings, the `present` tool can render **interactive widgets directly in the chat panel** using the `template` parameter. These are distinct from the browser/html dashboard modes.
+
+**Key difference:** Templates use `template` + object `content` (not array of blocks). No `format` parameter needed. The widget renders inline in VS Code chat. User interactions (reorder, select, submit) are returned to the LLM as structured data.
+
+### When to use MCP Apps vs Browser Dashboard
+
+| Use Case | Mode | Why |
+|----------|------|-----|
+| Quick user input (pick items, reorder, fill form) | **MCP App template** | Inline in chat, no context switch |
+| Rich multi-section dashboard with charts | **browser** | Full page layout with all block types |
+| Simple confirmation or selection | **Actions** (browser/html) | Buttons/selects in dashboard |
+
+### Template: `list-sort`
+
+Drag-and-drop reorderable list. Use for priority ordering, task sequencing, or ranked preferences.
+
+```json
+{
+  "template": "list-sort",
+  "title": "Priority Order",
+  "content": {
+    "items": [
+      { "id": "task-1", "label": "Fix authentication bug" },
+      { "id": "task-2", "label": "Add search feature" },
+      { "id": "task-3", "label": "Update documentation" }
+    ]
+  }
+}
+```
+
+**Content schema:** `{ items: Array<{ id: string, label: string }> }`
+**Returns:** Reordered array of items after user drags to reorder and submits.
+
+### Template: `data-table`
+
+Filterable, sortable table with optional summary stat cards. Use for structured data review, change summaries, or audit results.
+
+```json
+{
+  "template": "data-table",
+  "title": "File Changes",
+  "content": {
+    "columns": [
+      { "key": "file", "label": "File" },
+      { "key": "change", "label": "Change" },
+      { "key": "lines", "label": "Lines" }
+    ],
+    "rows": [
+      { "file": "auth.ts", "change": "Added guard", "lines": 5 },
+      { "file": "cache.ts", "change": "Fixed bug", "lines": 12 }
+    ],
+    "stats": [
+      { "label": "Files Changed", "value": "2" },
+      { "label": "Total Lines", "value": "17" }
+    ]
+  }
+}
+```
+
+**Content schema:** `{ columns: Array<{ key: string, label: string }>, rows: Array<Record<string, unknown>>, stats?: Array<{ label: string, value: string }> }`
+**Returns:** Selected row(s) data when user interacts and submits.
+
+### Template: `picker`
+
+Multi-select with categories and tag-based search. Use for component selection, feature toggles, or module picking.
+
+```json
+{
+  "template": "picker",
+  "title": "Select Modules",
+  "content": {
+    "categories": [
+      { "id": "core", "label": "Core" },
+      { "id": "plugins", "label": "Plugins" }
+    ],
+    "items": [
+      { "id": "auth", "label": "Authentication", "category": "core", "tags": ["security"] },
+      { "id": "cache", "label": "Cache Layer", "category": "core", "tags": ["performance"] },
+      { "id": "sentry", "label": "Sentry Plugin", "category": "plugins", "tags": ["monitoring"] }
+    ]
+  }
+}
+```
+
+**Content schema:** `{ categories: Array<{ id: string, label: string }>, items: Array<{ id: string, label: string, category: string, tags?: string[] }> }`
+**Returns:** Array of selected item IDs after user checks items and submits.
+
+### Template: `flame-graph`
+
+Hierarchical zoomable visualization. Use for codebase structure, performance profiles, dependency trees, or budget breakdowns.
+
+```json
+{
+  "template": "flame-graph",
+  "title": "Module Hierarchy",
+  "content": {
+    "profile": {
+      "name": "root",
+      "total": 100,
+      "children": [
+        {
+          "name": "packages/tools",
+          "total": 60,
+          "children": [
+            { "name": "search.ts", "total": 35 },
+            { "name": "compact.ts", "total": 25 }
+          ]
+        },
+        { "name": "packages/server", "total": 40 }
+      ]
+    }
+  }
+}
+```
+
+**Content schema:** `{ profile: { name: string, total: number, children?: Array<(recursive)> } }`
+**Returns:** Clicked node information when user interacts.
+
+### Template: `form`
+
+Input fields with text inputs, selects, and checkboxes. Use for configuration, parameter collection, or setup wizards.
+
+```json
+{
+  "template": "form",
+  "title": "Project Configuration",
+  "content": {
+    "fields": [
+      { "name": "projectName", "label": "Project Name", "type": "text", "value": "my-app" },
+      { "name": "framework", "label": "Framework", "type": "select", "options": ["React", "Vue", "Svelte"], "value": "React" },
+      { "name": "typescript", "label": "Use TypeScript", "type": "checkbox", "value": true },
+      { "name": "description", "label": "Description", "type": "text", "value": "" }
+    ]
+  }
+}
+```
+
+**Content schema:** `{ fields: Array<{ name: string, label: string, type: "text" | "select" | "checkbox", value?: string | boolean, options?: string[] }> }`
+**Returns:** Object with field name-value pairs after user fills out and submits.
+
+### MCP Apps Best Practices
+
+1. **Use meaningful `id` values** — they are returned in responses and used for programmatic handling.
+2. **Keep list-sort items under 15** — longer lists become unwieldy for drag-and-drop.
+3. **Always provide `value` defaults** in forms — pre-fill with sensible defaults to reduce user effort.
+4. **Use `tags` in picker** — they power the search/filter functionality.
+5. **Flame-graph `total` values** should be consistent — parent total should equal sum of children.
+6. **Data-table `stats`** are optional — use them for KPI summary cards above the table.
+7. **Combine with LLM logic** — use returned values to drive next steps (e.g., form → generate config, picker → scope analysis).
+
+#### 6. `timeline` — Vertical Event Timeline (display only)
+
+```json
+{
+  "events": [
+    {"title": "v1.0 Release", "description": "Initial release with core features", "timestamp": "2025-01", "status": "complete"},
+    {"title": "v2.0 Beta", "description": "MCP Apps support", "timestamp": "2025-07", "status": "active"},
+    {"title": "v3.0 Planning", "status": "pending"}
+  ]
+}
+```
+
+Fields: `title` (required), `description?`, `timestamp?`, `status?` (`'complete'|'active'|'pending'|'error'`), `icon?`, `category?`
+
+#### 7. `kanban` — Drag-Drop Board (interactive — emits on card move)
+
+```json
+{
+  "columns": [
+    {"id": "todo", "label": "To Do"},
+    {"id": "in-progress", "label": "In Progress", "color": "#3b82f6"},
+    {"id": "done", "label": "Done", "color": "#22c55e"}
+  ],
+  "cards": [
+    {"id": "c1", "title": "Fix auth bug", "column": "todo", "tags": ["bugfix"], "priority": "high"},
+    {"id": "c2", "title": "Add search", "column": "in-progress", "tags": ["feature"], "priority": "medium"}
+  ]
+}
+```
+
+Returns `{cardId, fromColumn, toColumn}` when a card is dragged between columns.
+
+#### 8. `tree` — Collapsible Tree View (display only)
+
+```json
+{
+  "root": {
+    "label": "packages/",
+    "children": [
+      {"label": "server/", "children": [{"label": "index.ts"}, {"label": "tools/", "children": [{"label": "present.ts"}]}]},
+      {"label": "present/", "children": [{"label": "present-app.ts"}]}
+    ]
+  }
+}
+```
+
+Fields: `label` (required), `id?`, `icon?`, `children?: TreeNode[]`, `metadata?: Record<string,string>`. Accepts `root` as single node or array of nodes.
+
+#### 9. `diff-view` — Side-by-Side Code Diff (display only)
+
+```json
+{
+  "files": [{
+    "path": "auth.ts",
+    "status": "modified",
+    "additions": 12,
+    "deletions": 3,
+    "hunks": [{
+      "header": "@@ -10,5 +10,14 @@",
+      "changes": [
+        {"type": "context", "content": "const auth = {};"},
+        {"type": "delete", "content": "// old validation"},
+        {"type": "add", "content": "// new JWT validation"},
+        {"type": "add", "content": "const token = verify(jwt);"}
+      ]
+    }]
+  }],
+  "stats": {"additions": 12, "deletions": 3, "filesChanged": 1}
+}
+```
+
+Status values: `'added'|'modified'|'deleted'|'renamed'`. Change types: `'add'|'delete'|'context'`.
+
+#### 10. `dashboard` — Metric Cards Grid (display only)
+
+```json
+{
+  "metrics": [
+    {"label": "Uptime", "value": "99.9%", "status": "success", "trend": {"value": "+0.1%", "direction": "up"}},
+    {"label": "Build Time", "value": "4.2s", "type": "progress", "progress": 42, "status": "warning"},
+    {"label": "Top Endpoints", "type": "list", "value": "3", "items": [
+      {"label": "/api/search", "value": "1.2k/day"},
+      {"label": "/api/present", "value": "890/day"}
+    ]}
+  ]
+}
+```
+
+Metric types: `'stat'` (default), `'progress'` (with bar), `'list'` (sub-items). Status: `'success'|'warning'|'error'|'info'`.
+
+### Interaction Summary (All 10 Templates)
+
+| Template | Trigger | Data Returned to LLM |
+|----------|---------|---------------------|
+| list-sort | Auto on drag-drop | Reordered ID array |
+| data-table | Export button | Current filtered rows |
+| picker | Apply Selection button | Selected ID array |
+| flame-graph | Auto on node click | Clicked node object |
+| form | Submit button | Field values object |
+| kanban | Auto on card drag | `{cardId, fromColumn, toColumn}` |
+| timeline | Display only | — |
+| tree | Display only | — |
+| diff-view | Display only | — |
+| dashboard | Display only | — |