PyPI - zerochat - Versions diffs - 7.3.0__py3-none-any.whl - Mend

zerochat 7.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (130) hide show

zerochat-7.3.0.dist-info/METADATA +70 -0
zerochat-7.3.0.dist-info/RECORD +130 -0
zerochat-7.3.0.dist-info/WHEEL +5 -0
zerochat-7.3.0.dist-info/entry_points.txt +2 -0
zerochat-7.3.0.dist-info/licenses/LICENSE +34 -0
zerochat-7.3.0.dist-info/top_level.txt +2 -0
zerochat.py +2004 -0
zerochat_runtime/__init__.py +1 -0
zerochat_runtime/assets/css/base.css +199 -0
zerochat_runtime/assets/css/components/composer.css +1258 -0
zerochat_runtime/assets/css/components/debug.css +777 -0
zerochat_runtime/assets/css/components/header.css +97 -0
zerochat_runtime/assets/css/components/icons.css +39 -0
zerochat_runtime/assets/css/components/markdown.css +685 -0
zerochat_runtime/assets/css/components/messages.css +473 -0
zerochat_runtime/assets/css/components/modals.css +1319 -0
zerochat_runtime/assets/css/components/sidebar.css +622 -0
zerochat_runtime/assets/css/components/tools.css +1223 -0
zerochat_runtime/assets/css/layout.css +171 -0
zerochat_runtime/assets/css/print.css +120 -0
zerochat_runtime/assets/css/styles.css +18 -0
zerochat_runtime/assets/css/theme-overrides.css +555 -0
zerochat_runtime/assets/css/tokens.css +165 -0
zerochat_runtime/assets/help/architecture.html +247 -0
zerochat_runtime/assets/help/composer.html +134 -0
zerochat_runtime/assets/help/conversations.html +105 -0
zerochat_runtime/assets/help/debug.html +108 -0
zerochat_runtime/assets/help/en/architecture.html +247 -0
zerochat_runtime/assets/help/en/composer.html +134 -0
zerochat_runtime/assets/help/en/conversations.html +104 -0
zerochat_runtime/assets/help/en/debug.html +105 -0
zerochat_runtime/assets/help/en/gemini-free.html +39 -0
zerochat_runtime/assets/help/en/index.html +191 -0
zerochat_runtime/assets/help/en/learning.html +71 -0
zerochat_runtime/assets/help/en/mcp.html +143 -0
zerochat_runtime/assets/help/en/openrouter-free.html +39 -0
zerochat_runtime/assets/help/en/profiles.html +173 -0
zerochat_runtime/assets/help/en/rag.html +130 -0
zerochat_runtime/assets/help/en/reasoning-telemetry.html +108 -0
zerochat_runtime/assets/help/en/tools-agent.html +133 -0
zerochat_runtime/assets/help/en/webllm.html +355 -0
zerochat_runtime/assets/help/gemini-free.html +39 -0
zerochat_runtime/assets/help/help.css +604 -0
zerochat_runtime/assets/help/help.js +51 -0
zerochat_runtime/assets/help/index.html +194 -0
zerochat_runtime/assets/help/learning.html +71 -0
zerochat_runtime/assets/help/mcp.html +143 -0
zerochat_runtime/assets/help/openrouter-free.html +39 -0
zerochat_runtime/assets/help/profiles.html +174 -0
zerochat_runtime/assets/help/rag.html +130 -0
zerochat_runtime/assets/help/reasoning-telemetry.html +111 -0
zerochat_runtime/assets/help/tools-agent.html +133 -0
zerochat_runtime/assets/help/webllm.html +359 -0
zerochat_runtime/assets/js/agent-core.js +1553 -0
zerochat_runtime/assets/js/api.js +844 -0
zerochat_runtime/assets/js/app.js +2558 -0
zerochat_runtime/assets/js/attachments.js +220 -0
zerochat_runtime/assets/js/charts.js +338 -0
zerochat_runtime/assets/js/chat-engine.js +566 -0
zerochat_runtime/assets/js/config-store.js +207 -0
zerochat_runtime/assets/js/context-manager.js +584 -0
zerochat_runtime/assets/js/conversation-service.js +484 -0
zerochat_runtime/assets/js/cookies.js +688 -0
zerochat_runtime/assets/js/data-reset-service.js +136 -0
zerochat_runtime/assets/js/debug.js +508 -0
zerochat_runtime/assets/js/defaults.js +16 -0
zerochat_runtime/assets/js/export.js +179 -0
zerochat_runtime/assets/js/file-parser.js +2088 -0
zerochat_runtime/assets/js/generation-controller.js +417 -0
zerochat_runtime/assets/js/i18n.js +1483 -0
zerochat_runtime/assets/js/icons.js +156 -0
zerochat_runtime/assets/js/ingestionEngine.js +436 -0
zerochat_runtime/assets/js/markdown.js +588 -0
zerochat_runtime/assets/js/mcp.js +1271 -0
zerochat_runtime/assets/js/message-turns.js +62 -0
zerochat_runtime/assets/js/profile-backup.js +118 -0
zerochat_runtime/assets/js/profile-export-bundle.js +481 -0
zerochat_runtime/assets/js/profile-repository.js +213 -0
zerochat_runtime/assets/js/providers-webllm.js +486 -0
zerochat_runtime/assets/js/providers.js +1560 -0
zerochat_runtime/assets/js/rag-index.js +295 -0
zerochat_runtime/assets/js/rag-service.js +530 -0
zerochat_runtime/assets/js/rag-ui.js +997 -0
zerochat_runtime/assets/js/ragStorage.js +676 -0
zerochat_runtime/assets/js/sandbox.js +449 -0
zerochat_runtime/assets/js/state.js +704 -0
zerochat_runtime/assets/js/storage-db.js +144 -0
zerochat_runtime/assets/js/tool-cards.js +330 -0
zerochat_runtime/assets/js/tool-security.js +653 -0
zerochat_runtime/assets/js/tools/README.md +50 -0
zerochat_runtime/assets/js/tools/builtin/agent-checkpoint.tool.js +212 -0
zerochat_runtime/assets/js/tools/builtin/download-pdf.tool.js +111 -0
zerochat_runtime/assets/js/tools/builtin/execute-javascript.tool.js +219 -0
zerochat_runtime/assets/js/tools/builtin/fetch-web-page.tool.js +112 -0
zerochat_runtime/assets/js/tools/builtin/list-documents.tool.js +117 -0
zerochat_runtime/assets/js/tools/builtin/read-knowledge-chunk.tool.js +129 -0
zerochat_runtime/assets/js/tools/builtin/read-knowledge-image.tool.js +95 -0
zerochat_runtime/assets/js/tools/builtin/render-chart.tool.js +90 -0
zerochat_runtime/assets/js/tools/builtin/search-knowledge-base.tool.js +124 -0
zerochat_runtime/assets/js/tools/builtin/search-web.tool.js +125 -0
zerochat_runtime/assets/js/tools/tool-manifest.js +53 -0
zerochat_runtime/assets/js/tools/tool-runtime.js +77 -0
zerochat_runtime/assets/js/ui-composer.js +319 -0
zerochat_runtime/assets/js/ui-conversation.js +655 -0
zerochat_runtime/assets/js/ui-dialogs.js +132 -0
zerochat_runtime/assets/js/ui-generation-status.js +119 -0
zerochat_runtime/assets/js/ui-inspector.js +804 -0
zerochat_runtime/assets/js/ui-mcp.js +604 -0
zerochat_runtime/assets/js/ui-profiles.js +824 -0
zerochat_runtime/assets/js/ui-reasoning.js +146 -0
zerochat_runtime/assets/js/ui-settings.js +825 -0
zerochat_runtime/assets/js/ui-shell.js +215 -0
zerochat_runtime/assets/js/ui-sidebar.js +429 -0
zerochat_runtime/assets/js/ui-telemetry.js +404 -0
zerochat_runtime/assets/js/ui-transfer.js +262 -0
zerochat_runtime/assets/js/utils.js +216 -0
zerochat_runtime/assets/js/vendor/orama.browser.js +11 -0
zerochat_runtime/assets/js/web-browser.js +569 -0
zerochat_runtime/assets/js/web-search.js +519 -0
zerochat_runtime/assets/manifest.webmanifest +20 -0
zerochat_runtime/assets/services/dummy_mcp/dummy_mcp_server.py +47 -0
zerochat_runtime/assets/services/dummy_mcp/service.json +22 -0
zerochat_runtime/assets/services/lsp/installer.json +9 -0
zerochat_runtime/assets/services/lsp/service.json +22 -0
zerochat_runtime/assets/services/memory/installer.json +9 -0
zerochat_runtime/assets/services/memory/service.json +24 -0
zerochat_runtime/assets/services/playwright/installer.json +10 -0
zerochat_runtime/assets/services/playwright/service.json +39 -0
zerochat_runtime/assets/sw.js +164 -0
zerochat_runtime/assets/zerochat.html +671 -0

zerochat_runtime/assets/help/en/index.html ADDED Viewed

@@ -0,0 +1,191 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Help & Documentation Center · ZeroChat</title>
+  <meta name="description" content="Complete user manual and technical documentation for ZeroChat: universal, autonomous, and private web client for AI models and local agents.">
+  <link rel="stylesheet" href="../help.css">
+</head>
+<body>
+  <div class="container">
+    <header>
+      <div class="header-top">
+        <a href="index.html" class="logo-badge">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 17l6-6-6-6M12 19h8"/></svg>
+          ZeroChat Docs
+        </a>
+        <div class="header-actions">
+          <div class="lang-switch">
+            <a href="../index.html" class="lang-link">Español</a> | <span class="lang-current">English</span>
+          </div>
+          <span class="top-nav-link">Version 7.x</span>
+        </div>
+      </div>
+      <h1>ZeroChat Help Center</h1>
+      <p class="subtitle">Reference guide and technical documentation to get the most out of your portable, private AI client.</p>
+    </header>
+    <div class="card">
+      <h2>What is ZeroChat?</h2>
+      <p>
+        <strong>ZeroChat</strong> is a standalone, secure, and portable web client designed to interact with artificial intelligence models, orchestrate autonomous multi-turn agents, and search local document knowledge bases.
+      </p>
+      <p>
+        Unlike conventional web apps, ZeroChat is served as a static web application (<code>zerochat.html</code>) that runs directly on GitHub Pages or any static web server with no heavy dependencies, database backends, or proxies. All your personal data, chat histories, profile credentials, and indexed documents remain strictly on your machine within your browser.
+      </p>
+      <div class="download-action-box">
+        <a href="../../zerochat.html" class="btn-open-app" id="btn-open-app">
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><polyline points="15 3 21 3 21 9"/><line x1="10" y1="14" x2="21" y2="3"/></svg>
+          Open ZeroChat (zerochat.html)
+        </a>
+        <span class="download-hint">Ready to use directly in your browser or connect with your local backend in <code>zerochat.py</code>.</span>
+      </div>
+      <div class="alert alert-info" style="margin-top: 1rem;">
+        <h3 style="margin-top: 0; margin-bottom: 0.5rem; font-size: 1.05rem;">Two Ways to Launch: Standalone Web vs. Local Backend</h3>
+        <ul style="margin: 0 0 0.5rem 1.25rem; padding: 0;">
+          <li>
+            <strong><code>zerochat.html</code> (Direct Web / PWA):</strong> Opens directly in any desktop or mobile browser (specifically optimized for Android as an installable PWA). By default it uses dark mode and, on mobile, keeps the conversation panel closed to prioritize the chat; both can be changed from the interface controls. Delivers commercial or local inference (WebLLM/WebGPU), in-browser RAG knowledge bases (Orama), Agent mode with a secure JS sandbox, and private IndexedDB storage without requiring Python, a terminal, or installation.
+          </li>
+          <li>
+            <strong><code>zerochat.py</code> (Local with Python backend):</strong> Background local server (port 6388 with a secure ephemeral token). Extends the web app with host operating system control: reading and editing local project files, executing terminal commands, and connecting external MCP servers (Playwright, LSP, memory).
+          </li>
+        </ul>
+        <div style="font-size: 0.9rem;">
+          <a href="architecture.html">View full technical comparison & capabilities in Architecture →</a>
+        </div>
+      </div>
+      <div class="alert alert-info" style="margin-top: 1rem;">
+        <h3 style="margin-top: 0; margin-bottom: 0.5rem; font-size: 1.05rem;">Quick download and launch</h3>
+        <p style="margin: 0.5rem 0;">
+          <strong>Download zerochat.py:</strong>
+          <a href="../../zerochat.py" download style="margin-left: 0.5rem;">zerochat.py</a>
+        </p>
+        <p style="margin: 0.5rem 0;"><strong>Run it directly (curl):</strong></p>
+        <div class="code-wrapper">
+          <pre><code>curl -sL https://albalday.github.io/zerochat/zerochat.py -o zerochat.py &amp;&amp; python3 zerochat.py</code></pre>
+        </div>
+      </div>
+      <div class="alert alert-info">
+        <strong>Self-learning project:</strong> ZeroChat was created to learn and experiment with AI and coding agents. <a href="learning.html">View the details →</a>
+      </div>
+    </div>
+    <div class="card">
+      <h2>System Features & Modules</h2>
+      <p>Explore each ZeroChat component below. Click any card to read its detailed technical guide:</p>
+      <div class="features-grid">
+        <!-- 1. Architecture & Portability -->
+        <a href="architecture.html" class="feature-card">
+          <div class="feature-icon-wrapper">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="2" y="3" width="20" height="14" rx="2"/><line x1="8" y1="21" x2="16" y2="21"/><line x1="12" y1="17" x2="12" y2="21"/></svg>
+          </div>
+          <div class="feature-title">Architecture & Portability</div>
+          <div class="feature-desc">Static web application served over HTTPS, local persistence in IndexedDB, and total data sovereignty without server middleware.</div>
+          <div class="feature-link">View detailed guide →</div>
+        </a>
+        <!-- 2. Connection Profiles -->
+        <a href="profiles.html" class="feature-card">
+          <div class="feature-icon-wrapper">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2"/><circle cx="9" cy="7" r="4"/><path d="M22 21v-2a4 4 0 0 0-3-3.87"/><path d="M16 3.13a4 4 0 0 1 0 7.75"/></svg>
+          </div>
+          <div class="feature-title">Profiles & Providers</div>
+          <div class="feature-desc">Connect with OpenAI, Ollama, OpenRouter, Claude, Gemini, and local Mirror with automated model and capability discovery.</div>
+          <div class="feature-link">View detailed guide →</div>
+        </a>
+        <!-- 3. WebLLM & WebGPU -->
+        <a href="webllm.html" class="feature-card">
+          <div class="feature-icon-wrapper">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/></svg>
+          </div>
+          <div class="feature-title">Local WebLLM Inference</div>
+          <div class="feature-desc">Execute models 100% inside the browser on your GPU via WebGPU, with catalog browsing, progressive downloading, and cache persistence.</div>
+          <div class="feature-link">View detailed guide →</div>
+        </a>
+        <!-- 4. Agent Mode & Tools -->
+        <a href="tools-agent.html" class="feature-card">
+          <div class="feature-icon-wrapper">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="11" width="18" height="10" rx="2"/><circle cx="12" cy="5" r="2"/><path d="M12 7v4"/><line x1="8" y1="16" x2="8" y2="16"/><line x1="16" y1="16" x2="16" y2="16"/></svg>
+          </div>
+          <div class="feature-title">Agent Mode & Tools</div>
+          <div class="feature-desc">Autonomous multi-turn loop with sandboxed JavaScript execution in Web Worker, web search, page fetching, and interactive SVG charts.</div>
+          <div class="feature-link">View detailed guide →</div>
+        </a>
+        <!-- 5. Local Knowledge RAG -->
+        <a href="rag.html" class="feature-card">
+          <div class="feature-icon-wrapper">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="12 2 2 7 12 12 22 7 12 2"/><polyline points="2 17 12 22 22 17"/><polyline points="2 12 12 17 22 12"/></svg>
+          </div>
+          <div class="feature-title">Local Knowledge (RAG)</div>
+          <div class="feature-desc">Ingest PDFs and documents into independent branches with vector and lexical indexing powered by Orama in the browser.</div>
+          <div class="feature-link">View detailed guide →</div>
+        </a>
+        <!-- 6. MCP Protocol -->
+        <a href="mcp.html" class="feature-card">
+          <div class="feature-icon-wrapper">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="2" y="2" width="20" height="8" rx="2"/><rect x="2" y="14" width="20" height="8" rx="2"/><line x1="6" y1="6" x2="6.01" y2="6"/><line x1="6" y1="18" x2="6.01" y2="18"/></svg>
+          </div>
+          <div class="feature-title">MCP Protocol</div>
+          <div class="feature-desc">Local server with file and terminal tools, external MCP services, and permission controls.</div>
+          <div class="feature-link">View detailed guide →</div>
+        </a>
+        <!-- 7. Debugging & Logs -->
+        <a href="debug.html" class="feature-card">
+          <div class="feature-icon-wrapper">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="4 17 10 11 4 5"/><line x1="12" y1="19" x2="20" y2="19"/></svg>
+          </div>
+          <div class="feature-title">Debugging & Interceptor</div>
+          <div class="feature-desc">Debug console with filters, a Raw view, and an interceptor for outgoing messages.</div>
+          <div class="feature-link">View detailed guide →</div>
+        </a>
+        <!-- 8. Conversations & History -->
+        <a href="conversations.html" class="feature-card">
+          <div class="feature-icon-wrapper">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>
+          </div>
+          <div class="feature-title">Conversations & Branching</div>
+          <div class="feature-desc">History, branches, search, and JSON, Markdown, or PDF export; JSON backup import.</div>
+          <div class="feature-link">View detailed guide →</div>
+        </a>
+        <!-- 9. Message Composer & Attachments -->
+        <a href="composer.html" class="feature-card">
+          <div class="feature-icon-wrapper">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>
+          </div>
+          <div class="feature-title">Composer & Multimedia</div>
+          <div class="feature-desc">Auto-expanding input textarea, keyboard shortcuts, and multi-format attachments (vision images, PDFs, source code, CSV, text).</div>
+          <div class="feature-link">View detailed guide →</div>
+        </a>
+        <!-- 10. Reasoning & Telemetry -->
+        <a href="reasoning-telemetry.html" class="feature-card">
+          <div class="feature-icon-wrapper">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9.5 2A2.5 2.5 0 0 1 12 4.5v15a2.5 2.5 0 0 1-4.96.44 2.5 2.5 0 0 1-2.96-3.08 3 3 0 0 1-.34-5.58 2.5 2.5 0 0 1 1.32-4.24 2.5 2.5 0 0 1 4.44-2.04z"/></svg>
+          </div>
+          <div class="feature-title">Reasoning & Telemetry</div>
+          <div class="feature-desc">Thinking effort control, agent checkpointing, and real-time monitoring of tokens, cache hit savings, and context window health.</div>
+          <div class="feature-link">View detailed guide →</div>
+        </a>
+      </div>
+    </div>
+    <footer>
+      <p>ZeroChat · Universal Web AI Client · User Manual</p>
+    </footer>
+  </div>
+  <script src="../help.js"></script>
+</body>
+</html>

zerochat_runtime/assets/help/en/learning.html ADDED Viewed

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Project and learning · ZeroChat Docs</title>
+  <meta name="description" content="Two learning tracks: building an AI client and learning to guide its development with agents.">
+  <link rel="stylesheet" href="../help.css">
+</head>
+<body>
+  <div class="container">
+    <header>
+      <div class="header-top">
+        <a href="index.html" class="logo-badge">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M4 17l6-6-6-6M12 19h8"/></svg>
+          ZeroChat Docs
+        </a>
+        <div class="header-actions">
+          <a href="../learning.html" class="top-nav-link" lang="es">Español</a>
+          <a href="index.html" class="top-nav-link">← Back to index</a>
+        </div>
+      </div>
+      <h1>Project and learning</h1>
+      <p class="subtitle">Two learning tracks: building an AI client and learning to guide its development with agents.</p>
+    </header>
+    <main>
+      <p>ZeroChat is a personal learning project about AI clients and agentic execution. The work combines clear goals, decision review, and result validation.</p>
+    <section class="card">
+      <h2>1. Learning chat client technology</h2>
+      <p>The journey goes from a simple prompt-built chat client to one with local knowledge and tools:</p>
+      <ul>
+        <li><strong>Chat and providers:</strong> SSE streaming, reasoning, vision and API adaptation through a shared provider architecture.</li>
+        <li><strong>Data and documents:</strong> IndexedDB persistence, PDF extraction and retrieval-augmented generation (RAG) with Orama and ZeroChatDB.</li>
+        <li><strong>Agentic execution:</strong> tool loops, JavaScript isolated in Web Workers, MCP, permissions and a local server with development tools.</li>
+        <li><strong>Inference and context:</strong> caching, token limits and checkpoints for long conversations, plus models running inside the browser with WebLLM and WebGPU.</li>
+        <li><strong>Shared desktop and mobile UI:</strong> responsive web design, navigation, and shared controls that provide a consistent experience across desktop screens and mobile devices.</li>
+      </ul>
+    </section>
+    <section class="card">
+      <h2>2. Learning to guide coding agents</h2>
+      <p>As the infrastructure grows—browser, storage, providers, MCP server, and local backend—learning also means keeping control of the whole system:</p>
+      <ul>
+        <li><strong>Plan before executing:</strong> define scope, stages, acceptance criteria and the tests that will confirm the outcome before requesting a change.</li>
+        <li><strong>Turn decisions into rules:</strong> document architecture, contracts and the workflow to guide the agent, with centralized state in <code>ChatState</code> and separate responsibilities.</li>
+        <li><strong>Discuss and simplify with the model:</strong> question proposals, reuse modules and remove unnecessary complexity before it becomes permanent infrastructure.</li>
+        <li><strong>Verify each step:</strong> use unit, infrastructure, integration, and browser tests alongside security audits to check real behavior.</li>
+      </ul>
+      <h3>Automated tests as a checkpoint</h3>
+      <p>Tests are the checkpoint at every stage of work with coding agents. Before implementation, they define what must remain stable and what must change; during the work, they check the affected module; when a stage closes, the full suite confirms that the change has not broken other system boundaries. Interface changes are checked in the browser and integration changes in local server infrastructure tests. If a test fails, the agent must correct or simplify the proposal before moving forward.</p>
+      <p>The plan is to keep repeating this cycle: choose a capability, agree on a simple design, assign scoped changes, review tests and document what was learned.</p>
+    </section>
+      <p>This plan summarizes the project's practical evolution and quality criteria.</p>
+    </main>
+    <nav class="page-navigation" aria-label="Help navigation">
+      <a href="index.html" class="nav-button index">
+        <span class="nav-direction">Back to index</span>
+        <span class="nav-title">View all topics</span>
+      </a>
+    </nav>
+    <footer>
+      <p>ZeroChat · Project and learning</p>
+    </footer>
+  </div>
+</body>
+</html>

zerochat_runtime/assets/help/en/mcp.html ADDED Viewed

@@ -0,0 +1,143 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Model Context Protocol (MCP) · ZeroChat Help</title>
+  <meta name="description" content="MCP guide for ZeroChat: the local server, tools, external services, and permissions.">
+  <link rel="stylesheet" href="../help.css">
+</head>
+<body>
+  <div class="container">
+    <header>
+      <div class="header-top">
+        <a href="index.html" class="logo-badge">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 17l6-6-6-6M12 19h8"/></svg>
+          ZeroChat Docs
+        </a>
+        <div class="header-actions">
+          <a href="../mcp.html" class="top-nav-link">Español 🌐</a>
+          <a href="index.html" class="top-nav-link">← Back to Index</a>
+        </div>
+      </div>
+      <h1>Model Context Protocol (MCP)</h1>
+      <p class="subtitle">Use tools on your computer and external MCP services from ZeroChat, with the local server and authorization controls built in.</p>
+    </header>
+    <div class="card">
+      <p>Local tools use <code>zmcp_&lt;tool&gt;</code> and external tools use <code>mcp_&lt;service&gt;_&lt;tool&gt;</code>, for example <code>mcp_browser_service_browser_navigate</code>. Permissions are stored under this full name: authorizing a tool does not authorize its namesake in another service. Legacy aliases are not supported. Special characters are encoded to prevent collisions.</p>
+    </div>
+    <div class="card">
+      <h2>1. What is MCP?</h2>
+      <p>
+        The <strong>Model Context Protocol (MCP)</strong> is an open protocol championed by Anthropic to bridge AI models with external tools and databases through a standardized interface.
+      </p>
+      <p>
+        In ZeroChat, <code>zerochat.py</code> starts a local server on <code>127.0.0.1</code>, opens the app with a session token, and the browser connects automatically. A remote MCP URL is not configured manually. The server provides file and terminal tools and hosts the external MCP services that you enable in the app.
+      </p>
+    </div>
+    <div class="card">
+      <h2>2. Connection & UI Indicators</h2>
+      <p>
+        Open <strong>Settings → MCP</strong> to check the local-server status and discovered tools:
+      </p>
+      <ul>
+        <li><strong>Disconnected:</strong> The local server is not available. Keep <code>zerochat.py</code> running and reload the page if it was restarted.</li>
+        <li><strong>Connected:</strong> ZeroChat has discovered the local tools and can list available external MCP services.</li>
+      </ul>
+      <p>
+        There is no manual connection form or button. Run the command below and open the app from the link started by the script. The session token protects requests to the local server; do not share that URL or token.
+      </p>
+    </div>
+    <div class="card">
+      <h2>3. Local Python Server (zerochat.py)</h2>
+      <p>
+        ZeroChat consolidates all local backend functionality into a single executable script: <code>zerochat.py</code>.
+      </p>
+      <p>
+        When executed, <code>zerochat.py</code> verifies the version, automatically creates and manages a virtual environment in <code>./zerochat</code>, starts the local SSE server, and launches your browser pointing to <code>zerochat.html</code> with an ephemeral session token.
+      </p>
+      <p>
+        <strong>Core Local Tools:</strong>
+      </p>
+      <ul>
+        <li><strong><code>execute_command</code>:</strong> Unified shell terminal for Git, CLI, test execution, and compilation, with automatic OS and environment diagnosis.</li>
+        <li><strong><code>read_file</code>:</strong> Safe file reading with line range slicing and context token limits.</li>
+        <li><strong><code>edit_file</code>:</strong> Atomic file writing and editing (overwrite, append, or chunk replacement).</li>
+        <li><strong><code>list_directory</code>:</strong> Structured folder tree and metadata exploration.</li>
+      </ul>
+      <p>
+        <strong>Session Token Security:</strong> All requests from <code>zerochat.html</code> require the ephemeral session token generated by <code>zerochat.py</code> at startup. Without this valid token, the local server rejects any incoming connection.
+      </p>
+      <div class="code-wrapper">
+        <pre><code># Download and launch the ZeroChat local backend
+curl -sL https://albalday.github.io/zerochat/zerochat.py -o zerochat.py &amp;&amp; python3 zerochat.py</code></pre>
+      </div>
+    </div>
+    <div class="card">
+      <h2>4. Tool Permissions & Authorization Policies</h2>
+      <p>
+        Because local tools can perform sensitive operations on your system (such as modifying files or running shell commands), ZeroChat provides granular security controls for each tool:
+      </p>
+      <p>
+        Open <strong>Settings → Permissions</strong> to choose the global policy, review remembered decisions, and clear them when needed. In the MCP panel you can also choose <em>Ask</em>, <em>Allow</em>, or <em>Deny</em> for each tool.
+      </p>
+      <ul>
+        <li><strong>On/Off Switches:</strong> Enable or disable each tool sent to the model without stopping the server.</li>
+        <li><strong>Authorization Policy:</strong>
+          <ul>
+            <li><em>Ask for authorization (recommended):</em> ZeroChat pauses to ask for explicit approval.</li>
+            <li><em>Allow all:</em> Any tool runs without confirmation. Use it only in a trusted environment.</li>
+          </ul>
+        </li>
+      </ul>
+      <div class="alert alert-warning">
+        <strong>Local network security:</strong> Make sure your MCP server binds strictly to the loopback interface <code>127.0.0.1</code> and not <code>0.0.0.0</code> when working on untrusted public networks.
+      </div>
+    </div>
+    <div class="card">
+      <h2>5. External MCP Services & Individual Activation</h2>
+      <p>
+        The local <code>zerochat.py</code> server manages external MCP services defined in <code>services/</code>. You do not need to run a global external daemon: start and stop each service from ZeroChat.
+      </p>
+      <p>
+        In <strong>Settings → MCP</strong>, <em>"Available MCP Servers"</em> lets you start or stop each service and configure its options. When starting one, ZeroChat installs dependencies when needed, discovers its tools, and adds them to the panel. Node.js-based services require Node.js 18 or later and npm.
+      </p>
+      <p>
+        The local server provides ready-to-use definitions in <code>services/</code>:
+      </p>
+      <ul>
+        <li><code>dummy_mcp</code>: Minimal test service in pure Python without external dependencies.</li>
+        <li><code>playwright</code>: Browser automation with the official Playwright MCP server; the <em>Headless</em> option controls whether a browser window is shown.</li>
+        <li><code>memory</code>: Knowledge graph and structured persistent memory.</li>
+        <li><code>lsp</code>: Language Server Protocol for code navigation and type inspection.</li>
+      </ul>
+    </div>
+    <nav class="page-navigation" aria-label="Help navigation">
+      <a href="rag.html" class="nav-button prev">
+        <span class="nav-direction">← Previous</span>
+        <span class="nav-title">Local Knowledge (RAG)</span>
+      </a>
+      <a href="index.html" class="nav-button index">
+        <span class="nav-direction">Index</span>
+        <span class="nav-title">View all topics</span>
+      </a>
+      <a href="debug.html" class="nav-button next">
+        <span class="nav-direction">Next →</span>
+        <span class="nav-title">Debugging & Interceptor</span>
+      </a>
+    </nav>
+    <footer>
+      <p>ZeroChat · Universal Web AI Client · User Manual</p>
+    </footer>
+  </div>
+  <script src="../help.js"></script>
+</body>
+</html>

zerochat_runtime/assets/help/en/openrouter-free.html ADDED Viewed

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>OpenRouter API key · ZeroChat</title>
+  <meta name="description" content="How to create an OpenRouter API key for use in ZeroChat.">
+  <link rel="stylesheet" href="../help.css">
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>Get an OpenRouter API key</h1>
+      <p class="subtitle">Create an OpenRouter key for use in ZeroChat.</p>
+    </header>
+    <main>
+      <section class="card">
+        <h2>Steps</h2>
+        <ol>
+          <li>
+            Open <a href="https://openrouter.ai/keys" target="_blank" rel="noopener noreferrer">OpenRouter’s official API keys page</a> and sign in or create an account.
+          </li>
+          <li>Select <strong>Create API Key</strong> or <strong>Create Key</strong>.</li>
+          <li>Enter a recognizable name, such as <code>ZeroChat</code>, and create the key.</li>
+          <li>Copy the key immediately and store it privately. OpenRouter shows its complete value only once.</li>
+          <li>In ZeroChat, create or edit an <strong>OpenRouter</strong> provider profile, paste the key, and choose a model.</li>
+        </ol>
+      </section>
+      <section class="card">
+        <h2>Important</h2>
+        <p>Models, limits, and prices change. Always check <a href="https://openrouter.ai/models" target="_blank" rel="noopener noreferrer">OpenRouter's current catalog and terms</a> before production use.</p>
+        <p>Never share the API key or publish it in chats, screenshots, repositories, or public configuration files.</p>
+      </section>
+    </main>
+  </div>
+</body>
+</html>

zerochat_runtime/assets/help/en/profiles.html ADDED Viewed

@@ -0,0 +1,173 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Profiles & AI Providers · ZeroChat Help</title>
+  <meta name="description" content="Guide for configuring connection profiles in ZeroChat: OpenAI, Ollama, LM Studio, OpenRouter, Anthropic Claude, Google Gemini, WebLLM, and Mirror profile.">
+  <link rel="stylesheet" href="../help.css">
+</head>
+<body>
+  <div class="container">
+    <header>
+      <div class="header-top">
+        <a href="index.html" class="logo-badge">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 17l6-6-6-6M12 19h8"/></svg>
+          ZeroChat Docs
+        </a>
+        <div class="header-actions">
+          <a href="../profiles.html" class="top-nav-link">Español 🌐</a>
+          <a href="index.html" class="top-nav-link">← Back to Index</a>
+        </div>
+      </div>
+      <h1>Profiles & AI Providers</h1>
+      <p class="subtitle">Learn how to connect ZeroChat with any language model, running either on your machine or in the cloud.</p>
+    </header>
+    <div class="card">
+      <h2>1. Connection Profile Management</h2>
+      <p>
+        ZeroChat lets you define multiple <strong>connection profiles</strong>. A profile encapsulates the API protocol type, server endpoint URL, authentication key (optional for local servers), and selected model name.
+      </p>
+      <p>
+        To manage profiles, click the active profile name in the header. The selector lets you create and export profiles, close the menu, and edit or delete each listed profile. Selecting one makes it active.
+      </p>
+      <div class="alert alert-info">
+        <strong>Instant switching:</strong> You can switch models or providers mid-conversation without losing context. Simply open the profile dropdown and select another one.
+      </div>
+      <p>
+        The profile selector lets you <strong>Export</strong> all editable definitions. It downloads an encrypted HTML file: open it to start importing into ZeroChat. After confirmation, new profiles are added and matching identifiers are updated without changing the Mirror profile.
+      </p>
+      <p>
+        API keys are encrypted in the browser's local profile storage and remain encrypted inside the backup, which adds a second encryption layer. The <strong>Lock changes</strong> checkbox, located in the editor header, marks a profile as non-editable when it is loaded again; the lock protects all profile settings. Changes are saved using the <strong>Save</strong> button in the modal header.
+      </p>
+      <div class="alert alert-warning">
+        <strong>Transport protection:</strong> the master key is embedded in ZeroChat to make profile reuse convenient. Encryption prevents keys from being visible when opening the file, but it must not be considered protection against someone who has access to the application source. Share these backups only through trusted channels.
+      </div>
+    </div>
+    <div class="card">
+      <h2>2. Supported Providers & Protocols</h2>
+      <div class="table-responsive">
+        <table>
+          <thead>
+            <tr>
+              <th>Interface Type</th>
+              <th>Common Servers & Services</th>
+              <th>Typical Endpoint</th>
+              <th>API Key</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td><strong>OpenAI / Compatible</strong></td>
+              <td>LM Studio, LocalAI, vLLM, official OpenAI</td>
+              <td><code>http://localhost:1234/v1</code></td>
+              <td>Optional on local / Required on OpenAI</td>
+            </tr>
+            <tr>
+              <td><strong>Ollama</strong></td>
+              <td>Local Ollama server</td>
+              <td><code>http://localhost:11434</code></td>
+              <td>Not required</td>
+            </tr>
+            <tr>
+              <td><strong>OpenRouter</strong></td>
+              <td>OpenRouter multi-model gateway</td>
+              <td><code>https://openrouter.ai/api/v1</code></td>
+              <td>Required (<code>sk-or-...</code>)</td>
+            </tr>
+            <tr>
+              <td><strong>Anthropic Claude</strong></td>
+              <td>Official Anthropic API</td>
+              <td><code>https://api.anthropic.com/v1</code></td>
+              <td>Required (<code>sk-ant-...</code>)</td>
+            </tr>
+            <tr>
+              <td><strong>Google Gemini</strong></td>
+              <td>Google AI Studio</td>
+              <td>Gemini OpenAI-compatible endpoint</td>
+              <td>Required</td>
+            </tr>
+            <tr>
+              <td><strong>WebLLM</strong></td>
+              <td>In-browser direct (WebGPU)</td>
+              <td><code>webllm://local</code> (automated)</td>
+              <td>Not applicable (100% local)</td>
+            </tr>
+            <tr>
+              <td><strong>Mirror (Espejo)</strong></td>
+              <td>Internal offline testing</td>
+              <td>No endpoint (simulated mode)</td>
+              <td>Not applicable</td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+    </div>
+    <div class="card">
+      <h2>3. Server Inspection (Query Button) & Validation</h2>
+      <p>
+        When creating or editing a profile, ZeroChat provides a <strong>Query</strong> button next to the URL input. This inspects the server before saving:
+      </p>
+      <ul>
+        <li><strong>Model discovery:</strong> Fetches the available models catalog and populates the dropdown automatically.</li>
+        <li><strong>Capability inspection:</strong> Verifies if the model supports vision, function calling (tools), native reasoning, and advertised context capacity.</li>
+        <li><strong>Save protection:</strong> For remote APIs or local HTTP endpoints, ZeroChat requires a successful Query before saving to ensure the connection works properly.</li>
+      </ul>
+      <div class="alert alert-success">
+        <strong>Fast save on WebLLM:</strong> When selecting an already downloaded WebLLM model from local cache, the <em>Query</em> button is optional, allowing you to save the profile immediately.
+      </div>
+    </div>
+    <div class="card">
+      <h2>4. Special Configuration for Ollama (CORS)</h2>
+      <p>
+        When connecting to <strong>Ollama</strong>, browsers will block requests due to CORS (Cross-Origin Resource Sharing) unless Ollama is started with cross-origin access enabled:
+      </p>
+      <div class="code-wrapper">
+        <pre><code># On Linux / macOS (terminal)
+OLLAMA_ORIGINS="*" ollama serve
+# On Windows (PowerShell)
+$env:OLLAMA_ORIGINS="*"
+ollama serve</code></pre>
+      </div>
+      <p>If running Ollama as a systemd service on Linux, add <code>Environment="OLLAMA_ORIGINS=*"</code> under the <code>[Service]</code> section.</p>
+    </div>
+    <div class="card">
+      <h2>5. The Built-in "Mirror" Profile</h2>
+      <p>
+        ZeroChat includes a read-only <strong>Mirror (Espejo)</strong> profile. It is ideal for UI testing and troubleshooting:
+      </p>
+      <ul>
+        <li>Makes zero network calls and needs no local server running.</li>
+        <li>Returns an immediate formatted preview of the normalized OpenAI-compatible payload.</li>
+        <li>Serves as a reliable fallback whenever an active profile is deleted or inaccessible.</li>
+      </ul>
+    </div>
+    <nav class="page-navigation" aria-label="Help navigation">
+      <a href="architecture.html" class="nav-button prev">
+        <span class="nav-direction">← Previous</span>
+        <span class="nav-title">Architecture & Portability</span>
+      </a>
+      <a href="index.html" class="nav-button index">
+        <span class="nav-direction">Index</span>
+        <span class="nav-title">View all topics</span>
+      </a>
+      <a href="webllm.html" class="nav-button next">
+        <span class="nav-direction">Next →</span>
+        <span class="nav-title">Local WebLLM Inference</span>
+      </a>
+    </nav>
+    <footer>
+      <p>ZeroChat · Universal Web AI Client · User Manual</p>
+    </footer>
+  </div>
+  <script src="../help.js"></script>
+</body>
+</html>