shadow-claw 1.27.0 → 1.28.0

package/dist/public/initControlPlane-Bi8ouFEb.js

@@ -0,0 +1 @@
+import{i as e}from"./rolldown-runtime-aKtaBQYM.js";import{r as t}from"./config-CrHchneq.js";import{i as n}from"./app-routes-Bs-riIvr.js";import{n as r}from"./txPromise-EBECky1b.js";import{t as i}from"./ulid-BY7rQVLN.js";import{t as a}from"./browser-nBz_r6l4.js";import{t as o}from"./getAllTasks-vpBlgGsc.js";var s=e(a(),1),c=class{_transport;_url;_httpUrl;_token;_clientId;_peerId;_deviceLabel;_capabilities;_version;_heartbeatIntervalMs;_reconnectDelayMs;_maxReconnectDelayMs;_handlers;_WebSocketClass;_EventSourceClass;_fetchFn;_ws=null;_es=null;_heartbeatTimer=null;_reconnectTimer=null;_currentReconnectDelay;_isDestroyed=!1;_state=`disconnected`;constructor(e){if(this._transport=e.transport||`sse`,this._clientId=e.clientId,this._peerId=e.peerId,this._deviceLabel=e.deviceLabel||`ShadowClaw Browser Client`,this._capabilities=e.capabilities||[`webmcp`,`opfs`,`push`],this._version=e.version||`1.27.1`,this._token=e.token,this._heartbeatIntervalMs=e.heartbeatIntervalMs||1e4,this._reconnectDelayMs=e.reconnectDelayMs||1e3,this._maxReconnectDelayMs=e.maxReconnectDelayMs||3e4,this._currentReconnectDelay=this._reconnectDelayMs,this._handlers=new Map,this._WebSocketClass=e.WebSocketClass||(typeof WebSocket<`u`?WebSocket:null),this._EventSourceClass=e.EventSourceClass||(typeof EventSource<`u`?EventSource:null),this._fetchFn=e.fetchFn||(typeof fetch<`u`?fetch.bind(globalThis):(()=>Promise.reject(Error(`fetch not available`)))),e.handlers)for(let[t,n]of Object.entries(e.handlers))this.registerHandler(t,n);let t=typeof location<`u`?location:null,n=t?`${t.protocol}//${t.host}`:`http://127.0.0.1:8888`,r=t?`${t.protocol===`https:`?`wss:`:`ws:`}//${t.host}`:`ws://127.0.0.1:8888`;this._url=e.url||`${r}/ws/control`,this._httpUrl=e.httpUrl||n}get transport(){return this._transport}get version(){return this._version}registerHandler(e,t){this._handlers.set(e,t)}unregisterHandler(e){this._handlers.delete(e)}getState(){return this._state}ensureConnected(e=!1){if(this._isDestroyed=!1,this._reconnectTimer&&=(clearTimeout(this._reconnectTimer),null),this._currentReconnectDelay=this._reconnectDelayMs,this._transport===`websocket`){let t=this._ws&&(this._ws.readyState===1||this._ws.readyState===this._WebSocketClass?.OPEN);(e||!t||this._state!==`connected`)&&(this._cleanupConnection(),this.connect())}else{let t=this._es&&(this._es.readyState===1||this._es.readyState===this._EventSourceClass?.OPEN);(e||!t||this._state!==`connected`)&&(this._cleanupConnection(),this.connect())}}connect(){this._isDestroyed||this._state===`connected`||this._state===`connecting`||(this._transport===`websocket`?this._connectWebSocket():this._connectSse())}_connectWebSocket(){if(!this._WebSocketClass){console.warn(`[ControlPlaneClient] WebSocket not supported in this environment`);return}this._state=`connecting`;let e=new URL(this._url,`ws://127.0.0.1:8888`);this._token&&e.searchParams.set(`token`,this._token);try{let t=new this._WebSocketClass(e.toString());this._ws=t,t.onopen=()=>{this._state=`connected`,this._currentReconnectDelay=this._reconnectDelayMs,this._sendRegister(),this._startHeartbeat()},t.onmessage=e=>{this._handleMessage(e.data)},t.onclose=()=>{this._cleanupConnection(),this._isDestroyed||this._scheduleReconnect()},t.onerror=e=>{console.warn(`[ControlPlaneClient] WebSocket error:`,e)}}catch(e){console.warn(`[ControlPlaneClient] Failed to establish WebSocket connection:`,e),this._cleanupConnection(),this._scheduleReconnect()}}_connectSse(){if(!this._EventSourceClass){(s.default===void 0||!s.default.env?.JEST_WORKER_ID)&&console.warn(`[ControlPlaneClient] EventSource not supported in this environment`);return}this._state=`connecting`;let e=new URL(`/api/control/events`,this._httpUrl);e.searchParams.set(`clientId`,this._clientId),this._token&&e.searchParams.set(`token`,this._token);try{let t=new this._EventSourceClass(e.toString());this._es=t,t.onopen=()=>{this._state=`connected`,this._currentReconnectDelay=this._reconnectDelayMs,this._sendRegister(),this._startHeartbeat()},typeof t.addEventListener==`function`&&t.addEventListener(`command:execute`,e=>{this._handleMessage(e.data)}),t.onmessage=e=>{this._handleMessage(e.data)},t.onerror=e=>{console.warn(`[ControlPlaneClient] SSE connection error:`,e),this._cleanupConnection(),this._isDestroyed||this._scheduleReconnect()}}catch(e){console.warn(`[ControlPlaneClient] Failed to establish SSE connection:`,e),this._cleanupConnection(),this._scheduleReconnect()}}disconnect(){this._isDestroyed=!0;try{this._sendUnregister()}catch{}this._cleanupConnection(),this._reconnectTimer&&=(clearTimeout(this._reconnectTimer),null)}_cleanupConnection(){if(this._state=`disconnected`,this._stopHeartbeat(),this._ws){try{this._ws.close()}catch{}this._ws=null}if(this._es){try{this._es.close()}catch{}this._es=null}}_scheduleReconnect(){this._reconnectTimer||this._isDestroyed||(this._reconnectTimer=setTimeout(()=>{this._reconnectTimer=null,this._isDestroyed||this.connect()},this._currentReconnectDelay),this._currentReconnectDelay=Math.min(this._currentReconnectDelay*1.5,this._maxReconnectDelayMs))}_startHeartbeat(){this._stopHeartbeat(),this._heartbeatTimer=setInterval(()=>{this._sendHeartbeat()},this._heartbeatIntervalMs)}_stopHeartbeat(){this._heartbeatTimer&&=(clearInterval(this._heartbeatTimer),null)}_sendRegister(){let e={clientId:this._clientId,deviceLabel:this._deviceLabel,capabilities:this._capabilities,version:this._version,transport:this._transport,peerId:this._peerId};this._sendMessage({id:i(),type:`client:register`,payload:e})}_sendHeartbeat(){let e={clientId:this._clientId,timestamp:Date.now()};this._sendMessage({id:i(),type:`client:heartbeat`,payload:e})}_sendUnregister(){if(!this._clientId)return;let e={clientId:this._clientId};this._sendMessage({id:i(),type:`client:unregister`,payload:e})}_sendMessage(e){if(this._transport===`websocket`){this._ws&&(this._ws.readyState===1||this._ws.readyState===this._WebSocketClass?.OPEN)&&this._ws.send(JSON.stringify(e));return}let t=new URL(`/api/control/messages`,this._httpUrl),n={"Content-Type":`application/json`};this._token&&(n[`x-control-token`]=this._token,n.Authorization=`Bearer ${this._token}`);let r={method:`POST`,headers:n,body:JSON.stringify(e)},i=t.hostname.toLowerCase(),a=i===`localhost`||i===`127.0.0.1`||i===`::1`||i===`[::1]`,o=/^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/.test(i);a?r.targetAddressSpace=`loopback`:o&&(r.targetAddressSpace=`private`),this._fetchFn(t.toString(),r).catch(e=>{console.warn(`[ControlPlaneClient] Failed to send message via HTTP POST:`,e)})}async _handleMessage(e){if(!e||typeof e!=`string`)return;let t;try{t=JSON.parse(e)}catch{return}if(t.type===`command:execute`){let{commandId:e,action:n,args:r}=t.payload,a=this._handlers.get(n);if(!a){this._sendMessage({id:i(),type:`command:result`,replyTo:t.id,payload:{commandId:e,success:!1,error:`Unknown action: ${n}`}});return}try{let n=await a(r);this._sendMessage({id:i(),type:`command:result`,replyTo:t.id,payload:{commandId:e,success:!0,data:n}})}catch(n){this._sendMessage({id:i(),type:`command:result`,replyTo:t.id,payload:{commandId:e,success:!1,error:n.message||String(n)}})}}}};function l(){if(typeof localStorage<`u`)try{let e=localStorage.getItem(t.CONTROL_PLANE_CLIENT_ID);if(e&&e.trim())return e.trim()}catch{}let e=n(),r=e?`${e}-${i().toLowerCase()}`:`client-${i().toLowerCase()}`;if(typeof localStorage<`u`)try{localStorage.setItem(t.CONTROL_PLANE_CLIENT_ID,r)}catch{}return r}async function u(e){if(typeof localStorage<`u`)try{let e=localStorage.getItem(t.CONTROL_PLANE_ENABLED);if(e!==null)return e===`true`||e===`1`}catch{}if(e)try{let{getConfig:n}=await import(`./getConfig-D89uJgo5.js`).then(e=>e.n),r=await n(e,t.CONTROL_PLANE_ENABLED);if(r!=null)return r===`true`||r===`1`}catch{}return!1}function d(e){if(typeof EventSource>`u`&&typeof WebSocket>`u`)return!1;let t=e||(typeof location<`u`?location:null);return!(!t||t.protocol===`file:`||typeof document<`u`&&document.querySelector(`meta[name="shadowclaw-static-only"]`))}function f(e){let n=``;if(typeof localStorage<`u`)try{n=(localStorage.getItem(t.CONTROL_PLANE_URL)||``).trim()}catch{}let r=e||(typeof location<`u`?location:null),i=r&&(r.protocol===`file:`||r.hostname&&(r.hostname.endsWith(`.github.io`)||r.hostname.endsWith(`.pages.dev`))),a=n;a||=i?`http://127.0.0.1:8888`:r&&r.host?`${r.protocol}//${r.host}`:`http://127.0.0.1:8888`,a=a.replace(/\/+$/,``);let o=a.replace(/^https?:/,e=>e===`https:`?`wss:`:`ws:`);return{httpUrl:a,wsUrl:`${o}/ws/control`}}function p(){let e=[];return typeof navigator<`u`&&(navigator.storage&&typeof navigator.storage.getDirectory==`function`&&e.push(`opfs`),`serviceWorker`in navigator&&typeof window<`u`&&`PushManager`in window&&e.push(`push`),(typeof document<`u`&&document.modelContext||navigator&&navigator.modelContext)&&e.push(`webmcp`)),typeof RTCPeerConnection<`u`&&e.push(`peerjs`),e}function m(){if(typeof navigator>`u`)return`ShadowClaw Node`;let e=navigator.userAgent,t=`Desktop`;/iPad/i.test(e)?t=`iPad`:/iPhone/i.test(e)?t=`iPhone`:/Android/i.test(e)?t=`Android`:/Macintosh/i.test(e)?t=`Mac`:/Windows/i.test(e)?t=`Windows`:/Linux/i.test(e)&&(t=`Linux`);let n=`Browser`;return/Chrome/i.test(e)&&!/Edg/i.test(e)?n=`Chrome`:/Safari/i.test(e)&&!/Chrome/i.test(e)?n=`Safari`:/Firefox/i.test(e)?n=`Firefox`:/Edg/i.test(e)&&(n=`Edge`),`${t} ${n}`}function h(){let e=``,t=``;typeof document<`u`&&(e=document.querySelector(`meta[name="version"]`)?.getAttribute(`content`)?.trim()||``,t=document.querySelector(`meta[name="revision"]`)?.getAttribute(`content`)?.trim()||``);let n=t.length>7?t.slice(0,7):t;return e&&n?`${e} (${n})`:e||n||`1.27.1`}let g=null;async function _(e,t={},n={}){let i=l(),a=m(),s=p();switch(e){case`send-message`:{if(!t.text)throw Error(`Missing text parameter`);let{orchestratorStore:e}=await import(`./orchestrator-BT3Ks5ip.js`).then(e=>e.n),r=n.orchestrator||e.orchestrator,i=t.groupId||e.activeGroupId||`br:main`;return r?.browserChat?.submit?(r.browserChat.submit(t.text,i),{queued:!0,groupId:i}):r?.submitMessage?(r.submitMessage(t.text,i),{queued:!0,groupId:i}):e.sendMessage?(e.sendMessage(t.text),{queued:!0,groupId:i}):{queued:!1,error:`Orchestrator not ready`}}case`list-tasks`:{let e=await o(await r());return t?.groupId&&(e=e.filter(e=>e.groupId===t.groupId)),{tasks:e}}case`read-state`:{let{orchestratorStore:e}=await import(`./orchestrator-BT3Ks5ip.js`).then(e=>e.n),t=n.orchestrator||e.orchestrator;return{clientId:i,deviceLabel:a,capabilities:s,version:n.version||h(),activeGroupId:n.orchestrator?.activeGroupId||e.activeGroupId||t?.activeGroupId||`br:main`,state:n.orchestrator?.state||e.state||t?.state||`idle`}}case`list-tools`:{try{let{getWebMcpTools:e}=await import(`./webmcp-DAjmliCx.js`).then(e=>e.a),t=await e();if(t&&t.length>0)return{tools:t.map(e=>({name:e.name,description:e.description,inputSchema:e.inputSchema,annotations:e.annotations}))}}catch{}try{let{orchestratorStore:e}=await import(`./orchestrator-BT3Ks5ip.js`).then(e=>e.n),r=n.orchestrator||e.orchestrator||(typeof document<`u`?document.querySelector(`shadow-claw`)?.orchestrator:null),i=t.groupId||r?.activeGroupId||e.activeGroupId||`br:main`,a=e.groups.find(e=>e.groupId===i);if(a?.toolTags&&a.toolTags.length>0){let{TOOL_DEFINITIONS:e}=await import(`./tools-C8x3nmo4.js`).then(e=>e.n),{parseWebMcpInputSchema:t}=await import(`./webmcp-DAjmliCx.js`).then(e=>e.a);return{tools:e.filter(e=>a.toolTags.includes(e.name)).map(e=>({name:e.name,description:e.description,inputSchema:t(e.input_schema)}))}}}catch{}let{TOOL_DEFINITIONS:e}=await import(`./tools-C8x3nmo4.js`).then(e=>e.n),{parseWebMcpInputSchema:r}=await import(`./webmcp-DAjmliCx.js`).then(e=>e.a);return{tools:e.map(e=>({name:e.name,description:e.description,inputSchema:r(e.input_schema)}))}}case`invoke-tool`:{if(!t.toolName)throw Error(`Missing toolName parameter`);try{let{orchestratorStore:e}=await import(`./orchestrator-BT3Ks5ip.js`).then(e=>e.n),{toolsStore:r}=await import(`./tools-DvckJZG2.js`).then(e=>e.n),i=n.orchestrator||e.orchestrator||(typeof document<`u`?document.querySelector(`shadow-claw`)?.orchestrator:null),a=t.groupId||i?.activeGroupId||e.activeGroupId||`br:main`,o=e.groups.find(e=>e.groupId===a);if(o?.toolTags&&o.toolTags.length>0){if(!o.toolTags.includes(t.toolName))throw Error(`Tool '${t.toolName}' is not enabled in the active conversation (${a}).`)}else if(r?.allTools&&r.allTools.some(e=>e.name===t.toolName)&&r?.enabledToolNames&&r.enabledToolNames.size>0){let e=r.enabledToolNames.has(t.toolName),n=r.isDeclarativeToolEnabled(t.toolName);if(!e&&!n)throw Error(`Tool '${t.toolName}' is not enabled on this client.`)}}catch(e){if(e.message&&e.message.includes(`is not enabled`))throw e}let e=typeof document<`u`&&document.modelContext||typeof navigator<`u`&&navigator.modelContext;if(e){let n;if(typeof e.getTools==`function`)try{let r=await e.getTools();if(Array.isArray(r)&&r.length>0){if(n=r.find(e=>e.name===t.toolName),!n)throw Error(`Tool '${t.toolName}' is not enabled or registered on this client.`)}else n=Array.isArray(r)?r.find(e=>e.name===t.toolName):void 0;if(n&&typeof n.execute==`function`)return{result:await n.execute(typeof t.input==`string`?JSON.parse(t.input):t.input||{})}}catch(e){if(e.message&&e.message.includes(`is not enabled`))throw e}let r=typeof t.input==`string`?t.input:JSON.stringify(t.input||{});if(typeof e.executeTool==`function`){if(n)try{return{result:await e.executeTool(n,r)}}catch{}try{return{result:await e.executeTool({name:t.toolName},r)}}catch{}try{return{result:await e.executeTool(t.toolName,r)}}catch{}}if(typeof navigator<`u`&&navigator.modelContextTesting&&typeof navigator.modelContextTesting.executeTool==`function`)try{return{result:await navigator.modelContextTesting.executeTool(t.toolName,r)}}catch{}if(typeof e.callTool==`function`)try{return{result:await e.callTool({name:t.toolName,arguments:typeof t.input==`string`?JSON.parse(t.input):t.input||{}})}}catch{}if(typeof e.invoke==`function`)try{return{result:await e.invoke(t.toolName,typeof t.input==`string`?JSON.parse(t.input):t.input||{})}}catch{}}let{orchestratorStore:r}=await import(`./orchestrator-BT3Ks5ip.js`).then(e=>e.n),i=n.orchestrator||r.orchestrator||(typeof document<`u`?document.querySelector(`shadow-claw`)?.orchestrator:null),a=i?.agentWorker;if(a&&typeof a.postMessage==`function`){let e=Date.now().toString(36)+Math.random().toString(36).slice(2),n=t.toolName===`ask_user`,r=t.timeoutMs||(n?3e5:6e4);return{result:await new Promise((n,o)=>{let s=setTimeout(()=>{a.removeEventListener(`message`,c),o(Error(`Timeout waiting for tool execution`))},r),c=t=>{let r=t.data;r&&r.type===`execute-tool-result`&&r.callId===e&&(clearTimeout(s),a.removeEventListener(`message`,c),r.error?o(Error(r.error)):n(r.result))};a.addEventListener(`message`,c),a.postMessage({type:`execute-tool`,callId:e,payload:{name:t.toolName,input:typeof t.input==`string`?JSON.parse(t.input):t.input||{},groupId:t.groupId||i?.activeGroupId||`br:main`}})})}}throw Error(`Tool ${t.toolName} could not be executed (no context or worker available)`)}case`trigger-backup`:{let{orchestratorStore:e}=await import(`./orchestrator-BT3Ks5ip.js`).then(e=>e.n),a=t.groupId||n.orchestrator?.activeGroupId||e.activeGroupId||`br:main`,o=await r(),{getGroupDir:s}=await import(`./getGroupDir-P1h9wl6S.js`).then(e=>e.n),c=await s(o,a);async function l(e,t=``){let n=[];for await(let[r,i]of e.entries()){let e=t?`${t}/${r}`:r;if(i.kind===`directory`){let t=await l(i,e);n.push(...t)}else n.push(e)}return n}async function u(e){try{let t=e.split(`/`),n=c;for(let e=0;e<t.length-1;e++)n=await n.getDirectoryHandle(t[e]);let r=await(await(await n.getFileHandle(t[t.length-1])).getFile()).arrayBuffer();return new Uint8Array(r)}catch{return null}}let{BackupController:d}=await import(`./backup-controller-CvzDOq4T.js`);return await new d({clientId:i,token:t.token,serverBaseUrl:f().httpUrl,fileEnumerator:()=>l(c),fileReader:e=>u(e)}).initiate()}default:throw Error(`Unknown action '${e}'`)}}function v(e={}){if(g){try{g.disconnect()}catch{}g=null}let n=e.clientId&&e.clientId.trim()||l(),r=p(),i=m(),a=e.version||h(),o=null;if(typeof localStorage<`u`)try{let e=localStorage.getItem(t.CONTROL_PLANE_TRANSPORT);(e===`sse`||e===`websocket`)&&(o=e)}catch{}let s=e.transport||o||`sse`,u;if(typeof localStorage<`u`)try{u=localStorage.getItem(t.PEERJS_MY_PEER_ID)||void 0}catch{}let{httpUrl:v,wsUrl:y}=f(),b=new c({clientId:n,deviceLabel:i,capabilities:r,version:a,peerId:u,transport:s,httpUrl:v,url:y,handlers:{"send-message":t=>_(`send-message`,t,e),"list-tasks":t=>_(`list-tasks`,t,e),"read-state":t=>_(`read-state`,t,e),"invoke-tool":t=>_(`invoke-tool`,t,e),"list-tools":t=>_(`list-tools`,t,e),"trigger-backup":t=>_(`trigger-backup`,t,e)}});return e.autoConnect!==!1&&d()&&b.connect(),g=b,b}function y(){return g}function b(){if(g){try{g.disconnect()}catch{}g=null}}async function x(e={}){let n=e.db;if(!n)try{n=await r()}catch{}if(!await u(n))return b(),null;if(!d())return null;if(typeof localStorage<`u`&&n)try{let{getConfig:e}=await import(`./getConfig-D89uJgo5.js`).then(e=>e.n),[r,i]=await Promise.all([e(n,t.CONTROL_PLANE_URL),e(n,t.CONTROL_PLANE_TRANSPORT)]);r&&localStorage.setItem(t.CONTROL_PLANE_URL,r),i&&localStorage.setItem(t.CONTROL_PLANE_TRANSPORT,i),localStorage.setItem(t.CONTROL_PLANE_ENABLED,`true`)}catch{}let i=y();return i?(i.ensureConnected(e.force),i):v(e)}export{x as ensureControlPlaneConnected,_ as executeClientControlCommand,u as isControlPlaneEnabled,d as shouldConnectControlPlane,b as stopControlPlaneClient};

package/dist/public/llms.txt

@@ -1,6 +1,32 @@
 # [ShadowClaw](https://xt-ml.github.io/shadow-claw/)
 
-> A browser-native, fully-featured AI assistant whose core orchestration and tool-use loop run client-side in the browser. Deployable as a PWA or native Electron desktop app, backed by a Node.js service layer (local proxying, control plane, MCP), and driven via the `shadow-claw` CLI. AI inference routes to remote APIs, local servers, or in-browser models depending on your configuration.
+> A browser-native AI assistant featuring client-side orchestration of the full agentic loop (reasoning, state machine, dynamic context windowing, and tool execution) running off the main thread in a Web Worker in the browser or Electron. Instantly launchable via `npx shadow-claw dev --open`, driven by a full-featured CLI, and backed by a 24/7 Node.js service layer (control plane, task scheduler, proxying, and MCP).
+
+## Quick Start & CLI
+
+Run instantly without cloning the repo:
+
+- `npx shadow-claw dev --open` — Start local services and launch the assistant in your browser immediately.
+- `npx shadow-claw init <dir>` — Scaffold a custom template or knowledge hub.
+- `npx shadow-claw server` — Run headless 24/7 backend services (task scheduler, MCP, REST API).
+- `npx shadow-claw send "prompt"` — Dispatch prompts to connected clients directly from your terminal.
+- [CLI Reference](https://xt-ml.github.io/shadow-claw/docs/subsystems/cli.md) — Complete guide to all CLI commands, flags, and control plane options.
+
+## When to Use This
+
+ShadowClaw is best suited for:
+
+- **Client-side orchestration of the agentic loop:** When you want the entire agent decision loop—state machine, prompt assembly, dynamic context windowing, and tool dispatch—to execute client-side off the main thread in a browser Web Worker or Electron.
+- **Zero-install instant launch & CLI driving:** Starting immediately with `npx shadow-claw dev --open`, scaffolding custom templates with `npx shadow-claw init`, or driving connected browser sessions, tasks, and backups through the `shadow-claw` CLI.
+- **Ultra-safe sandboxed execution:** Running real code, bash, and system operations inside isolated client-side environments—including an in-browser WebVM (v86 Alpine Linux running in WASM inside a Web Worker), `just-bash` POSIX emulation, and sandboxed OPFS/IndexedDB storage.
+- **Control plane & client bridge:** Driving browser and Electron execution surfaces from external tools, scripts, or CLI commands via real-time SSE, WebSockets, or WebRTC.
+- **Headless server & background services:** Running a persistent 24/7 Node backend (`shadow-claw server`) to manage client schedules in SQLite, tick cron schedules, wake dormant clients via Web Push, and serve REST APIs and MCP endpoints.
+- **Model Context Protocol (MCP) integrations:** Interfacing with external coding agents (Claude Desktop, Cursor, Goose) via STDIO or Streamable HTTP.
+- **Static knowledge hubs:** Authoring and deploying static documentation and agent-assisted knowledge repositories.
+
+When to look elsewhere:
+
+- Workloads requiring an unsandboxed, host-native server agent where the entire LLM prompt/tool execution loop must run directly against the server's bare-metal OS rather than sandboxed client execution surfaces.
 
 ## Docs
 
@@ -16,6 +42,15 @@
 - [Storage System](https://xt-ml.github.io/shadow-claw/docs/architecture/storage.md)
 - [Context Management](https://xt-ml.github.io/shadow-claw/docs/architecture/context-management.md)
 - [Streaming](https://xt-ml.github.io/shadow-claw/docs/architecture/streaming.md)
+- [Control Plane & Client Bridge](https://xt-ml.github.io/shadow-claw/docs/subsystems/control-plane.md)
+
+## MCP & Discovery
+
+- [MCP Server Card (SEP-2127)](https://xt-ml.github.io/shadow-claw/.well-known/mcp.json): Standardized remote MCP discovery document
+- [AI Catalog (SEP-2127)](https://xt-ml.github.io/shadow-claw/.well-known/ai-catalog.json): Decentralized AI artifact catalog
+- [MCP Servers Manifest (Discussion #1147)](https://xt-ml.github.io/shadow-claw/.well-known/mcp/servers.json): Server endpoint manifest
+- [Protected Resource Metadata (RFC 9728)](https://xt-ml.github.io/shadow-claw/.well-known/oauth-protected-resource): OAuth PRM discovery
+- [Stateless MCP Server Subsystem](https://xt-ml.github.io/shadow-claw/docs/subsystems/mcp-server.md): Complete architectural documentation for MCP Streamable HTTP & STDIO transports
 
 ## Optional