// USER_GUIDE.md

DOCUMENTATION GET_STARTED_

Everything you need to know to work alongside your AI pair programmer. From setup to advanced features, this guide covers it all.

[001] THE_CONCEPT

AI-Native Editor

CORE_PRINCIPLE

Zaguán Blade is not just a text editor with a chat sidebar. It is designed from the ground up to allow an AI agent to "live" inside your editor.

It supports Local AI through Ollama and any OpenAI-compatible connection, so you can run models on your own machine or point to self-hosted gateways without changing your workflow.

👁

It sees what you see

The AI has access to your active files, cursor position, and project structure.

⚡

It acts

The AI can run terminal commands, edit files, and browse the web to find answers.

🤝

It collaborates

Instead of just pasting code chunks, the AI proposes changes directly in your file using "Diff Blocks" which you can review, accept, or reject.

[002] GETTING_STARTED

Quick Start Guide

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

3

Choose Storage Mode

When opening a project for the first time, select your preferred storage mode for conversation history.

Local Storage Server Storage
[003] THE_INTERFACE

Interface Overview

📁

Activity Bar

  • Files - Project file explorer
  • Git - Stage, commit, push
  • History - Browse file history
  • Settings - Preferences & account
💻

Center Stage

EDITOR

High-performance CodeMirror 6 editor with syntax highlighting. Diff Blocks appear inline when the AI proposes changes.

🤖

Right Panel

AI_ASSISTANT
  • Chat - Main communication channel
  • Model Selector - Choose AI model
  • Command Center - Type @ for special commands
⌨️

Bottom Panel

TERMINAL

Integrated terminal for running commands. The AI can see and interact with this terminal when executing commands.

[004] KEYBOARD_SHORTCUTS

Master the Keys

Global Shortcuts

F11Toggle fullscreen mode
Ctrl+WClose current tab
Ctrl+TabCycle to next tab
Ctrl+Shift+TabCycle to previous tab
EscapeClose modals/popups

File Operations

Ctrl+NNew File
Ctrl+OOpen Folder
Ctrl+SSave current file
Ctrl+Shift+SSave As
Alt+F4Exit application

Editor Shortcuts

Ctrl+ZUndo
Ctrl+Shift+ZRedo
Ctrl+FFind in file
F2Rename symbol
Ctrl+EToggle Edit/View mode (Markdown)

Chat Input

EnterSend message
Shift+EnterNew line (without sending)
Arrow Up/DownNavigate command suggestions
Tab or EnterSelect command from autocomplete
EscapeClose command autocomplete
[005] @_COMMANDS

Special Commands

Type @ in the chat input to access these special commands:

@web <url>

Fetches content from a URL and uses it as context for the AI. Great for referencing documentation or articles.

@research <topic>

Performs deep research on a topic and displays results in a new tab. AI-powered web research at your fingertips.

[006] WORKING_WITH_AI

AI Collaboration

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.

  • 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"

Reviewing Changes

When the AI writes code, it doesn't just overwrite your work. It proposes Edits.

  1. The AI will indicate it is writing code.
  2. You will see Green (added) and Red (removed) lines appear directly in your editor.
  3. Review the changes carefully.
  4. Accept/Reject: Click Accept (✓) to apply, or Reject (✗) to discard. Use "Accept All" or "Reject All" for multiple changes.
[007] SETTINGS

Configuration

👤

Account Tab

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

Storage Tab

  • Storage Mode - Local (.zblade/ folder) or Server storage
  • Sync Metadata - Sync conversation titles to server (no code)
  • Enable Cache - Cache recent context for faster access
  • Max Cache Size - Configure cache (10-500 MB)
🧠

Context Tab

PER-PROJECT
  • Max Context Tokens - Control context sent to AI (2K-32K)
  • Enable Compression - Remote (cloud) or Local compression
  • Allow .gitignored Files - Include gitignored files in AI context
[008] PROJECT_INSTRUCTIONS

Customize Your AI

Zaguán Blade creates a .zblade/ folder in your project with an instructions.md file. Edit this file to provide project-specific instructions to the AI.

.zblade/instructions.md markdown 
# Project Instructions

## Project Overview
<!-- Describe your project briefly -->

## Coding Guidelines
<!-- Add any specific coding conventions or patterns to follow -->

## Important Files
<!-- List key files the AI should be aware of -->

The AI reads this file to understand your project's conventions and requirements.

[009] EDITOR_FEATURES

Additional Features

Context Menu (Right-Click)

Cut / Copy / Paste Undo / Redo Find Rename Symbol Show Call Graph

File Explorer Context Menu

New File / Folder Rename Delete Cut / Copy / Paste Open in Terminal

Markdown Support

Markdown files automatically enable line wrapping. Use Ctrl+E to toggle between Edit and View modes.

[010] 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.

🖼

Capture Window

Select a window from the picker and attach a full screenshot of it.

✂

Capture Region

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

Platform Notes (Linux / X11)

On X11-based desktops (e.g., Openbox, i3, Fluxbox), window capture has the following limitations:

  • Current workspace only - The window picker only shows windows on your active workspace. Windows on other virtual desktops cannot be captured because X11 does not render off-screen windows.
  • Window must be visible - The target window must be visible and not fully obscured by another window. If a window is covered, the capture may return a black image. Click the window to bring it to the front before capturing.
  • Compositors help - If you run a compositor such as picom or compton, these limitations are largely eliminated - compositors maintain off-screen buffers for all windows, enabling capture of obscured or unfocused windows.

These limitations do not apply to Wayland desktops (GNOME, KDE Plasma 6) or macOS, which use compositing by default.

[011] PRIVACY_&_DATA

Your Data, Your Control

🚫

No Telemetry

Zaguán Blade does not collect usage telemetry.

🔒

Local Storage Mode

When using local storage, your code and conversations never leave your machine.

🔐

Server Storage Mode

Conversations are encrypted on Zaguán servers.

[012] 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.

Linux: ~/.config/zblade/prompts/[exact-model-name].md
Windows: %APPDATA%\zblade\prompts\[exact-model-name].md
macOS: ~/Library/Application Support/zblade/prompts/[exact-model-name].md
~/.config/zblade/prompts/glm-4.7-flash:Q4_K_M.md markdown 
You are an AI coding assistant in Zaguán Blade. Help users write, understand, and improve code efficiently.

# Core Rules

- When asked who and what you are, you are "glm-4.7-flash, an AI coding assistant in Zaguán Blade."
- Understand context before acting
- Match existing code style and conventions
- Verify libraries exist before using them (check imports, package.json, etc.)
- Use absolute file paths
- Read files before editing them
- Add comments sparingly - focus on "why" not "what"
- If unclear, ask for clarification

# Communication

- Be concise and direct
- Use markdown for code blocks
- No preamble ("Great!", "Certainly!")
- Jump straight to the task

# Available Tools

**get_workspace_structure** - Get project directory tree
**list_dir** - List files/directories in a path
**read_file** - Read file contents  
**write_file** - Create or overwrite a file
**apply_patch** - Replace specific content in a file (for edits)
**grep_search** - Search for patterns across files
**run_command** - Execute shell commands
**get_editor_state** - Get currently open file and cursor position

We encourage you to try Local AI and report any bugs or issues you encounter!

[013] TOOL_CALLS_REFERENCE

Tool Calls Reference

When creating custom system prompts for Local AI models, you'll need to include definitions for the tool calls Zaguán Blade supports. This reference document describes all available tools with their parameters and usage examples.

📖 View Complete Tool Calls Reference

Full documentation of all available tool calls for Local AI system prompts

 →
[014] KNOWN_BUGS

Known Issues

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

⚠️

Local AI Support

Local AI support may not work consistently in all scenarios. We're actively improving reliability.

📝

Search Functionality

Global search across project files is not yet implemented. The search icon has been hidden until this feature is ready.

📝

Diff/Patch View

The Diff/Patch view may not be 100% complete. Edge cases in code review might behave unexpectedly.

💾

Local Storage Mode

Local Storage Mode hasn't been extensively tested. Use with caution and report any issues.

Found a bug not listed here? Please report it on GitHub.

[015] SUPPORT_&_FEEDBACK

Alpha Release

FEATURE_INCOMPLETE

We define "Alpha" as "Feature incomplete, but good enough to be useful."

You will encounter bugs. When you do:

🐛 Report Bugs → 💡 Feature Requests →

Thank you for being part of the future of coding.