From af3c3b1d453e9f0271b69d74a01d81f2bdb94b87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stig-=C3=98rjan=20Smelror?= Date: Sun, 10 May 2026 21:34:56 +0200 Subject: [PATCH] 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. --- src/pages/changelog.astro | 1 + src/pages/docs.astro | 140 +++++++++++++++++++++++++++++++------- src/pages/tools.astro | 43 +++++++++--- 3 files changed, 153 insertions(+), 31 deletions(-) diff --git a/src/pages/changelog.astro b/src/pages/changelog.astro index 61067e7..6e46078 100644 --- a/src/pages/changelog.astro +++ b/src/pages/changelog.astro @@ -54,6 +54,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
  • Zaguán Coder Daemon. Fixed a bug where it reconnected to the provider in a longer session.
  • Zaguán Coder Daemon. Wired up zlp_request. It was planned, but missing.
  • Zaguán Coder Daemon. Fixed loading the History in Zaguán Blade.
    • +
  • File Explorer. Fixed a bug where moving files was not possible using the mouse.
    • diff --git a/src/pages/docs.astro b/src/pages/docs.astro index cf7ef2d..0c4e691 100644 --- a/src/pages/docs.astro +++ b/src/pages/docs.astro @@ -66,15 +66,20 @@ import BaseLayout from '../layouts/BaseLayout.astro';
    1
    -

    Get Your API Key

    -

    Visit ZaguanAI.com and subscribe to get your Zaguán API Key.

    -
    Without a valid API Key, Zaguán Blade functions as a standard, high-performance text editor.
    +

    Choose Your AI Path

    +

    Zaguán Blade supports both Local AI (private, no API key) and Cloud AI (faster hosted models). You can use either or both.

    +
    + Local AI + Cloud AI + Hybrid +
    2
    -

    Configure Account

    -

    Launch Zaguán Blade, click the Gear Icon (Settings) in the bottom-left corner, go to the Account tab, and paste your API Key.

    +

    Set Up Your AI Provider

    +

    For Local AI: Open Settings > Local AI and enable Ollama or an OpenAI-compatible server. No API key required.

    +

    For Cloud AI: Go to Settings > Account and add your Zaguán API key for hosted models.

    @@ -227,10 +232,14 @@ import BaseLayout from '../layouts/BaseLayout.astro';

    Context is Key

    -

    The AI automatically knows about the file you are currently looking at. You don't need to copy-paste code into the chat.

    +

    The AI automatically knows about your workspace context. You don't need to copy-paste code into the chat.

      -
    • Ask questions - "Explain this function", "Refactor this to be more performant", "Find the bug in this logic"
      • -
    • Tasking - "Create a new component for X", "Update the CSS to match this design", "Run the tests and fix the failure"
      • +
    • Active file - The file you are currently viewing
      • +
    • Open files - All open tabs in the editor
      • +
    • Cursor & selection - Your cursor position and any selected text
      • +
    • Mentioned paths - Files referenced via @path in chat
      • +
    • Diagnostics - Recent build errors and compiler warnings
      • +
    • Project structure - File tree and symbol index when needed
    @@ -248,23 +257,73 @@ import BaseLayout from '../layouts/BaseLayout.astro';
    + +
    +
    +
    [007] CHAT_MODES
    +

    Chat Modes

    +

    Zaguán Blade supports two chat modes accessible from the Command Center:

    + +
    +
    +
    Code Mode
    +

    The default mode for implementing and executing. The AI can read files, edit code, run terminal commands, and make changes to your project.

    +
    +
    +
    Planning Mode
    +

    Investigate and build a plan before coding. The AI explores your codebase, researches approaches, and proposes architecture — no edits or commands are executed.

    +
    +
    +
    Implement Action
    +

    After reviewing a plan in Planning mode, use Implement to convert the plan into a code-mode request and start building.

    +
    +
    +
    +
    +
    -
    [007] SETTINGS
    +
    [008] SETTINGS

    Configuration

    +
    +
    + ⚙ +

    Configuration

    +
    +
      +
    • Theme - Zaguán Dark, Blade Coder, Blade Cream, Blade Robot
      • +
    • Language - UI language preference
      • +
    • Markdown View - Toggle edit/view mode for markdown files
      • +
    +
    +
    👤

    Account Tab

      -
    • API Key - Your Zaguán subscription key for AI features
      • +
    • API Key - Your Zaguán subscription key for cloud AI models
    • Manage Subscription - Link to your account dashboard
    + +
    +
    + 🤖 +

    Local AI Tab

    +
    +
      +
    • Ollama - Connect to a local Ollama instance
      • +
    • Ollama Cloud - Connect to Ollama via ngrok/remote
      • +
    • OpenAI-compatible - Any OpenAI-compatible server endpoint
      • +
    • Test Connection - Verify your local AI setup
      • +
    • Refresh Models - Reload available models from providers
      • +
    +
    @@ -291,6 +350,19 @@ import BaseLayout from '../layouts/BaseLayout.astro';
  • Allow .gitignored Files - Include gitignored files in AI context
    • + +
    +
    + ℹ +

    About Tab

    +
    +
      +
    • Version - Current Zaguán Blade version
      • +
    • Runtime - Tauri runtime information
      • +
    • Engine - WebView engine details
      • +
    • Local-First - Privacy and data control details
      • +
    +
    @@ -298,7 +370,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
    -
    [008] PROJECT_INSTRUCTIONS
    +
    [009] PROJECT_INSTRUCTIONS

    Customize Your AI

    @@ -331,7 +403,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
    -
    [009] EDITOR_FEATURES
    +
    [010] EDITOR_FEATURES

    Additional Features

    @@ -368,7 +440,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
    -
    [010] SCREENSHOT_CAPTURE
    +
    [011] SCREENSHOT_CAPTURE

    Screenshot Capture

    Attach screenshots to your chat messages to give the AI visual context. Access capture options from the Feature Menu (grid icon) in the Command Center.

    @@ -383,6 +455,11 @@ import BaseLayout from '../layouts/BaseLayout.astro';

    Capture Region

    Select a window, then drag to crop a specific region from it.

    +
    +
    📤
    +

    Upload Image

    +

    Attach an existing image file to the chat conversation for visual context.

    +
    @@ -401,7 +478,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
    -
    [011] PRIVACY_&_DATA
    +
    [012] PRIVACY_&_DATA

    Your Data, Your Control

    @@ -410,6 +487,11 @@ import BaseLayout from '../layouts/BaseLayout.astro';

    No Telemetry

    Zaguán Blade does not collect usage telemetry.

    +
    +
    🤖
    +

    Local AI Privacy

    +

    Local AI models run entirely on your machine. Prompts and code never leave your computer when using Ollama or local OpenAI-compatible servers.

    +
    🔒

    Local Storage Mode

    @@ -418,7 +500,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
    🔐

    Server Storage Mode

    -

    Conversations are encrypted on Zaguán servers.

    +

    Conversations are encrypted on Zaguán servers. Cloud AI requests are processed on Zaguán infrastructure.

    @@ -427,25 +509,29 @@ import BaseLayout from '../layouts/BaseLayout.astro';
    -
    [012] LOCAL_AI_SYSTEM_PROMPTS
    +
    [013] LOCAL_AI_SYSTEM_PROMPTS

    Custom System Prompts

    - 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.

    - Linux: ~/.config/zblade/prompts/[exact-model-name].md + Linux: ~/.config/zblade/prompts/[model-name].md
    - Windows: %APPDATA%\zblade\prompts\[exact-model-name].md + Windows: %APPDATA%\zblade\prompts\[model-name].md
    - macOS: ~/Library/Application Support/zblade/prompts/[exact-model-name].md + macOS: ~/Library/Application Support/zblade/prompts/[model-name].md
    + +

    + Blade tries provider-qualified, stripped, lowercased, and base-model prompt filenames, so exact case and format is no longer required. +

    @@ -500,7 +586,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
    -
    [013] TOOL_CALLS_REFERENCE
    +
    [014] TOOL_CALLS_REFERENCE

    Tool Calls Reference

    @@ -525,7 +611,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
    -
    [014] KNOWN_BUGS
    +
    [015] KNOWN_BUGS

    Known Issues

    As an alpha release, there are some known limitations and bugs we're actively working on:

    @@ -564,7 +650,7 @@ import BaseLayout from '../layouts/BaseLayout.astro';
    -
    [015] SUPPORT_&_FEEDBACK
    +
    [016] SUPPORT_&_FEEDBACK

    Alpha Release

    @@ -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; diff --git a/src/pages/tools.astro b/src/pages/tools.astro index bd1989d..a6e1f47 100644 --- a/src/pages/tools.astro +++ b/src/pages/tools.astro @@ -38,6 +38,9 @@ import BaseLayout from '../layouts/BaseLayout.astro'; Directory & Search Editor Interaction Command Execution + Code Intelligence + Project Index + Composite Tools Result Handling Path Resolution System Prompt @@ -791,29 +794,53 @@ import BaseLayout from '../layouts/BaseLayout.astro'; run_command TERMINAL
    -

    Execute a shell command (requires user approval).

    +

    Execute a command in the workspace (requires user approval). Supports both legacy shell-line and structured program+args modes.

    -

    Parameters

    +

    Structured Mode (preferred)

    - - + + + +
    NameTypeDescription
    commandrequired stringShell command to execute
    cwdrequired stringWorking directory
    programrequired* stringExecutable path/name
    argsoptional arrayStructured arguments list
    shelloptional booleanForce shell execution (default: false in structured mode)
    cwdoptional stringWorking directory
    -
    -

    Example

    - 
    {
+              
    
+                
    Legacy Shell Mode
    
+                
+                  
+                  
+                    
+                    
+                    
+                    
+                  
+                
    NameTypeDescription
    commandrequired* stringShell command line to execute
    cwdoptional stringWorking directory
    blockingoptional booleanWait for completion (default: true)
    wait_ms_before_asyncoptional integerStartup wait when non-blocking
    
+              
    
+              
    
+                
    
+                  
    Structured (preferred)
    
+                  
    {
+  "program": "cargo",
+  "args": ["build", "--release"],
+  "cwd": "."
+}
    
+                
    
+                
    
+                  
    Legacy Shell
    
+                  
    {
   "command": "cargo build --release",
   "cwd": "."
 }
    
+                
    
               
    
               
    
                 ⚠️
-                
    This tool requires user confirmation before execution for safety.
    
+                
    This tool requires user confirmation before execution. Provide either command or program, not both.