shadow-claw 1.28.0 → 1.29.0

package/dist/public/{base-task-model-CYkpwnvU-DDfHUUIS.js → base-task-model-CYkpwnvU-DrXr4G1R.js}

@@ -1 +1 @@
-var e=class{#e;#t;#n=!1;#r=new Set;#i=new AbortController;#a=null;constructor(e,t){this.#e=e,this.#t=t}static _validateLanguageTag(e){try{return Intl.getCanonicalLocales(e)[0]}catch{throw RangeError(`Invalid language tag: ${e}`)}}static _checkContext(){let e=this.__window||(typeof globalThis<`u`?globalThis:null),t=!1;try{(!e||e.closed||e.document&&e.document.defaultView!==e)&&(t=!0)}catch{t=!0}if(t){let t;try{t=e?.DOMException||globalThis.DOMException||Error}catch{t=globalThis.DOMException||Error}throw new t(`The execution context is not valid.`,`InvalidStateError`)}}_checkContext(){this.constructor._checkContext()}static baseAvailability(e={}){try{this._checkContext()}catch(e){let t=Promise.reject(e);return t.catch(()=>{}),t}let t=(async()=>{await this.ensureLanguageModel();let t={expectedInputs:[{type:`text`,languages:e.expectedInputLanguages||[`en`]}],expectedOutputs:[{type:`text`,languages:e.outputLanguage?[e.outputLanguage]:[`en`]}]};return await(this.__window||globalThis).LanguageModel.availability(t)})();return t.catch(()=>{}),t}static async ensureLanguageModel(){let e=this.__window||globalThis;e!==void 0&&!e.LanguageModel&&await import(`./prompt-api-polyfill-Dl1kbJhR.js`)}static availability(e={}){let t=(async()=>{this._checkContext(),await this.ensureLanguageModel();let t={expectedInputs:[{type:`text`,languages:e.expectedInputLanguages||[`en`]}],expectedOutputs:[{type:`text`,languages:e.outputLanguage?[e.outputLanguage]:[`en`]}]};return await globalThis.LanguageModel.availability(t)})();return t.catch(()=>{}),t}_isNonTranslatable(e){return typeof e==`string`&&/^[\s\x00-\x1f]*$/.test(e)}_runTask(e,t={}){if(this._isNonTranslatable(e)){let t=Promise.resolve(e);return t.catch(()=>{}),t}let n=this._runTaskInternal(e,t);return n.catch(()=>{}),n}async _runTaskInternal(e,t={}){if(this._checkContext(),this.#n){let e=Promise.reject(this.#a||new DOMException(`The summarizer has been destroyed.`,`AbortError`));return e.catch(()=>{}),e}let{userPrompt:n}=this.#t.buildPrompt(e,t),r=AbortSignal.any([this.#i.signal,t.signal].filter(Boolean));if(r.aborted){let e=Promise.reject(r.reason||new DOMException(`Aborted`,`AbortError`));return e.catch(()=>{}),e}let i={...t,signal:r},a=await this.#e.clone(i);this.#r.add(a);try{return await new Promise((e,t)=>{let o=()=>{t(r.reason||new DOMException(`Aborted`,`AbortError`))};if(r.aborted){o();return}r.addEventListener(`abort`,o,{once:!0}),a.prompt(n,i).then(e).catch(t).finally(()=>{r.removeEventListener(`abort`,o)})})}finally{a.destroy(),this.#r.delete(a)}}_runTaskStreaming(e,t={}){if(this._checkContext(),this._isNonTranslatable(e))return new ReadableStream({start(t){t.enqueue(e),t.close()}});let{userPrompt:n}=this.#t.buildPrompt(e,t),r=this.#e,i=t.signal;if(i?.aborted)throw i.reason||new DOMException(`Aborted`,`AbortError`);let a=this,o=AbortSignal.any([this.#i.signal,t.signal].filter(Boolean));if(o.aborted)throw o.reason||new DOMException(`Aborted`,`AbortError`);return new ReadableStream({async start(e){if(a.#n){e.error(a.#a||new DOMException(`The summarizer has been destroyed.`,`AbortError`));return}let i,s,c=()=>{s&&=(s.cancel().catch(()=>{}),null),i&&=(i.destroy(),a.#r.delete(i),null)},l=()=>{i&&c();try{e.error(o.reason||new DOMException(`Aborted`,`AbortError`))}catch{}};o.addEventListener(`abort`,l,{once:!0});try{let c={...t,signal:o};if(i=await r.clone(c),a.#r.add(i),o.aborted){l();return}for(s=i.promptStreaming(n,c).getReader();;){let{done:t,value:n}=await s.read();if(t)break;e.enqueue(n)}e.close()}catch(t){e.error(t)}finally{o.removeEventListener(`abort`,l),c()}}})}measureInputUsage(e,t={}){if(this._checkContext(),this.#n){let e=Promise.reject(this.#a||new DOMException(`The summarizer has been destroyed.`,`AbortError`));return e.catch(()=>{}),e}let n=AbortSignal.any([this.#i.signal,t.signal].filter(Boolean));if(n.aborted){let e=Promise.reject(n.reason||new DOMException(`Aborted`,`AbortError`));return e.catch(()=>{}),e}let r=new Promise((t,r)=>{let i=()=>r(n.reason||new DOMException(`Aborted`,`AbortError`));n.addEventListener(`abort`,i,{once:!0}),this.#e.measureInputUsage(e).then(t).catch(r).finally(()=>{n.removeEventListener(`abort`,i)})});return r.catch(()=>{}),r}get inputQuota(){return this.#e.inputQuota}destroy(e){if(!this.#n){this.#n=!0,this.#a=e||new DOMException(`The summarizer has been destroyed.`,`AbortError`),this.#i.abort(this.#a);for(let e of this.#r)e.destroy();this.#r.clear(),this.#e.destroy()}}static exposeAPIGlobally(e,t,n){if(typeof globalThis>`u`||!globalThis.document)return;let r=!!globalThis[n],i=n=>{try{if(!n||n[e]&&n[e].__isPolyfill)return;if(!(e in n)||r){let r={[e]:class extends t{}}[e];r.prototype[Symbol.toStringTag]=e,r.__window=n,r.__isPolyfill=!0,typeof r.create==`function`&&(r.create=r.create.bind(r)),typeof r.availability==`function`&&(r.availability=r.availability.bind(r)),Object.defineProperty(n,e,{value:r,writable:!0,configurable:!0,enumerable:!1}),n.DOMException&&(n.QuotaExceededError=n.DOMException)}}catch{}};if(i(globalThis),typeof HTMLIFrameElement<`u`)try{let e=Object.getOwnPropertyDescriptor(HTMLIFrameElement.prototype,`contentWindow`);e&&e.get&&Object.defineProperty(HTMLIFrameElement.prototype,"contentWindow",{get(){let t=e.get.call(this);return t&&i(t),t},configurable:!0})}catch{}let a=new MutationObserver(e=>{for(let t of e)for(let e of t.addedNodes)e.tagName===`IFRAME`&&(i(e.contentWindow),e.addEventListener(`load`,()=>i(e.contentWindow),{once:!1}))});globalThis.document?.documentElement&&(a.observe(globalThis.document.documentElement,{childList:!0,subtree:!0}),globalThis.document.querySelectorAll(`iframe`).forEach(e=>{i(e.contentWindow),e.addEventListener(`load`,()=>i(e.contentWindow),{once:!1})})),globalThis[e]&&globalThis[e].__isPolyfill&&console.log(`Polyfill: window.${e} is now backed by the ${e} API polyfill.`)}};export{e as t};
+var e=class{#e;#t;#n=!1;#r=new Set;#i=new AbortController;#a=null;constructor(e,t){this.#e=e,this.#t=t}static _validateLanguageTag(e){try{return Intl.getCanonicalLocales(e)[0]}catch{throw RangeError(`Invalid language tag: ${e}`)}}static _checkContext(){let e=this.__window||(typeof globalThis<`u`?globalThis:null),t=!1;try{(!e||e.closed||e.document&&e.document.defaultView!==e)&&(t=!0)}catch{t=!0}if(t){let t;try{t=e?.DOMException||globalThis.DOMException||Error}catch{t=globalThis.DOMException||Error}throw new t(`The execution context is not valid.`,`InvalidStateError`)}}_checkContext(){this.constructor._checkContext()}static baseAvailability(e={}){try{this._checkContext()}catch(e){let t=Promise.reject(e);return t.catch(()=>{}),t}let t=(async()=>{await this.ensureLanguageModel();let t={expectedInputs:[{type:`text`,languages:e.expectedInputLanguages||[`en`]}],expectedOutputs:[{type:`text`,languages:e.outputLanguage?[e.outputLanguage]:[`en`]}]};return await(this.__window||globalThis).LanguageModel.availability(t)})();return t.catch(()=>{}),t}static async ensureLanguageModel(){let e=this.__window||globalThis;e!==void 0&&!e.LanguageModel&&await import(`./prompt-api-polyfill-CXd75leW.js`)}static availability(e={}){let t=(async()=>{this._checkContext(),await this.ensureLanguageModel();let t={expectedInputs:[{type:`text`,languages:e.expectedInputLanguages||[`en`]}],expectedOutputs:[{type:`text`,languages:e.outputLanguage?[e.outputLanguage]:[`en`]}]};return await globalThis.LanguageModel.availability(t)})();return t.catch(()=>{}),t}_isNonTranslatable(e){return typeof e==`string`&&/^[\s\x00-\x1f]*$/.test(e)}_runTask(e,t={}){if(this._isNonTranslatable(e)){let t=Promise.resolve(e);return t.catch(()=>{}),t}let n=this._runTaskInternal(e,t);return n.catch(()=>{}),n}async _runTaskInternal(e,t={}){if(this._checkContext(),this.#n){let e=Promise.reject(this.#a||new DOMException(`The summarizer has been destroyed.`,`AbortError`));return e.catch(()=>{}),e}let{userPrompt:n}=this.#t.buildPrompt(e,t),r=AbortSignal.any([this.#i.signal,t.signal].filter(Boolean));if(r.aborted){let e=Promise.reject(r.reason||new DOMException(`Aborted`,`AbortError`));return e.catch(()=>{}),e}let i={...t,signal:r},a=await this.#e.clone(i);this.#r.add(a);try{return await new Promise((e,t)=>{let o=()=>{t(r.reason||new DOMException(`Aborted`,`AbortError`))};if(r.aborted){o();return}r.addEventListener(`abort`,o,{once:!0}),a.prompt(n,i).then(e).catch(t).finally(()=>{r.removeEventListener(`abort`,o)})})}finally{a.destroy(),this.#r.delete(a)}}_runTaskStreaming(e,t={}){if(this._checkContext(),this._isNonTranslatable(e))return new ReadableStream({start(t){t.enqueue(e),t.close()}});let{userPrompt:n}=this.#t.buildPrompt(e,t),r=this.#e,i=t.signal;if(i?.aborted)throw i.reason||new DOMException(`Aborted`,`AbortError`);let a=this,o=AbortSignal.any([this.#i.signal,t.signal].filter(Boolean));if(o.aborted)throw o.reason||new DOMException(`Aborted`,`AbortError`);return new ReadableStream({async start(e){if(a.#n){e.error(a.#a||new DOMException(`The summarizer has been destroyed.`,`AbortError`));return}let i,s,c=()=>{s&&=(s.cancel().catch(()=>{}),null),i&&=(i.destroy(),a.#r.delete(i),null)},l=()=>{i&&c();try{e.error(o.reason||new DOMException(`Aborted`,`AbortError`))}catch{}};o.addEventListener(`abort`,l,{once:!0});try{let c={...t,signal:o};if(i=await r.clone(c),a.#r.add(i),o.aborted){l();return}for(s=i.promptStreaming(n,c).getReader();;){let{done:t,value:n}=await s.read();if(t)break;e.enqueue(n)}e.close()}catch(t){e.error(t)}finally{o.removeEventListener(`abort`,l),c()}}})}measureInputUsage(e,t={}){if(this._checkContext(),this.#n){let e=Promise.reject(this.#a||new DOMException(`The summarizer has been destroyed.`,`AbortError`));return e.catch(()=>{}),e}let n=AbortSignal.any([this.#i.signal,t.signal].filter(Boolean));if(n.aborted){let e=Promise.reject(n.reason||new DOMException(`Aborted`,`AbortError`));return e.catch(()=>{}),e}let r=new Promise((t,r)=>{let i=()=>r(n.reason||new DOMException(`Aborted`,`AbortError`));n.addEventListener(`abort`,i,{once:!0}),this.#e.measureInputUsage(e).then(t).catch(r).finally(()=>{n.removeEventListener(`abort`,i)})});return r.catch(()=>{}),r}get inputQuota(){return this.#e.inputQuota}destroy(e){if(!this.#n){this.#n=!0,this.#a=e||new DOMException(`The summarizer has been destroyed.`,`AbortError`),this.#i.abort(this.#a);for(let e of this.#r)e.destroy();this.#r.clear(),this.#e.destroy()}}static exposeAPIGlobally(e,t,n){if(typeof globalThis>`u`||!globalThis.document)return;let r=!!globalThis[n],i=n=>{try{if(!n||n[e]&&n[e].__isPolyfill)return;if(!(e in n)||r){let r={[e]:class extends t{}}[e];r.prototype[Symbol.toStringTag]=e,r.__window=n,r.__isPolyfill=!0,typeof r.create==`function`&&(r.create=r.create.bind(r)),typeof r.availability==`function`&&(r.availability=r.availability.bind(r)),Object.defineProperty(n,e,{value:r,writable:!0,configurable:!0,enumerable:!1}),n.DOMException&&(n.QuotaExceededError=n.DOMException)}}catch{}};if(i(globalThis),typeof HTMLIFrameElement<`u`)try{let e=Object.getOwnPropertyDescriptor(HTMLIFrameElement.prototype,`contentWindow`);e&&e.get&&Object.defineProperty(HTMLIFrameElement.prototype,"contentWindow",{get(){let t=e.get.call(this);return t&&i(t),t},configurable:!0})}catch{}let a=new MutationObserver(e=>{for(let t of e)for(let e of t.addedNodes)e.tagName===`IFRAME`&&(i(e.contentWindow),e.addEventListener(`load`,()=>i(e.contentWindow),{once:!1}))});globalThis.document?.documentElement&&(a.observe(globalThis.document.documentElement,{childList:!0,subtree:!0}),globalThis.document.querySelectorAll(`iframe`).forEach(e=>{i(e.contentWindow),e.addEventListener(`load`,()=>i(e.contentWindow),{once:!1})})),globalThis[e]&&globalThis[e].__isPolyfill&&console.log(`Polyfill: window.${e} is now backed by the ${e} API polyfill.`)}};export{e as t};

package/dist/public/{configurePeerJs-BhBokQlC.js → configurePeerJs-B470pdeU.js}

@@ -1 +1 @@
-import{r as e}from"./config-CrHchneq.js";import{Ct as t,ht as n}from"./orchestrator-BT3Ks5ip.js";import{t as r}from"./setConfig-DFMYnYLE.js";async function i(i,a,o,s,c=``,l=0,u=``,d=!0){let f=o.trim(),p=t(s),m=c.trim(),h=Number.isFinite(l)?Math.max(0,Math.floor(l)):0,g=u.trim(),_=!!d;i.peerjsMyPeerId=f,i.peerjsTrustedPeerIds=p,i.peerjsServerHost=m,i.peerjsServerPort=h,i.peerjsServerPath=g,i.peerjsServerSecure=_,await r(a,e.PEERJS_MY_PEER_ID,f),await r(a,e.PEERJS_TRUSTED_PEER_IDS,JSON.stringify(p)),await r(a,e.PEERJS_SERVER_HOST,m),await r(a,e.PEERJS_SERVER_PORT,h?String(h):``),await r(a,e.PEERJS_SERVER_PATH,g),await r(a,e.PEERJS_SERVER_SECURE,_?`true`:`false`);let v=m?{host:m,path:g||void 0,port:h||void 0,secure:_}:{};i.peerjs.stop(),i.peerjs.configure(f,p,v),f&&n(i,`peerjs`)&&i.peerjs.start()}export{i as t};
+import{r as e}from"./config-CrHchneq.js";import{Ct as t,ht as n}from"./orchestrator-DpkkeD6T.js";import{t as r}from"./setConfig-DFMYnYLE.js";async function i(i,a,o,s,c=``,l=0,u=``,d=!0){let f=o.trim(),p=t(s),m=c.trim(),h=Number.isFinite(l)?Math.max(0,Math.floor(l)):0,g=u.trim(),_=!!d;i.peerjsMyPeerId=f,i.peerjsTrustedPeerIds=p,i.peerjsServerHost=m,i.peerjsServerPort=h,i.peerjsServerPath=g,i.peerjsServerSecure=_,await r(a,e.PEERJS_MY_PEER_ID,f),await r(a,e.PEERJS_TRUSTED_PEER_IDS,JSON.stringify(p)),await r(a,e.PEERJS_SERVER_HOST,m),await r(a,e.PEERJS_SERVER_PORT,h?String(h):``),await r(a,e.PEERJS_SERVER_PATH,g),await r(a,e.PEERJS_SERVER_SECURE,_?`true`:`false`);let v=m?{host:m,path:g||void 0,port:h||void 0,secure:_}:{};i.peerjs.stop(),i.peerjs.configure(f,p,v),f&&n(i,`peerjs`)&&i.peerjs.start()}export{i as t};

package/dist/public/docs/README.md

@@ -21,37 +21,36 @@ How the core pieces fit together.
 
 Detailed docs for each major subsystem.
 
-| Document                                                                | What it covers                                                                                                                                                                                                             |
-| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Shell Emulator](subsystems/shell.md)                                   | JS shell via `just-bash` AST evaluation, OPFS bridge, supported commands                                                                                                                                                   |
-| [WebVM](subsystems/vm.md)                                               | v86 Alpine Linux, boot modes, exclusivity guard, terminal bridge, 9p sync                                                                                                                                                  |
-| [Git Integration](subsystems/git.md)                                    | isomorphic-git on native filesystem handles, merge conflicts, credentials                                                                                                                                                  |
-| [Channel System](subsystems/channels.md)                                | Channel registry, browser/Telegram/iMessage channels, router, multi-channel flow                                                                                                                                           |
-| [Remote MCP](subsystems/remote-mcp.md)                                  | External MCP servers, tool discovery, authentication, JSON-RPC protocol, OAuth reconnection                                                                                                                                |
-| [Accounts & Credentials](subsystems/accounts.md)                        | Service account management, credential storage, auth bridges                                                                                                                                                               |
-| [Crypto & Secrets](subsystems/crypto.md)                                | AES-256-GCM key storage, runtime key handling, environment hardening; idempotent default Trusted Types policy                                                                                                              |
-| [Tools & Profiles](subsystems/tools.md)                                 | Tool definitions, execution dispatch, profiles, tool configuration panel, adding new tools                                                                                                                                 |
-| [Agent Skills](subsystems/skills.md)                                    | Workspace-local skill discovery, slash-command routing, declarative tool execution pipelines, output/toast suppression, discovery index generation (.well-known/agent-skills/index.json), resources, and static publishing |
-| [Notifications & Scheduling](subsystems/notifications.md)               | Web Push, VAPID, server-side SQLite scheduler, recursion guards                                                                                                                                                            |
-| [Providers & Rate Limiting](subsystems/providers.md)                    | LLM provider registry, adapter pattern, Prompt API (default), dynamic CPU/WASM fallback, CacheStorage model downloads, and 30s auto-closing error dialogs                                                                  |
-| [Electron Desktop](subsystems/electron.md)                              | Desktop app architecture, in-process server, power management                                                                                                                                                              |
-| [Reactive UI & Component Library](subsystems/reactive-ui.md)            | Signals, `ShadowClawElement`, `reconcileList`, Web Components, stores, ESM package exports, and Storybook workbench                                                                                                        |
-| [Model Registry & Capabilities](subsystems/providers.md#model-registry) | Dynamic model metadata fetching and modality capability detection                                                                                                                                                          |
-| [Attachment Capabilities](subsystems/attachment-capabilities.md)        | MIME-aware attachment handling and native vs fallback delivery                                                                                                                                                             |
-| [Chat Template Sanitizer](subsystems/sanitizer.md)                      | Strip control tokens and structural markers from local model output                                                                                                                                                        |
-| [A2UI Interactive Surfaces](subsystems/a2ui.md)                         | A2UI v1.0 catalog renderer, component rendering, PeerJS surface delivery, data binding, and Storybook workbench coverage for all 18 components                                                                             |
-| [AGUI Events & Adapter](subsystems/agui.md)                             | Translates orchestrator EventBus events to standardized AG-UI protocol events for UI visibility                                                                                                                            |
-| [Trusted Types Tinyfill](subsystems/trusted-types-tinyfill.md)          | Polyfill for Trusted Types API, browser compatibility, security rationale                                                                                                                                                  |
-| [Email Integration](subsystems/email.md)                                | IMAP/SMTP support with encrypted credentials                                                                                                                                                                               |
-| [WebMCP](subsystems/webmcp.md)                                          | Browser's Model Context Protocol integration and tool execution, supporting Chrome 154+ object input schemas, getWebMcpTools querying, and graceful degradation                                                            |
-| [Pages System](subsystems/pages.md)                                     | Workspace-relative pages rendering, sidebar navigation, static site seeding, pretty paths, same-origin route validation, and production asset inlining                                                                     |
-| [Custom Element Security](subsystems/custom-element-security.md)        | Custom element registry & DOM guards, allowlists, script descriptors ({ src, hasInit }), iframe sandbox policies, and nonce-gated CSP                                                                                      |
-| [LiteRT Provider](subsystems/providers.md)                              | In-browser WebGPU inference provider using Google LiteRT-LM                                                                                                                                                                |
-| [CLI & Static Site Publishing](subsystems/cli.md)                       | `shadow-claw` CLI commands (`build`, `dev`, `serve`, `server`, `init`, `clients`, `send`, `backup`, `tasks`, `mcp`, `skills:index`), dual-root path resolution, and npm packaging                                          |
-| [Control Plane & Client Bridge](subsystems/control-plane.md)            | Dual SSE/WebSocket control plane for CLI driving and persistent execution surface                                                                                                                                          |
-| [Stateless MCP Server](subsystems/mcp-server.md)                        | Official Stateless Model Context Protocol (2026-07-28) server for external agent hosts, multi-client tool targeting, CLI driving, and dynamic browser tool relay                                                           |
-| [File Backup Subsystem](subsystems/backup.md)                           | Remote workspace and OPFS file backups to server storage                                                                                                                                                                   |
-| [OpenAPI & Endpoint Discoverability](subsystems/openapi.md)             | Official OpenAPI 3.1 specification, interactive Scalar documentation UI, and route-coverage contract testing                                                                                                               |
+| Document                                                         | What it covers                                                                                                                                                                                                              |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Shell Emulator](subsystems/shell.md)                            | JS shell via `just-bash` AST evaluation, OPFS bridge, supported commands                                                                                                                                                    |
+| [WebVM](subsystems/vm.md)                                        | v86 Alpine Linux, boot modes, exclusivity guard, terminal bridge, 9p sync                                                                                                                                                   |
+| [Git Integration](subsystems/git.md)                             | isomorphic-git on native filesystem handles, merge conflicts, credentials                                                                                                                                                   |
+| [Channel System](subsystems/channels.md)                         | Channel registry, browser/Telegram/iMessage channels, router, multi-channel flow                                                                                                                                            |
+| [Remote MCP](subsystems/remote-mcp.md)                           | External MCP servers, tool discovery, authentication, JSON-RPC protocol, OAuth reconnection                                                                                                                                 |
+| [Accounts & Credentials](subsystems/accounts.md)                 | Service account management, credential storage, auth bridges                                                                                                                                                                |
+| [Crypto & Secrets](subsystems/crypto.md)                         | AES-256-GCM key storage, runtime key handling, environment hardening; idempotent default Trusted Types policy                                                                                                               |
+| [Tools & Profiles](subsystems/tools.md)                          | Tool definitions, execution dispatch, profiles, tool configuration panel, adding new tools                                                                                                                                  |
+| [Agent Skills](subsystems/skills.md)                             | Workspace-local skill discovery, slash-command routing, declarative tool execution pipelines, output/toast suppression, discovery index generation (.well-known/agent-skills/index.json), resources, and static publishing  |
+| [Notifications & Scheduling](subsystems/notifications.md)        | Web Push, VAPID, server-side SQLite scheduler, recursion guards                                                                                                                                                             |
+| [Providers & Model Registry](subsystems/providers.md)            | LLM provider registry, adapter pattern, Prompt API (default with polyfills), LiteRT-LM WebGPU, dynamic CPU/WASM fallback, model registry & capability detection, CacheStorage model downloads, and 30s auto-closing dialogs |
+| [Electron Desktop](subsystems/electron.md)                       | Desktop app architecture, in-process server, power management                                                                                                                                                               |
+| [Reactive UI & Component Library](subsystems/reactive-ui.md)     | Signals, `ShadowClawElement`, `reconcileList`, Web Components, stores, ESM package exports, and Storybook workbench                                                                                                         |
+| [Attachment Capabilities](subsystems/attachment-capabilities.md) | MIME-aware attachment handling and native vs fallback delivery                                                                                                                                                              |
+| [Chat Template Sanitizer](subsystems/sanitizer.md)               | Strip control tokens and structural markers from local model output                                                                                                                                                         |
+| [A2UI Interactive Surfaces](subsystems/a2ui.md)                  | A2UI v1.0 catalog renderer, component rendering, PeerJS surface delivery, data binding, and Storybook workbench coverage for all 18 components                                                                              |
+| [AGUI Events & Adapter](subsystems/agui.md)                      | Translates orchestrator EventBus events to standardized AG-UI protocol events for UI visibility                                                                                                                             |
+| [Trusted Types Tinyfill](subsystems/trusted-types-tinyfill.md)   | Polyfill for Trusted Types API, browser compatibility, security rationale                                                                                                                                                   |
+| [Email Integration](subsystems/email.md)                         | IMAP/SMTP support with encrypted credentials                                                                                                                                                                                |
+| [WebMCP](subsystems/webmcp.md)                                   | Browser's Model Context Protocol integration and tool execution, supporting Chrome 154+ object input schemas, getWebMcpTools querying, and graceful degradation                                                             |
+| [Web Share Target](subsystems/share-target.md)                   | OS share sheet integration receiving files, URLs, and text into OPFS workspaces via PWA Web Share Target API                                                                                                                |
+| [Pages System](subsystems/pages.md)                              | Workspace-relative pages rendering, sidebar navigation, static site seeding, pretty paths, same-origin route validation, and production asset inlining                                                                      |
+| [Custom Element Security](subsystems/custom-element-security.md) | Custom element registry & DOM guards, allowlists, script descriptors ({ src, hasInit }), iframe sandbox policies, and nonce-gated CSP                                                                                       |
+| [CLI & Static Site Publishing](subsystems/cli.md)                | `shadow-claw` CLI commands (`build`, `dev`, `serve`, `server`, `init`, `clients`, `send`, `backup`, `tasks`, `mcp`, `skills:index`), dual-root path resolution, and npm packaging                                           |
+| [Control Plane & Client Bridge](subsystems/control-plane.md)     | SSE, WebSocket, and WebRTC DataChannel control plane for CLI driving, headless automation, and persistent browser execution surfaces                                                                                        |
+| [Stateless MCP Server](subsystems/mcp-server.md)                 | Official Stateless Model Context Protocol (2026-07-28) server for external agent hosts, featuring native server management tools (`shadowclaw_server_*`), multi-client tool targeting, and dynamic browser tool relaying    |
+| [File Backup Subsystem](subsystems/backup.md)                    | Remote workspace and OPFS file backups to server storage                                                                                                                                                                    |
+| [OpenAPI & Endpoint Discoverability](subsystems/openapi.md)      | Official OpenAPI 3.1 specification, interactive Scalar documentation UI, and route-coverage contract testing                                                                                                                |
 
 ### Guides
 
@@ -68,6 +67,7 @@ Step-by-step instructions for common dev tasks.
 | [Service Accounts & Credentials](guides/adding-service-accounts.md)            | How to manage encrypted credentials for channels and services                                 |
 | [Configuring Messaging Channels](guides/configuring-messaging-channels.md)     | User guide for Telegram and iMessage setup                                                    |
 | [Server Development Configuration](guides/server-development-configuration.md) | CLI flags, CORS modes, host binding, port configuration, opt-in HTTPS/TLS, CSP report logging |
+| [Publishing to GitHub Pages](guides/publishing-to-github-pages.md)             | Step-by-step setup for static publishing via GitHub Actions, CLI builds, and template repos   |
 
 ### Decisions
 

package/dist/public/docs/architecture/context-management.md

@@ -65,6 +65,13 @@ export function estimateMessageTokens(message: ConversationMessage): number {
 }
 ```
 
+### Token Estimation & Cache Tracking
+
+In addition to estimating context consumption before LLM invocation, ShadowClaw tracks live token metrics and prompt caching statistics returned by providers:
+
+- **Token Usage Tracking:** Tracks prompt/input tokens, output/completion tokens, and total token usage per turn.
+- **Cache Hits & Misses:** Captures cache read hits (`cache_read_input_tokens`) and cache creation (`cache_creation_input_tokens`) from Anthropic and AWS Bedrock responses, accumulating them in `StreamAccumulator` (`src/worker/StreamAccumulator/`) and recording them in conversation history.
+
 ## Output Truncation
 
 **File:** `src/context/truncateToolOutput.ts`

package/dist/public/docs/architecture/storage.md

@@ -217,6 +217,15 @@ To prevent storage state leakage when multiple instances are deployed under subp
    When booting a namespaced deployment for the first time, ShadowClaw checks if data was previously stored under `"shadowclaw"`.
    - **IndexedDB**: Copies all object stores into the new namespaced database in a single non-destructive pass, setting `DB_MIGRATED_FROM_LEGACY`.
    - **OPFS**: Recursively copies all legacy workspace directories and files from `"shadowclaw"` into `"shadowclaw-${namespace}"` (with Safari worker write fallback), setting `OPFS_MIGRATED_FROM_LEGACY`.
-   The legacy storage is left intact as a fallback seed.
+     The legacy storage is left intact as a fallback seed.
 5. **Namespaced `localStorage` (`namespacedStorage.ts`):**
    Key pattern `shadowclaw:${namespace}:${key}` with automatic one-time copy-on-read from legacy unprefixed keys.
+
+## Files Browser Safeguards & Clipboard Operations
+
+The Files browser (`src/components/shadow-claw-files/`) incorporates robust safeguards for file and directory manipulation:
+
+- **Clipboard-Driven Actions**: Supports Cut, Copy, and Paste for files and directories across workspaces. The Paste action is dynamically hidden when the clipboard is empty.
+- **Folder Self-Paste Protection**: When copying or moving directories, operations recursively validate target paths, strictly preventing pasting a directory into itself or any of its descendants.
+- **Inter-Group Transfers**: Files and folders can be moved or copied across different conversation groups (`sourceGroupId` $\rightarrow$ `targetGroupId`).
+- **Conflict Resolution**: When an item with the same name exists at the destination, the UI prompts with non-destructive options to either rename the incoming item or overwrite the existing target.

package/dist/public/docs/decisions/bundled-typescript-architecture.md

@@ -2,7 +2,6 @@
 
 **Status:** Active
 **Date:** 2026-04-19
-**Commit:** `7d0540e` — "Build pipeline overhaul: TypeScript, Rollup, Electron, and E2E improvements"
 
 ## Context
 

package/dist/public/docs/decisions/native-web-components-and-signals.md

@@ -2,7 +2,6 @@
 
 **Status:** Active
 **Date:** Early project — established in original architecture
-**Commit:** `7d0540e` — co-located component assets introduced
 
 ## Context
 

package/dist/public/docs/example/article/index.html

@@ -1,4 +1,4 @@
-<!doctype html><html lang="en"><head><title>ShadowClaw</title><meta charset="utf-8"><meta name="revision" content="19ae0bb4c7c6a8640bebeb5c18f31bda04741ae3" /><meta name="version" content="1.28.0" /><meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover"><meta name="description" content="ShadowClaw - Browser-native AI agent." /><link rel="canonical" href="https://xt-ml.github.io/shadow-claw/"><meta property="og:title" content="ShadowClaw"><meta property="og:description" content="Browser-native personal AI assistant with local and remote LLM orchestration, Web Workers, OPFS storage, and agentic tool execution."><meta property="og:type" content="website"><meta property="og:url" content="https://xt-ml.github.io/shadow-claw/"><meta property="og:image" content="https://xt-ml.github.io/shadow-claw/assets/icons/512.png"><meta name="twitter:card" content="summary"><meta name="twitter:title" content="ShadowClaw"><meta name="twitter:description" content="Browser-native personal AI assistant with local and remote LLM orchestration, Web Workers, OPFS storage, and agentic tool execution."><meta name="twitter:image" content="https://xt-ml.github.io/shadow-claw/assets/icons/512.png"><script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"SoftwareApplication","@id":"https://xt-ml.github.io/shadow-claw/#software","name":"ShadowClaw","description":"Browser-native personal AI assistant with local and remote LLM orchestration, Web Workers, OPFS storage, and agentic tool execution.","url":"https://xt-ml.github.io/shadow-claw/","applicationCategory":"DeveloperApplication","operatingSystem":"Web, Browser, Desktop","offers":{"@type":"Offer","price":"0","priceCurrency":"USD"},"author":{"@type":"Organization","name":"xt-ml","url":"https://github.com/xt-ml"},"codeRepository":"https://github.com/xt-ml/shadow-claw","license":"https://github.com/xt-ml/shadow-claw/blob/main/LICENSE"},{"@type":"WebSite","@id":"https://xt-ml.github.io/shadow-claw/#website","url":"https://xt-ml.github.io/shadow-claw/","name":"ShadowClaw","description":"Official website and live deployment of ShadowClaw browser-native AI assistant.","publisher":{"@type":"Organization","name":"xt-ml","url":"https://github.com/xt-ml"}},{"@type":"Organization","@id":"https://xt-ml.github.io/shadow-claw/#organization","name":"xt-ml","url":"https://github.com/xt-ml","sameAs":["https://github.com/xt-ml"]}]}</script><meta name="theme-color" content="#fff" /><meta http-equiv="origin-trial" content="A88uTgESYWcVgREKVReKB6jom41uP8TzW6ei3jNdidf+Xl6ONqKRjKNBphsxhrZmdkakLK3oXDgkGq53rtZYSAMAAAB2eyJvcmlnaW4iOiJodHRwczovL3h0LW1sLmdpdGh1Yi5pbzo0NDMiLCJmZWF0dXJlIjoiV2ViTUNQIiwiZXhwaXJ5IjoxNzk0ODczNjAwLCJpc1N1YmRvbWFpbiI6dHJ1ZSwiaXNUaGlyZFBhcnR5Ijp0cnVlfQ=="><base href="/shadow-claw/"><script id="shadow-claw-site-config" type="application/json">{"$schema":"https:\u002f\u002fjson-schema.org\u002fdraft\u002f2020-12\u002fschema","site":{"title":"ShadowClaw","description":"ShadowClaw - Browser-native AI agent.","themeColor":"#fff"},"branding":{"faviconPath":"assets\u002ficons\u002ffavicon.ico","appleTouchIconPath":"assets\u002ficons\u002f180.png","notFoundPath":"404.html"},"pwa":{"manifestPath":"manifest.json","themeColor":"#000000"},"sitemapPath":"sitemap.xml","assets":["assets"],"sidebar":{"pagesHidden":false,"chatHidden":false,"tasksHidden":false,"filesHidden":false,"defaultPage":"pages"},"settings":{"defaultToolsProfile":"__builtin_default"}}</script>
+<!doctype html><html lang="en"><head><title>ShadowClaw</title><meta charset="utf-8"><meta name="revision" content="6c79eccd1cf4132f8ef7e80b4310efd1b42ce4cc" /><meta name="version" content="1.29.0" /><meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover"><meta name="description" content="ShadowClaw - Browser-native AI agent." /><link rel="canonical" href="https://xt-ml.github.io/shadow-claw/"><meta property="og:title" content="ShadowClaw"><meta property="og:description" content="Browser-native personal AI assistant with local and remote LLM orchestration, Web Workers, OPFS storage, and agentic tool execution."><meta property="og:type" content="website"><meta property="og:url" content="https://xt-ml.github.io/shadow-claw/"><meta property="og:image" content="https://xt-ml.github.io/shadow-claw/assets/icons/512.png"><meta name="twitter:card" content="summary"><meta name="twitter:title" content="ShadowClaw"><meta name="twitter:description" content="Browser-native personal AI assistant with local and remote LLM orchestration, Web Workers, OPFS storage, and agentic tool execution."><meta name="twitter:image" content="https://xt-ml.github.io/shadow-claw/assets/icons/512.png"><script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"SoftwareApplication","@id":"https://xt-ml.github.io/shadow-claw/#software","name":"ShadowClaw","description":"Browser-native personal AI assistant with local and remote LLM orchestration, Web Workers, OPFS storage, and agentic tool execution.","url":"https://xt-ml.github.io/shadow-claw/","applicationCategory":"DeveloperApplication","operatingSystem":"Web, Browser, Desktop","offers":{"@type":"Offer","price":"0","priceCurrency":"USD"},"author":{"@type":"Organization","name":"xt-ml","url":"https://github.com/xt-ml"},"codeRepository":"https://github.com/xt-ml/shadow-claw","license":"https://github.com/xt-ml/shadow-claw/blob/main/LICENSE"},{"@type":"WebSite","@id":"https://xt-ml.github.io/shadow-claw/#website","url":"https://xt-ml.github.io/shadow-claw/","name":"ShadowClaw","description":"Official website and live deployment of ShadowClaw browser-native AI assistant.","publisher":{"@type":"Organization","name":"xt-ml","url":"https://github.com/xt-ml"}},{"@type":"Organization","@id":"https://xt-ml.github.io/shadow-claw/#organization","name":"xt-ml","url":"https://github.com/xt-ml","sameAs":["https://github.com/xt-ml"]}]}</script><meta name="theme-color" content="#fff" /><meta http-equiv="origin-trial" content="A88uTgESYWcVgREKVReKB6jom41uP8TzW6ei3jNdidf+Xl6ONqKRjKNBphsxhrZmdkakLK3oXDgkGq53rtZYSAMAAAB2eyJvcmlnaW4iOiJodHRwczovL3h0LW1sLmdpdGh1Yi5pbzo0NDMiLCJmZWF0dXJlIjoiV2ViTUNQIiwiZXhwaXJ5IjoxNzk0ODczNjAwLCJpc1N1YmRvbWFpbiI6dHJ1ZSwiaXNUaGlyZFBhcnR5Ijp0cnVlfQ=="><base href="/shadow-claw/"><script id="shadow-claw-site-config" type="application/json">{"$schema":"https:\u002f\u002fjson-schema.org\u002fdraft\u002f2020-12\u002fschema","site":{"title":"ShadowClaw","description":"ShadowClaw - Browser-native AI agent.","themeColor":"#fff"},"branding":{"faviconPath":"assets\u002ficons\u002ffavicon.ico","appleTouchIconPath":"assets\u002ficons\u002f180.png","notFoundPath":"404.html"},"pwa":{"manifestPath":"manifest.json","themeColor":"#000000"},"sitemapPath":"sitemap.xml","assets":["assets"],"sidebar":{"pagesHidden":false,"chatHidden":false,"tasksHidden":false,"filesHidden":false,"defaultPage":"pages"},"settings":{"defaultToolsProfile":"__builtin_default"}}</script>
     <script>var ShadowClawThemeInit=(function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});function t(){if(globalThis.trustedTypes)return;let e=new Map;globalThis.trustedTypes={createPolicy:(t,n)=>{if(e.has(t))throw TypeError(`Policy with name "${t}" already exists.`);let r={createHTML:n.createHTML?e=>n.createHTML(e):void 0,createScriptURL:n.createScriptURL?e=>n.createScriptURL(e):void 0,createScript:n.createScript?e=>n.createScript(e):void 0};return e.set(t,r),r},getPolicy:t=>e.get(t)??null,isHTML:e=>typeof e==`string`||e instanceof Object&&`toString`in e,isScriptURL:e=>typeof e==`string`||e instanceof Object&&`toString`in e,isScript:e=>typeof e==`string`||e instanceof Object&&`toString`in e}}let n=`__shadowClawDefaultTrustedTypesPolicyState`,r=`default`,i=`shadowclaw-sandbox`;function a(){let e=globalThis;return e[n]||(e[n]={initialized:!1,policy:null}),e[n]}function o(){let e=a();if(e.initialized)return;let t=Reflect.get(globalThis,`trustedTypes`);if(!(!t||typeof t.createPolicy!=`function`)){e.initialized=!0;try{if(typeof t.getPolicy==`function`){let n=t.getPolicy(r);if(n){e.policy=n;return}}let n=!1;if(typeof t.getPolicyNames==`function`){let e=t.getPolicyNames();Array.isArray(e)&&e.includes(r)&&(n=!0)}if(n){if(typeof t.getPolicy==`function`){let n=t.getPolicy(i);if(n){e.policy=n;return}}e.policy=t.createPolicy(i,{createHTML:e=>e,createScriptURL:e=>e});return}e.policy=t.createPolicy(r,{createHTML:e=>e,createScriptURL:e=>e})}catch{typeof t.getPolicy==`function`&&(e.policy=t.getPolicy(r)??t.getPolicy(i)??null)}}}new class{loading=!1;models=new Map;getModelInfo(e){return this.models.get(e.toLowerCase())??null}registerModelInfo(e,t){this.models.set(e.toLowerCase(),t)}clear(){this.models.clear()}async fetchModelInfo(e,t,n){if(e.modelsUrl){this.loading=!0;try{let r=new Headers;if(r.set(`Content-Type`,`application/json`),e.headers)for(let[t,n]of Object.entries(e.headers))r.set(t,n);if(n)for(let[e,t]of Object.entries(n))r.set(e,t);if(t&&e.apiKeyHeader){let n=e.apiKeyHeaderFormat;r.set(e.apiKeyHeader,n?n.replace(`{key}`,t):t)}let i=await fetch(e.modelsUrl,{headers:r});if(!i.ok)throw Error(`HTTP ${i.status} ${i.statusText}`);let a=await i.json(),o=Array.isArray(a.data)?a.data:Array.isArray(a.models)?a.models:[];for(let e of o){if(!e.id)continue;let t=e.context_length??e.context_window??0,n=e.max_completion_tokens||e.per_request_limits?.completion_tokens||e.top_provider?.max_completion_tokens||null,r=typeof e.supports_tools==`boolean`?e.supports_tools:typeof e.supportsTools==`boolean`?e.supportsTools:void 0,i=this.extractModalities(e,`input`),a=this.extractModalities(e,`output`),o=this.modalitiesInclude(i,`image`,`vision`),s=this.modalitiesInclude(i,`audio`,`voice`,`hearing`),c=this.modalitiesInclude(i,`video`),l=e.id===`openrouter/free`||this.supportedParametersInclude(e,`image`,`vision`,`audio`,`tool`,`structured`),u=this.extractReasoning(e);!t&&Array.isArray(e.providers)&&e.providers.length>0&&(t=e.providers[0]?.context_length||0),this.registerModelInfo(e.id,{contextWindow:t,maxOutput:n,...r!==void 0&&{supportsTools:r},...i.length>0&&{inputModalities:i},...a.length>0&&{outputModalities:a},...o!==void 0&&{supportsImageInput:o},...s!==void 0&&{supportsAudioInput:s},...c!==void 0&&{supportsVideoInput:c},...u&&{reasoning:u},...l&&{routesByRequestFeatures:l}})}o.length>0&&console.log(`[ModelRegistry] Registered ${o.length} models for provider "${e.id}"`)}catch(t){console.error(`[ModelRegistry] Error fetching models for ${e.id}:`,t)}finally{this.loading=!1}}}extractModalities(e,t){let n=t===`input`?e.input_modalities||e.inputModalities:e.output_modalities||e.outputModalities,r=e.architecture||{},i=t===`input`?r.input_modalities||r.inputModalities:r.output_modalities||r.outputModalities,a=typeof r.modality==`string`?r.modality:``,o=this.parseArchitectureModality(a,t),s=[...this.normalizeStringArray(n),...this.normalizeStringArray(i),...o];return Array.from(new Set(s))}extractReasoning(e){let t=e?.reasoning;if(!t||typeof t!=`object`)return;let n=this.normalizeStringArray(t.supported_efforts),r=typeof t.default_effort==`string`?t.default_effort.toLowerCase():void 0,i=typeof t.default_enabled==`boolean`?t.default_enabled:void 0,a=typeof t.supports_max_tokens==`boolean`?t.supports_max_tokens:void 0,o=typeof t.mandatory==`boolean`?t.mandatory:void 0;if(!(n.length===0&&r===void 0&&i===void 0&&a===void 0&&o===void 0))return{...n.length>0&&{supportedEfforts:n},...r!==void 0&&{defaultEffort:r},...i!==void 0&&{defaultEnabled:i},...a!==void 0&&{supportsMaxTokens:a},...o!==void 0&&{mandatory:o}}}modalitiesInclude(e,...t){if(e.length!==0)return t.some(t=>e.some(e=>e.includes(t)))}normalizeStringArray(e){return Array.isArray(e)?e.filter(e=>typeof e==`string`).map(e=>e.toLowerCase()):[]}parseArchitectureModality(e,t){if(!e)return[];let[n=``,r=``]=e.toLowerCase().split(`->`).map(e=>e.trim());return(t===`input`?n:r).split(/[+,/\s]+/).map(e=>e.trim()).filter(Boolean)}supportedParametersInclude(e,...t){let n=this.normalizeStringArray(e.supported_parameters||e.supportedParameters);return t.some(e=>n.some(t=>t.includes(e)))}};function s(e){return e.replace(/^\/+|\/+$/g,``)}function c(e){let t=s(e);return t.endsWith(`/index.html`)?t=t.slice(0,-11):t.endsWith(`index.html`)&&(t=t.slice(0,-10)),s(t)}function l(e){let t=s(e),n=t.split(`/`).filter(Boolean);if(n.length===0)return null;let r=n[0].toLowerCase();if(r===`pages`){if(n.length>=3){let e=n[1];return{page:`pages`,groupId:e===`main`?`br:main`:e.startsWith(`br-`)?`br:${e.slice(3)}`:e,path:n.slice(2).join(`/`)}}return{page:`pages`,groupId:`br:main`,path:n.slice(1).join(`/`)}}if(r===`files`){let e=n[1]||`main`;return{page:`files`,groupId:e===`main`?`br:main`:e.startsWith(`br-`)?`br:${e.slice(3)}`:e,path:n.slice(2).join(`/`)||void 0}}if(r===`chat`){let e=n[1]||`main`;return{page:`chat`,groupId:e===`main`?`br:main`:e.startsWith(`br-`)?`br:${e.slice(3)}`:e}}if(r===`tasks`){let e=n[1]||`main`;return{page:`tasks`,groupId:e===`main`?`br:main`:e.startsWith(`br-`)?`br:${e.slice(3)}`:e}}return r===`main`?{page:`pages`,groupId:`br:main`,path:n.slice(1).join(`/`)}:{page:`pages`,groupId:`br:main`,path:t}}function u(){if(typeof document<`u`){let e=document.getElementById(`shadow-claw-static-routing`);if(e&&e.textContent)try{let t=JSON.parse(e.textContent);if(t&&typeof t==`object`&&t.routes)return t}catch(e){console.warn(`Failed to parse embedded static routing manifest:`,e)}}return null}function d(e,t){let n=t||u();if(!n||!n.routes)return null;let r=c(e);if(!r)return null;for(let[e,t]of Object.entries(n.routes))if(!(!t||!t.prettyPath)&&c(t.prettyPath)===r)return l(e);return null}let f=null,ee=new Set([`chat`,`files`,`tasks`,`pages`,`settings`,`tools`,`channels`]);function te(){f=null}typeof globalThis<`u`&&(globalThis.__applyBasePathCacheReset=te);function p(){let e=typeof window<`u`?window:typeof self<`u`?self:globalThis;if(e&&e.__SHADOWCLAW_DEPLOY_ID__){let t=String(e.__SHADOWCLAW_DEPLOY_ID__).trim();if(t)return t.replace(/[^a-zA-Z0-9_-]/g,`-`)}let t=globalThis.process;if(t&&t.env&&t.env.SHADOWCLAW_DEPLOY_ID){let e=String(t.env.SHADOWCLAW_DEPLOY_ID).trim();if(e)return e.replace(/[^a-zA-Z0-9_-]/g,`-`)}let n=m();return!n||n===`/`?``:n.replace(/^\/+|\/+$/g,``).replace(/[^a-zA-Z0-9_-]/g,`-`)}function m(){if(f!==null)return f;if((typeof window>`u`||globalThis.WorkerGlobalScope!==void 0&&typeof self<`u`&&self instanceof globalThis.WorkerGlobalScope)&&typeof self<`u`&&self.location){let e=(self.location.pathname||`/`).split(`/`).filter(Boolean);if(e.length<=1)return f=`/`,f;let t=e[0].toLowerCase(),n=t===`service-worker.js`||t===`sw.js`||t===`manifest.json`||t===`sitemap.xml`||t===`favicon.ico`||t===`index.html`||t===`service-worker`||t===`assets`||t===`dist`||t===`public`;if(n&&e.length===2)return f=`/`,f;if(!n)return f=`/`+e[0]+`/`,f}let e=typeof window<`u`&&window.location?window.location:typeof self<`u`&&self.location?self.location:null;if(!e)return`/`;if(typeof document<`u`&&typeof document.querySelector==`function`){let t=document.querySelector(`base[href]`);if(t){let n=t.getAttribute(`href`);if(n)try{let t=new URL(n,e.origin).pathname;return t.endsWith(`/`)||(t+=`/`),f=t,f}catch{}}}let t=e.pathname||`/`;if(t===`/`)return f=`/`,f;let n=t.split(`/`).filter(Boolean),r=n.findIndex(e=>ee.has(e.toLowerCase()));return r>=0?r===0?(f=`/`,f):(f=`/`+n.slice(0,r).join(`/`)+`/`,f):d(t)?(f=`/`,f):n.length===1&&!t.includes(`.`)?(f=`/`+n[0]+`/`,f):(f=`/`,f)}function ne(e){let t=e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`);return RegExp(`(^|\\s)@${t}\\b`,`i`)}ne(`ShadowClaw`);function re(){let e=p();return e?`shadowclaw-${e}`:`shadowclaw`}re();let h={github:{providerId:`github`,name:`GitHub`,aliases:[`github`,`api.github.com`],modes:[`oauth`,`token`],defaultMode:`oauth`,serviceTypes:[`http_api`,`git_remote`],authTypes:[`token`,`oauth`],tokenAuth:{token:{headerName:`Authorization`,headerPrefix:`token `},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}},oauth:{authorizeUrl:`https://github.com/login/oauth/authorize`,tokenUrl:`https://github.com/login/oauth/access_token`,defaultScopes:[`repo`,`read:user`],usePkce:!0,clientAuthMethod:`request_body`,scopeSeparator:`space`}},gitlab:{providerId:`gitlab`,name:`GitLab`,aliases:[`gitlab`,`gitlab.com`],modes:[`oauth`,`token`],defaultMode:`oauth`,serviceTypes:[`http_api`,`git_remote`],authTypes:[`token`,`oauth`],tokenAuth:{token:{headerName:`PRIVATE-TOKEN`,headerPrefix:``},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}},tokenAuthByServiceType:{git_remote:{token:{headerName:`Authorization`,headerPrefix:`Bearer `},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}}},oauth:{authorizeUrl:`https://gitlab.com/oauth/authorize`,tokenUrl:`https://gitlab.com/oauth/token`,defaultScopes:[`read_api`,`read_user`],usePkce:!0,clientAuthMethod:`request_body`,scopeSeparator:`space`}},figma:{providerId:`figma`,name:`Figma`,aliases:[`figma`,`api.figma.com`],modes:[`oauth`,`token`],defaultMode:`oauth`,serviceTypes:[`http_api`],authTypes:[`token`,`oauth`],tokenAuth:{token:{headerName:`X-Figma-Token`,headerPrefix:``},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}},oauth:{authorizeUrl:`https://www.figma.com/oauth`,tokenUrl:`https://api.figma.com/v1/oauth/token`,refreshUrl:`https://api.figma.com/v1/oauth/refresh`,defaultScopes:[],usePkce:!0,clientAuthMethod:`basic_header`,scopeSeparator:`space`}},notion:{providerId:`notion`,name:`Notion`,aliases:[`notion`,`api.notion.com`,`notion.so`],modes:[`oauth`,`token`],defaultMode:`oauth`,serviceTypes:[`http_api`],authTypes:[`token`,`oauth`],tokenAuth:{token:{headerName:`Authorization`,headerPrefix:`Bearer `},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}},oauth:{authorizeUrl:`https://api.notion.com/v1/oauth/authorize`,tokenUrl:`https://api.notion.com/v1/oauth/token`,defaultScopes:[],usePkce:!0,clientAuthMethod:`basic_header`,scopeSeparator:`space`}},microsoft_graph:{providerId:`microsoft_graph`,name:`Microsoft Graph`,aliases:[`microsoft`,`graph.microsoft.com`,`microsoft_graph`],modes:[`oauth`,`token`],defaultMode:`oauth`,serviceTypes:[`http_api`],authTypes:[`token`,`oauth`],tokenAuth:{token:{headerName:`Authorization`,headerPrefix:`Bearer `},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}},oauth:{authorizeUrl:`https://login.microsoftonline.com/common/oauth2/v2.0/authorize`,tokenUrl:`https://login.microsoftonline.com/common/oauth2/v2.0/token`,defaultScopes:[`openid`,`profile`,`offline_access`,`User.Read`],usePkce:!0,clientAuthMethod:`request_body`,scopeSeparator:`space`}},yahoo_mail:{providerId:`yahoo_mail`,name:`Yahoo Mail`,aliases:[`yahoo`,`yahoo_mail`,`mail.yahoo.com`],modes:[`oauth`,`token`],defaultMode:`oauth`,serviceTypes:[`http_api`],authTypes:[`token`,`oauth`],tokenAuth:{token:{headerName:`Authorization`,headerPrefix:`Bearer `},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}},oauth:{authorizeUrl:`https://api.login.yahoo.com/oauth2/request_auth`,tokenUrl:`https://api.login.yahoo.com/oauth2/get_token`,defaultScopes:[`mail-r`,`mail-w`],usePkce:!0,clientAuthMethod:`request_body`,scopeSeparator:`space`}},google:{providerId:`google`,name:`Google`,aliases:[`google`,`googleapis.com`],modes:[`oauth`,`token`],defaultMode:`oauth`,serviceTypes:[`http_api`],authTypes:[`token`,`oauth`],tokenAuth:{token:{headerName:`Authorization`,headerPrefix:`Bearer `},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}},oauth:{authorizeUrl:`https://accounts.google.com/o/oauth2/v2/auth`,tokenUrl:`https://oauth2.googleapis.com/token`,defaultScopes:[`openid`,`profile`,`email`],usePkce:!0,clientAuthMethod:`request_body`,scopeSeparator:`space`}},atlassian:{providerId:`atlassian`,name:`Atlassian`,aliases:[`atlassian`,`api.atlassian.com`],modes:[`oauth`,`token`,`basic`],defaultMode:`basic`,serviceTypes:[`http_api`,`git_remote`],authTypes:[`token`,`oauth`,`basic_userpass`],tokenAuth:{token:{headerName:`Authorization`,headerPrefix:`Bearer `},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `},basic:{headerName:`Authorization`,headerPrefix:`Basic `}},oauth:{authorizeUrl:`https://auth.atlassian.com/authorize`,tokenUrl:`https://auth.atlassian.com/oauth/token`,defaultScopes:[],usePkce:!0,clientAuthMethod:`request_body`,scopeSeparator:`space`}},slack:{providerId:`slack`,name:`Slack`,aliases:[`slack`,`slack.com`],modes:[`oauth`,`token`],defaultMode:`oauth`,serviceTypes:[`http_api`],authTypes:[`token`,`oauth`],tokenAuth:{token:{headerName:`Authorization`,headerPrefix:`Bearer `},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}},oauth:{authorizeUrl:`https://slack.com/oauth/v2/authorize`,tokenUrl:`https://slack.com/api/oauth.v2.access`,defaultScopes:[],usePkce:!1,clientAuthMethod:`request_body`,scopeSeparator:`comma`}},linear:{providerId:`linear`,name:`Linear`,aliases:[`linear`,`api.linear.app`,`linear.app`],modes:[`oauth`,`token`],defaultMode:`oauth`,serviceTypes:[`http_api`],authTypes:[`token`,`oauth`],tokenAuth:{token:{headerName:`Authorization`,headerPrefix:`Bearer `},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}},oauth:{authorizeUrl:`https://linear.app/oauth/authorize`,tokenUrl:`https://api.linear.app/oauth/token`,defaultScopes:[],usePkce:!0,clientAuthMethod:`request_body`,scopeSeparator:`space`}},azure_devops:{providerId:`azure_devops`,name:`Azure DevOps`,aliases:[`azure_devops`,`dev.azure.com`],modes:[`oauth`,`token`],defaultMode:`oauth`,serviceTypes:[`http_api`,`git_remote`],authTypes:[`token`,`oauth`,`basic_userpass`,`ssh_key`],tokenAuth:{token:{headerName:`Authorization`,headerPrefix:`Bearer `},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}},tokenAuthByServiceType:{git_remote:{token:{headerName:`Authorization`,headerPrefix:`Basic `},oauth:{headerName:`Authorization`,headerPrefix:`Basic `}}},oauth:{authorizeUrl:`https://app.vssps.visualstudio.com/oauth2/authorize`,tokenUrl:`https://app.vssps.visualstudio.com/oauth2/token`,defaultScopes:[`vso.code`,`vso.profile`,`offline_access`],usePkce:!1,clientAuthMethod:`request_body`,scopeSeparator:`space`}},custom_mcp:{providerId:`custom_mcp`,name:`Custom MCP`,aliases:[`custom_mcp`],modes:[`oauth`,`token`],defaultMode:`oauth`,serviceTypes:[`mcp_remote`,`webmcp_local`],authTypes:[`none`,`token`,`oauth`,`custom_header`,`ssh_key`],tokenAuth:{token:{headerName:`Authorization`,headerPrefix:`Bearer `},oauth:{headerName:`Authorization`,headerPrefix:`Bearer `}},oauth:{authorizeUrl:`https://example.com/oauth/authorize`,tokenUrl:`https://example.com/oauth/token`,defaultScopes:[],usePkce:!0,clientAuthMethod:`request_body`,scopeSeparator:`space`}}};Object.fromEntries(Object.values(h).filter(e=>!!e.oauth).map(e=>{let t=e.oauth;return[e.providerId,{id:e.providerId,name:e.name,authorizeUrl:t.authorizeUrl,tokenUrl:t.tokenUrl,redirectUri:t.redirectUri,defaultScopes:t.defaultScopes,usePkce:t.usePkce,clientAuthMethod:t.clientAuthMethod,scopeSeparator:t.scopeSeparator}]})),Object.fromEntries(Object.values(h).map(e=>[e.providerId,{providerId:e.providerId,modes:e.modes,defaultMode:e.defaultMode}])),new Promise(e=>{});
 /*! @license DOMPurify 3.4.13 | (c) Cure53 and other contributors | Released under the Apache license 2.0 and Mozilla Public License 2.0 | github.com/cure53/DOMPurify/blob/3.4.13/LICENSE */
 function g(e,t){(t==null||t>e.length)&&(t=e.length);for(var n=0,r=Array(t);n<t;n++)r[n]=e[n];return r}function ie(e){if(Array.isArray(e))return e}function _(e,t){var n=e==null?null:typeof Symbol<`u`&&e[Symbol.iterator]||e[`@@iterator`];if(n!=null){var r,i,a,o,s=[],c=!0,l=!1;try{if(a=(n=n.call(e)).next,t!==0)for(;!(c=(r=a.call(n)).done)&&(s.push(r.value),s.length!==t);c=!0);}catch(e){l=!0,i=e}finally{try{if(!c&&n.return!=null&&(o=n.return(),Object(o)!==o))return}finally{if(l)throw i}}return s}}function v(){throw TypeError(`Invalid attempt to destructure non-iterable instance.

package/dist/public/docs/guides/publishing-to-github-pages.md

@@ -0,0 +1,334 @@
+# Publishing to GitHub Pages
+
+> How to drive automated static-site publishing pipelines with ShadowClaw and GitHub Actions.
+
+ShadowClaw can drive a fully automated static-site publishing pipeline directly from the browser, with the only server-side requirement being a GitHub Actions workflow that runs the Node.js build.
+
+---
+
+## Deployment Strategies
+
+### Strategy A — Full fork
+
+Clone the entire ShadowClaw repository, add your pages to `pages/main/`, push to a new repo you own, and let CI build and deploy it.
+
+### Strategy B — Pages-only repo (Git clone & inject in CI)
+
+Your repo contains your content, an optional root-level `shadow-claw.config.json` (or `site-config.json`), and a GitHub Actions workflow. Content lives under `pages/`; the workflow checks out ShadowClaw as a build toolchain in CI and builds into `dist/public`.
+
+### Strategy C — NPM Package & CLI (`npx shadow-claw`)
+
+Run or deploy using the `shadow-claw` npm package directly:
+
+- Locally: `npx shadow-claw dev` (or `shadow-claw run`) to preview with dev server.
+- In CI: `npx shadow-claw build --prod` builds `dist/public` without needing to clone ShadowClaw or copy files.
+- In `package.json`: add `"shadow-claw": "^1.28.0"` as a devDependency and run `npm run build`.
+
+**Strategy B and Strategy C are both fully supported for content-only repositories and knowledge hubs.**
+
+---
+
+## Strategy B — Step-by-step
+
+### 1. Create a new GitHub repository
+
+Create an empty repo at `github.com/<you>/<your-site>`. Enable **Settings → Pages → Source: GitHub Actions**.
+
+### 2. Add the workflow
+
+Create `.github/workflows/deploy-pages.yml`:
+
+```yaml
+name: Build and Deploy via ShadowClaw
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      shadowclaw_version:
+        description: "ShadowClaw npm version (e.g. latest, 1.28.0)"
+        required: false
+        default: "latest"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+
+      - name: Build static site via ShadowClaw CLI
+        env:
+          PAGES_ORIGIN: "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"
+          PAGES_BASE_PATH: "/${{ github.event.repository.name }}/"
+        run: |
+          VERSION="${{ github.event.inputs.shadowclaw_version || 'latest' }}"
+          npx --yes "shadow-claw@$VERSION" build --prod
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist/public
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+### Version Pinning
+
+ShadowClaw builds via `npx --yes shadow-claw@latest build --prod`. To pin to a specific npm release, specify the version in `.github/workflows/deploy-pages.yml` or supply `shadowclaw_version` when triggering the GitHub Actions workflow manually.
+
+For a **custom apex domain** (e.g. `example.com`), override:
+
+```yaml
+PAGES_ORIGIN: "https://example.com/"
+PAGES_BASE_PATH: "/"
+```
+
+### 3. Add your content
+
+```text
+pages/
+  main/
+    index.html        ← home page
+    ~/content/
+      about.md        ← any other pages
+  routes.json         ← pretty-path config (optional)
+
+shadow-claw.config.json  ← branding, default tool settings, and build configuration (optional)
+```
+
+Site configurations can also specify tool defaults under `settings`:
+
+```json
+{
+  "settings": {
+    "defaultToolsProfile": "__builtin_default",
+    "enabledTools": ["javascript", "read_file", "write_file"]
+  }
+}
+```
+
+The `pages/` directory is optional. If it is absent, the build succeeds and ShadowClaw publishes its built-in `index.html` and `MEMORY.md` Pages content. Pretty paths are skipped unless a `routes.json` file is present.
+
+Minimal `pages/routes.json`:
+
+```json
+{
+  "routes": {
+    "/pages/main/index.html": { "prettyPath": "/main" },
+    "/pages/main/~/content/about.md": { "prettyPath": "/main/about" },
+    "/pages/main/MEMORY.md": { "prettyPath": "/main/memory" }
+  }
+}
+```
+
+> **Reserved path prefixes** — the following first-path-segments are owned by ShadowClaw's own router and **must not** be used as pretty path prefixes:
+> `/`, `/chat`, `/files`, `/tasks`, `/pages`, `/settings`, `/tools`, `/channels`.
+> `/` (root) is also reserved as the default pinned page and is unreachable as a pretty path. Use a safe namespace like `/main/`, `/articles/`, `/docs/`, or any custom prefix that doesn't collide with the list above.
+
+#### Default Pinned Page (`/`)
+
+When visitors navigate to the root URL (`/`) of your published site, ShadowClaw displays the **default pinned page**.
+
+**How ShadowClaw selects the default page for `/`:**
+
+1. Both the static site prerenderer (`prerender-dsd-shell`) and runtime page store (`orchestratorStore`) gather all page files in `pages/main/`. If `pages/main/` is absent, both use the built-in default `index.html` and `MEMORY.md` pages.
+2. `MEMORY.md` is always moved to the bottom of the list.
+3. All remaining pages are sorted by `pages.sortOrder` from `shadow-claw.config.json` (or `site-config.json`) (`"desc"` by default, natural numeric, or `"asc"`).
+4. The first file in this sorted list (`pages[0]`) becomes the default page rendered at `/`.
+
+**How to ensure your intended home page is rendered at `/`:**
+Name your landing page file so it sorts first in reverse-alphabetical order relative to other files in `pages/main/`:
+
+- `index.md` or `index.html` will sort ahead of `about.md`, `contact.md`, or `faq.md`.
+- If you have files starting with letters after `i` (e.g. `welcome.md`), `welcome.md` will sort ahead of `index.md`. Ensure your preferred landing page filename sorts highest in reverse-alphabetical order.
+
+### 4. Push — CI does the rest
+
+Every push to `main` triggers a build and deploys to `https://<you>.github.io/<your-site>/`.
+
+---
+
+## In-browser automation (no LLM, no server)
+
+ShadowClaw can publish to your content repo entirely from the browser using a `type: "tools"` task chain. The chain is deterministic — it makes **zero LLM calls**.
+
+### Prerequisites
+
+- Clone your content repo into the workspace: ask the agent to `git_clone https://github.com/<you>/<your-site>`, or do it manually.
+- Configure a GitHub Personal Access Token in **Settings → Git → PAT** (needs `repo` scope for private repos, `public_repo` for public ones).
+
+### Minimal publish chain
+
+```json
+{
+  "type": "tools",
+  "tools": [
+    {
+      "name": "write_file",
+      "input": {
+        "path": "repos/your-site/pages/main/post.md",
+        "content": "---\ntitle: My Post\n---\n\n# Hello World\n\nContent here."
+      }
+    },
+    {
+      "name": "git_add",
+      "input": {
+        "repo": "your-site",
+        "files": ["pages/main/post.md"]
+      }
+    },
+    {
+      "name": "git_commit",
+      "input": {
+        "repo": "your-site",
+        "message": "publish: new post"
+      }
+    },
+    {
+      "name": "git_push",
+      "input": {
+        "repo": "your-site"
+      }
+    }
+  ]
+}
+```
+
+### Fetch-transform-publish chain (fully automated data pipeline)
+
+This chain fetches an external data source, transforms it to markdown via the JavaScript sandbox, writes it as a page, and pushes — no human in the loop:
+
+```json
+{
+  "type": "tools",
+  "tools": [
+    {
+      "name": "fetch_url",
+      "input": {
+        "url": "https://api.github.com/repos/xt-ml/shadow-claw/releases/latest"
+      }
+    },
+    {
+      "name": "javascript",
+      "input": {
+        "code": "const match = $PIPE_DATA.match(/--- BEGIN EXTERNAL CONTENT[\\s\\S]*?---\\n([\\s\\S]*?)\\n--- END EXTERNAL CONTENT ---/); const raw = match ? match[1] : $PIPE_DATA; const rel = JSON.parse(raw); const date = rel.published_at?.slice(0, 10) ?? 'unknown'; return `---\\ntitle: ShadowClaw ${rel.tag_name}\\ndate: ${date}\\n---\\n\\n# ${rel.name}\\n\\nPublished: ${date}\\n\\n${rel.body ?? ''}`;",
+        "data": { "$pipe": "prev" }
+      }
+    },
+    {
+      "name": "write_file",
+      "input": {
+        "path": "repos/your-site/pages/main/release-notes.md",
+        "content": { "$pipe": "prev" }
+      }
+    },
+    {
+      "name": "git_add",
+      "input": {
+        "repo": "your-site",
+        "files": ["pages/main/release-notes.md"]
+      }
+    },
+    {
+      "name": "git_commit",
+      "input": {
+        "repo": "your-site",
+        "message": "shadow-claw[bot]: sync release notes"
+      }
+    },
+    {
+      "name": "git_push",
+      "input": {
+        "repo": "your-site"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Strategy C — NPM Package & CLI Workflow
+
+If you prefer building directly with `npx shadow-claw` without cloning the ShadowClaw repository in CI, use this minimal workflow:
+
+```yaml
+name: Build and Deploy via ShadowClaw CLI
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout content repo
+        uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Build production bundle
+        env:
+          NODE_ENV: production
+          PAGES_ORIGIN: "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"
+          PAGES_BASE_PATH: "/${{ github.event.repository.name }}/"
+        run: npx shadow-claw build --prod
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist/public
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+> **Tip:** Wrap this in a scheduled task (Tasks sidebar → New Task → type `tools`, set a cron interval) to run the pipeline automatically, e.g. every 24 hours. No LLM calls are made at execution time.
+
+---
+
+## Template repository
+
+A ready-to-fork starter template is available in the [`shadow-claw-template`](https://github.com/xt-ml/shadow-claw-template) repository. It contains the workflow, sample `pages/main/index.html`, `pages/main/~/content/about.md`, root-level `shadow-claw.config.json`, and `pages/routes.json`.

package/dist/public/docs/guides/server-development-configuration.md

@@ -123,6 +123,21 @@ npx shadow-claw dev --https --cert /path/to/cert.pem --key /path/to/key.pem
 npm start -- 8888 --https --cert /path/to/cert.pem --key /path/to/key.pem
 ```
 
+#### Manual TLS Certificate Generation (OpenSSL)
+
+To manually generate a self-signed certificate with Subject Alternative Name (SAN) extensions covering local hostnames and IP addresses:
+
+```bash
+openssl req -x509 -newkey rsa:2048 -nodes -days 398 \
+  -keyout .cache/tls/key.pem \
+  -out .cache/tls/cert.pem \
+  -subj "/CN=book" \
+  -addext "subjectAltName=DNS:exampleHostname,IP:192.168.1.200,DNS:localhost,IP:127.0.0.1" \
+  -addext "extendedKeyUsage=serverAuth"
+```
+
+Certificates placed in `.cache/tls/key.pem` and `.cache/tls/cert.pem` are automatically loaded when running with `--https` (via `SHADOWCLAW_SSL_DIR` / `config.sslDir`) without requiring explicit `--cert` or `--key` flags.
+
 ### Cache & Storage Configuration
 
 **Flags:** `--cache-dir`, `--tmp` / `--temp`, `-y` / `--yes`