You've already forked zblade.dev
docs(website): add Local AI setup guide and chat modes docs
Restructure getting started to cover Local AI and Cloud AI options with Hybrid support. Add Chat Modes section documenting Code Mode, Planning Mode, and Implement Action. Expand Settings with Local AI tab, Configuration, and Experiments details. Update tools page and add changelog entry for File Explorer drag-to-move fix.
This commit is contained in:
@@ -54,6 +54,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<li><strong>Zaguán Coder Daemon.</strong> Fixed a bug where it reconnected to the provider in a longer session.</li>
|
||||
<li><strong>Zaguán Coder Daemon.</strong> Wired up <code>zlp_request</code>. It was planned, but missing.</li>
|
||||
<li><strong>Zaguán Coder Daemon.</strong> Fixed loading the History in Zaguán Blade.</li>
|
||||
<li><strong>File Explorer.</strong> Fixed a bug where moving files was not possible using the mouse.</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
+117
-23
@@ -66,15 +66,20 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<div class="steps-grid">
|
||||
<div class="step-card step-highlight">
|
||||
<div class="step-num">1</div>
|
||||
<h3>Get Your API Key</h3>
|
||||
<p>Visit <a href="https://zaguanai.com/pricing" target="_blank" rel="noopener">ZaguanAI.com</a> and subscribe to get your Zaguán API Key.</p>
|
||||
<div class="step-note">Without a valid API Key, Zaguán Blade functions as a standard, high-performance text editor.</div>
|
||||
<h3>Choose Your AI Path</h3>
|
||||
<p>Zaguán Blade supports both <strong>Local AI</strong> (private, no API key) and <strong>Cloud AI</strong> (faster hosted models). You can use either or both.</p>
|
||||
<div class="step-options">
|
||||
<span class="option-tag option-recommended">Local AI</span>
|
||||
<span class="option-tag">Cloud AI</span>
|
||||
<span class="option-tag">Hybrid</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-num">2</div>
|
||||
<h3>Configure Account</h3>
|
||||
<p>Launch Zaguán Blade, click the <strong>Gear Icon</strong> (Settings) in the bottom-left corner, go to the <strong>Account</strong> tab, and paste your API Key.</p>
|
||||
<h3>Set Up Your AI Provider</h3>
|
||||
<p><strong>For Local AI:</strong> Open <strong>Settings > Local AI</strong> and enable Ollama or an OpenAI-compatible server. No API key required.</p>
|
||||
<p class="step-or"><strong>For Cloud AI:</strong> Go to <strong>Settings > Account</strong> and add your Zaguán API key for hosted models.</p>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
@@ -227,10 +232,14 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<div class="ai-content">
|
||||
<div class="ai-block">
|
||||
<h3>Context is Key</h3>
|
||||
<p>The AI automatically knows about the file you are currently looking at. You don't need to copy-paste code into the chat.</p>
|
||||
<p>The AI automatically knows about your workspace context. You don't need to copy-paste code into the chat.</p>
|
||||
<ul>
|
||||
<li><strong>Ask questions</strong> - "Explain this function", "Refactor this to be more performant", "Find the bug in this logic"</li>
|
||||
<li><strong>Tasking</strong> - "Create a new component for X", "Update the CSS to match this design", "Run the tests and fix the failure"</li>
|
||||
<li><strong>Active file</strong> - The file you are currently viewing</li>
|
||||
<li><strong>Open files</strong> - All open tabs in the editor</li>
|
||||
<li><strong>Cursor & selection</strong> - Your cursor position and any selected text</li>
|
||||
<li><strong>Mentioned paths</strong> - Files referenced via <code>@path</code> in chat</li>
|
||||
<li><strong>Diagnostics</strong> - Recent build errors and compiler warnings</li>
|
||||
<li><strong>Project structure</strong> - File tree and symbol index when needed</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
@@ -248,23 +257,73 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Chat Modes Section -->
|
||||
<section id="chat-modes" class="docs-section section-alt">
|
||||
<div class="container">
|
||||
<div class="section-label">[007] CHAT_MODES</div>
|
||||
<h2 class="section-title">Chat Modes</h2>
|
||||
<p class="section-desc">Zaguán Blade supports two chat modes accessible from the <strong>Command Center</strong>:</p>
|
||||
|
||||
<div class="commands-grid">
|
||||
<div class="command-card">
|
||||
<div class="command-syntax">Code Mode</div>
|
||||
<p>The default mode for implementing and executing. The AI can read files, edit code, run terminal commands, and make changes to your project.</p>
|
||||
</div>
|
||||
<div class="command-card">
|
||||
<div class="command-syntax">Planning Mode</div>
|
||||
<p>Investigate and build a plan before coding. The AI explores your codebase, researches approaches, and proposes architecture — no edits or commands are executed.</p>
|
||||
</div>
|
||||
<div class="command-card">
|
||||
<div class="command-syntax">Implement Action</div>
|
||||
<p>After reviewing a plan in Planning mode, use <strong>Implement</strong> to convert the plan into a code-mode request and start building.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Settings Section -->
|
||||
<section id="settings" class="docs-section">
|
||||
<div class="container">
|
||||
<div class="section-label">[007] SETTINGS</div>
|
||||
<div class="section-label">[008] SETTINGS</div>
|
||||
<h2 class="section-title">Configuration</h2>
|
||||
|
||||
<div class="settings-grid">
|
||||
<div class="setting-card">
|
||||
<div class="setting-header">
|
||||
<span class="setting-icon">⚙</span>
|
||||
<h3>Configuration</h3>
|
||||
</div>
|
||||
<ul>
|
||||
<li><strong>Theme</strong> - Zaguán Dark, Blade Coder, Blade Cream, Blade Robot</li>
|
||||
<li><strong>Language</strong> - UI language preference</li>
|
||||
<li><strong>Markdown View</strong> - Toggle edit/view mode for markdown files</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="setting-card">
|
||||
<div class="setting-header">
|
||||
<span class="setting-icon">👤</span>
|
||||
<h3>Account Tab</h3>
|
||||
</div>
|
||||
<ul>
|
||||
<li><strong>API Key</strong> - Your Zaguán subscription key for AI features</li>
|
||||
<li><strong>API Key</strong> - Your Zaguán subscription key for cloud AI models</li>
|
||||
<li><strong>Manage Subscription</strong> - Link to your account dashboard</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="setting-card">
|
||||
<div class="setting-header">
|
||||
<span class="setting-icon">🤖</span>
|
||||
<h3>Local AI Tab</h3>
|
||||
</div>
|
||||
<ul>
|
||||
<li><strong>Ollama</strong> - Connect to a local Ollama instance</li>
|
||||
<li><strong>Ollama Cloud</strong> - Connect to Ollama via ngrok/remote</li>
|
||||
<li><strong>OpenAI-compatible</strong> - Any OpenAI-compatible server endpoint</li>
|
||||
<li><strong>Test Connection</strong> - Verify your local AI setup</li>
|
||||
<li><strong>Refresh Models</strong> - Reload available models from providers</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="setting-card">
|
||||
<div class="setting-header">
|
||||
@@ -291,6 +350,19 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<li><strong>Allow .gitignored Files</strong> - Include gitignored files in AI context</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="setting-card">
|
||||
<div class="setting-header">
|
||||
<span class="setting-icon">ℹ</span>
|
||||
<h3>About Tab</h3>
|
||||
</div>
|
||||
<ul>
|
||||
<li><strong>Version</strong> - Current Zaguán Blade version</li>
|
||||
<li><strong>Runtime</strong> - Tauri runtime information</li>
|
||||
<li><strong>Engine</strong> - WebView engine details</li>
|
||||
<li><strong>Local-First</strong> - Privacy and data control details</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
@@ -298,7 +370,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<!-- Project Instructions Section -->
|
||||
<section id="project-instructions" class="docs-section section-alt">
|
||||
<div class="container">
|
||||
<div class="section-label">[008] PROJECT_INSTRUCTIONS</div>
|
||||
<div class="section-label">[009] PROJECT_INSTRUCTIONS</div>
|
||||
<h2 class="section-title">Customize Your AI</h2>
|
||||
|
||||
<div class="instructions-content">
|
||||
@@ -331,7 +403,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<!-- Editor Features Section -->
|
||||
<section id="features" class="docs-section">
|
||||
<div class="container">
|
||||
<div class="section-label">[009] EDITOR_FEATURES</div>
|
||||
<div class="section-label">[010] EDITOR_FEATURES</div>
|
||||
<h2 class="section-title">Additional Features</h2>
|
||||
|
||||
<div class="features-list">
|
||||
@@ -368,7 +440,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<!-- Screenshot Capture Section -->
|
||||
<section id="screenshot" class="docs-section section-alt">
|
||||
<div class="container">
|
||||
<div class="section-label">[010] SCREENSHOT_CAPTURE</div>
|
||||
<div class="section-label">[011] SCREENSHOT_CAPTURE</div>
|
||||
<h2 class="section-title">Screenshot Capture</h2>
|
||||
<p class="section-desc">Attach screenshots to your chat messages to give the AI visual context. Access capture options from the <strong>Feature Menu</strong> (grid icon) in the Command Center.</p>
|
||||
|
||||
@@ -383,6 +455,11 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<h3>Capture Region</h3>
|
||||
<p>Select a window, then drag to crop a specific region from it.</p>
|
||||
</div>
|
||||
<div class="screenshot-card">
|
||||
<div class="screenshot-icon">📤</div>
|
||||
<h3>Upload Image</h3>
|
||||
<p>Attach an existing image file to the chat conversation for visual context.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="screenshot-notes">
|
||||
@@ -401,7 +478,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<!-- Privacy Section -->
|
||||
<section id="privacy" class="docs-section">
|
||||
<div class="container">
|
||||
<div class="section-label">[011] PRIVACY_&_DATA</div>
|
||||
<div class="section-label">[012] PRIVACY_&_DATA</div>
|
||||
<h2 class="section-title">Your Data, Your Control</h2>
|
||||
|
||||
<div class="privacy-grid">
|
||||
@@ -410,6 +487,11 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<h3>No Telemetry</h3>
|
||||
<p>Zaguán Blade does not collect usage telemetry.</p>
|
||||
</div>
|
||||
<div class="privacy-item">
|
||||
<div class="privacy-icon">🤖</div>
|
||||
<h3>Local AI Privacy</h3>
|
||||
<p>Local AI models run entirely on your machine. Prompts and code never leave your computer when using Ollama or local OpenAI-compatible servers.</p>
|
||||
</div>
|
||||
<div class="privacy-item">
|
||||
<div class="privacy-icon">🔒</div>
|
||||
<h3>Local Storage Mode</h3>
|
||||
@@ -418,7 +500,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<div class="privacy-item">
|
||||
<div class="privacy-icon">🔐</div>
|
||||
<h3>Server Storage Mode</h3>
|
||||
<p>Conversations are encrypted on Zaguán servers.</p>
|
||||
<p>Conversations are encrypted on Zaguán servers. Cloud AI requests are processed on Zaguán infrastructure.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -427,25 +509,29 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<!-- Local AI System Prompts Section -->
|
||||
<section id="local-ai-prompts" class="docs-section">
|
||||
<div class="container">
|
||||
<div class="section-label">[012] LOCAL_AI_SYSTEM_PROMPTS</div>
|
||||
<div class="section-label">[013] LOCAL_AI_SYSTEM_PROMPTS</div>
|
||||
<h2 class="section-title">Custom System Prompts</h2>
|
||||
|
||||
<div class="instructions-content">
|
||||
<p class="instructions-intro">
|
||||
When using Local AI models (Ollama or OpenAI-compatible), you can customize the system prompt for each model by creating a file with the exact model name.
|
||||
When using Local AI models (Ollama or OpenAI-compatible), you can customize the system prompt for each model by creating a file with the model name or a compatible fallback name.
|
||||
</p>
|
||||
|
||||
<div class="prompt-paths">
|
||||
<div class="prompt-path-item">
|
||||
<strong>Linux:</strong> <code class="inline-code">~/.config/zblade/prompts/[exact-model-name].md</code>
|
||||
<strong>Linux:</strong> <code class="inline-code">~/.config/zblade/prompts/[model-name].md</code>
|
||||
</div>
|
||||
<div class="prompt-path-item">
|
||||
<strong>Windows:</strong> <code class="inline-code">%APPDATA%\zblade\prompts\[exact-model-name].md</code>
|
||||
<strong>Windows:</strong> <code class="inline-code">%APPDATA%\zblade\prompts\[model-name].md</code>
|
||||
</div>
|
||||
<div class="prompt-path-item">
|
||||
<strong>macOS:</strong> <code class="inline-code">~/Library/Application Support/zblade/prompts/[exact-model-name].md</code>
|
||||
<strong>macOS:</strong> <code class="inline-code">~/Library/Application Support/zblade/prompts/[model-name].md</code>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p class="instructions-note">
|
||||
Blade tries provider-qualified, stripped, lowercased, and base-model prompt filenames, so exact case and format is no longer required.
|
||||
</p>
|
||||
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
@@ -500,7 +586,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<!-- Tool Calls Reference Section -->
|
||||
<section id="tool-calls" class="docs-section section-alt">
|
||||
<div class="container">
|
||||
<div class="section-label">[013] TOOL_CALLS_REFERENCE</div>
|
||||
<div class="section-label">[014] TOOL_CALLS_REFERENCE</div>
|
||||
<h2 class="section-title">Tool Calls Reference</h2>
|
||||
|
||||
<div class="instructions-content">
|
||||
@@ -525,7 +611,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<!-- Known Bugs Section -->
|
||||
<section id="known-bugs" class="docs-section section-alt">
|
||||
<div class="container">
|
||||
<div class="section-label">[014] KNOWN_BUGS</div>
|
||||
<div class="section-label">[015] KNOWN_BUGS</div>
|
||||
<h2 class="section-title">Known Issues</h2>
|
||||
<p class="section-desc">As an alpha release, there are some known limitations and bugs we're actively working on:</p>
|
||||
|
||||
@@ -564,7 +650,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<!-- Support Section -->
|
||||
<section id="support" class="docs-section">
|
||||
<div class="container">
|
||||
<div class="section-label">[015] SUPPORT_&_FEEDBACK</div>
|
||||
<div class="section-label">[016] SUPPORT_&_FEEDBACK</div>
|
||||
<div class="support-card">
|
||||
<div class="support-header">
|
||||
<h2>Alpha Release</h2>
|
||||
@@ -817,6 +903,14 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
padding-top: var(--space-sm);
|
||||
border-top: 1px solid var(--color-border);
|
||||
}
|
||||
|
||||
.step-or {
|
||||
font-size: 0.85rem;
|
||||
color: var(--color-text-secondary);
|
||||
margin-top: var(--space-sm);
|
||||
padding-top: var(--space-sm);
|
||||
border-top: 1px dashed var(--color-border);
|
||||
}
|
||||
|
||||
.step-options {
|
||||
display: flex;
|
||||
|
||||
+35
-8
@@ -38,6 +38,9 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<a href="#directory-search" class="nav-chip">Directory & Search</a>
|
||||
<a href="#editor-interaction" class="nav-chip">Editor Interaction</a>
|
||||
<a href="#command-execution" class="nav-chip">Command Execution</a>
|
||||
<a href="#code-intelligence" class="nav-chip">Code Intelligence</a>
|
||||
<a href="#project-index" class="nav-chip">Project Index</a>
|
||||
<a href="#composite-tools" class="nav-chip">Composite Tools</a>
|
||||
<a href="#tool-result-handling" class="nav-chip">Result Handling</a>
|
||||
<a href="#path-resolution" class="nav-chip">Path Resolution</a>
|
||||
<a href="#system-prompt-integration" class="nav-chip">System Prompt</a>
|
||||
@@ -791,29 +794,53 @@ import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
<span class="tool-name">run_command</span>
|
||||
<span class="tool-tag">TERMINAL</span>
|
||||
</div>
|
||||
<p class="tool-desc">Execute a shell command (requires user approval).</p>
|
||||
<p class="tool-desc">Execute a command in the workspace (requires user approval). Supports both legacy shell-line and structured program+args modes.</p>
|
||||
</div>
|
||||
<div class="tool-body">
|
||||
<div class="tool-params">
|
||||
<h4>Parameters</h4>
|
||||
<h4>Structured Mode (preferred)</h4>
|
||||
<table class="params-table">
|
||||
<thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td><code>command</code></td><td><span class="type-badge req">required</span> string</td><td>Shell command to execute</td></tr>
|
||||
<tr><td><code>cwd</code></td><td><span class="type-badge req">required</span> string</td><td>Working directory</td></tr>
|
||||
<tr><td><code>program</code></td><td><span class="type-badge req">required*</span> string</td><td>Executable path/name</td></tr>
|
||||
<tr><td><code>args</code></td><td><span class="type-badge opt">optional</span> array</td><td>Structured arguments list</td></tr>
|
||||
<tr><td><code>shell</code></td><td><span class="type-badge opt">optional</span> boolean</td><td>Force shell execution (default: false in structured mode)</td></tr>
|
||||
<tr><td><code>cwd</code></td><td><span class="type-badge opt">optional</span> string</td><td>Working directory</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<div class="tool-example">
|
||||
<h4>Example</h4>
|
||||
<pre is:raw><code>{
|
||||
<div class="tool-params">
|
||||
<h4>Legacy Shell Mode</h4>
|
||||
<table class="params-table">
|
||||
<thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td><code>command</code></td><td><span class="type-badge req">required*</span> string</td><td>Shell command line to execute</td></tr>
|
||||
<tr><td><code>cwd</code></td><td><span class="type-badge opt">optional</span> string</td><td>Working directory</td></tr>
|
||||
<tr><td><code>blocking</code></td><td><span class="type-badge opt">optional</span> boolean</td><td>Wait for completion (default: true)</td></tr>
|
||||
<tr><td><code>wait_ms_before_async</code></td><td><span class="type-badge opt">optional</span> integer</td><td>Startup wait when non-blocking</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<div class="tool-examples-row">
|
||||
<div class="tool-example">
|
||||
<h4>Structured (preferred)</h4>
|
||||
<pre is:raw><code>{
|
||||
"program": "cargo",
|
||||
"args": ["build", "--release"],
|
||||
"cwd": "."
|
||||
}</code></pre>
|
||||
</div>
|
||||
<div class="tool-example">
|
||||
<h4>Legacy Shell</h4>
|
||||
<pre is:raw><code>{
|
||||
"command": "cargo build --release",
|
||||
"cwd": "."
|
||||
}</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="tool-note tool-note-warning">
|
||||
<span class="note-icon">⚠️</span>
|
||||
<p class="note-text">This tool requires user confirmation before execution for safety.</p>
|
||||
<p class="note-text">This tool requires user confirmation before execution. Provide either <code>command</code> or <code>program</code>, not both.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Reference in New Issue
Block a user