# AnnexCode – User Manual ## 1. Overview AnnexCode is the web and code editor of the AnnexCREATE suite. It is built for freelancers, self-employed professionals, and small agencies who build websites and small web projects and publish them to their own web space. Key benefits at a glance: - **Everything in one window**: syntax editor, WYSIWYG HTML preview, Bootstrap components, local development servers, an integrated terminal, and an FTP workflow in the suite's familiar three-column layout. - **A preview that works with you**: the HTML preview renders the project with all its CSS files, can be checked in three viewports, and writes text edits straight back into the source code. - **Publishing without extra tools**: manage server connections, upload files via FTP, and compare local and remote files in the FTP perspective. - **AI assistance your way**: locally via Ollama or LM Studio, or through cloud providers (Claude, Kimi, Codex) with API keys stored in the macOS Keychain. AnnexCode is part of the AnnexCREATE "Creative OS": the design system, asset library, brand kits, clipboard, licensing, and diagnostics are shared with all other apps in the suite. ## 2. Installation & Activation AnnexCode is installed and managed through **AnnexHub**: 1. Open AnnexHub and select AnnexCode in the **Apps** area (⌘1 in AnnexHub). 2. Install or update – updates are shown in AnnexHub, including changelogs. 3. Activate your license in AnnexHub under **Licenses**: online with a license key, or offline via a signed activation file. **Offline-first**: AnnexCode runs without a server connection. The editor, preview, local servers, terminal, and project work all function fully offline. You only need server access for license updates in AnnexHub, uploading to your web space, and cloud AI providers. ## 3. Basic Workflow The typical path from launch to a published page: 1. **Create or open a file**: new HTML file via `File ▸ New` (⌘N), or load an existing `.axcode` project via `File ▸ Open…` (⌘O). 2. **Work in the editor**: write code with syntax highlighting; use the editor's search bar to find and replace when needed. 3. **Insert components**: drag ready-made Bootstrap components (e.g. Navbar, Hero, Card) from the sidebar into the preview or the source, and adjust them in the inspector. 4. **Check the preview**: review the WYSIWYG preview in the Desktop, Tablet, and Mobile viewports; text edits can be made directly in the preview. 5. **Start a local server**: for PHP, Node.js, or Python projects, start the matching development server and point the preview at the server URL. 6. **Save**: store the project via `File ▸ Save…` (⌘S) as an `.axcode` container. 7. **Set up a connection**: create a server connection in the connection manager (FTP, SFTP, or WebDAV; the password goes into the macOS Keychain). 8. **Upload**: upload the active file with the toolbar button – or compare the sync state of all files in the FTP perspective first. ## 4. Core Features ### Editor, Syntax Highlighting, and Find & Replace The editor (`SyntaxTextEditor`) opens files in tabs and highlights syntax for HTML, CSS, JavaScript, PHP, Python, JSON, XML, Swift, and Rust. A toggleable search bar lets you find text in the active file and replace single matches or all at once. The editor is intentionally lean: no autocompletion, no linting, no debugger, no Git integration. ### File Import Text files (html, htm, css, js, php, py, json, xml, swift, rs, md, txt, csv, yaml, yml) open directly as editor files on import. Images, vectors, and PDFs go through the suite's central import engine and are stored in the project as linked assets with a description file. ### WYSIWYG HTML Preview The preview (WKWebView) renders the active HTML file combined with all CSS files in the project. You can switch between the Desktop (1200), Tablet (768), and Mobile (375) viewports, and in edit mode change text directly in the preview – the change is written back into the HTML source. It works the other way around, too: clicking an element in the preview jumps to the matching spot in the code and highlights it with the native find indicator, without stealing focus from the preview (the jump is not available in the localhost view, which has no element mapping). If a local server is running, the preview can optionally show its URL instead of the static rendering. ### Components Panel and Inspector The components panel holds ten ready-made Bootstrap components: Navbar, Hero, Card, Button, Form, Footer, Grid Row, Alert, Section, and Image. Drag them into the preview or the source; the inspector edits their properties (text, image, color, URL, boolean) and writes the changes straight into the HTML. ### Local Development Servers and Package Manager Per project you can start, stop, and restart the PHP built-in server, a Node.js server (with `npm start` detection), or Python's `http.server`. Ports are assigned automatically from the range 8100–8199, and the combined stdout/stderr log is kept per project. Running servers are stopped automatically when you quit the app. Depending on the tech stack, you install packages from within the app: `npm install` (Node.js projects) or `composer install` (PHP projects); output and exit codes appear in a dedicated sheet. ### Integrated Terminal A terminal panel can be shown at the bottom of the window: via the toolbar or `View ▸ Toggle Terminal` (⌃⌘T). It starts a shell session in the project directory with line-based input (deliberately not an interactive pseudo-terminal). Output is displayed append-only, with a history limit and a marker when output is truncated. Abort running commands with the Ctrl-C equivalent; processes are terminated cleanly when the panel is closed. ### Server Connections and Deployment In the connection manager you create and edit server connections; passwords are stored in the macOS Keychain and never written into the project. Start uploading the active file with the toolbar button, which shows progress; the picker offers FTP, SFTP, and WebDAV (listing, upload, and download over all three protocols). The **FTP perspective** compares your local project files with the remote listing and shows a per-file sync status (synced, local newer, remote newer, conflict, missing locally, missing remotely). Upload or download individual files directly from the comparison. It is a manual comparison – no auto-sync. ### Google Codes The snippet generator creates codes for Google Analytics 4, Google Ads, Search Console, and Tag Manager and inserts them at the correct position (head/body) in `index.html`. If an entry for the same service and account already exists, it is replaced. The codes are stored as project metadata. ### AI Chat Panel The AI panel supports five provider slots: Ollama and LM Studio locally (no API key), plus Claude, Kimi, and Codex in the cloud (API key in the macOS Keychain). Endpoint and model are freely configurable. The active editor file can be attached to requests as context; from the editor, context actions are available: explain code, refactor, and generate unit tests. ### Assets, Brand Kits, and Clipboard The suite-wide asset library lives in the sidebar; dragging a text file from it onto the editor opens it as a file. Link brand kits to the project in the inspector – their assets appear as a separate sidebar section with quick access (copy asset path). The Annex clipboard copies file contents with a text fallback for other apps and registers links between files and assets. ### Menu Bar and Keyboard Shortcuts AnnexCode uses real macOS menus: - `File ▸ New` – new empty HTML file (⌘N) - `File ▸ Open…` – open an `.axcode` container (⌘O) - `File ▸ Save…` – always shows the save panel (⌘S) - `AnnexCode ▸ Settings…` (⌘,) - `View ▸ Toggle Terminal` (⌃⌘T) Upload is started via the toolbar button or with ⌘U (opens the upload dialog for the active file). ### Settings and Localization Settings combine the suite options (theme/color scheme, diagnostics, privacy) plus a section for AI providers. The interface is localized in German, English, Spanish, French, and Italian (default: German). ## 5. Formats & Interoperability **Native format `.axcode`** in two variants: - **Annex container**: stores a snapshot of the project (files, connections without passwords, project URL, brand kit links). Saving and loading are wired in the app (`File ▸ Save…` / `File ▸ Open…`). - **Project package**: a directory with `project.json` containing the tech stack (Plain HTML, Bootstrap 5, Tailwind CDN, Node.js Static, PHP + Composer), project metadata, Google codes, and the project files. Loading project packages is currently available through the model API or the MCP host. **Import**: text formats (see section 4) as well as images, vectors, and PDFs as linked assets via the suite import engine. There is no dedicated file export (e.g. as ZIP or static HTML) – files leave the app via container saving, upload, or the clipboard. **Working with the suite**: - Annex clipboard with text fallback to other Annex apps and third-party apps. - Shared asset library and brand kit links, including asset linking through the LinkedObject registry. - Connections can carry client and project IDs – a hook into suite management. - On save, the document is written to the shared version index and therefore appears in AnnexHub's central search. iCloud/cloud sync is not wired. ## 6. MCP Control AnnexCode can be controlled through the MCP host, which runs in **AnnexHub** (JSON-RPC 2.0 via STDIO) and is started from there. This allows AI agents to automate the app's actions. Suite tools (for all apps): - `list_apps` – lists all available Annex apps with installation status and version. - `open_app` – opens an Annex app by its ID. - `open_document` – opens a file in the given Annex app. - `get_active_document` – returns information about an app's active document. - `get_license_status` – returns the license status of an Annex product. - `search_assets` – searches the central asset library by name or tags. App-specific tool: - `code.open_file` – opens a file in AnnexCode. Skills (suite-wide): `suite.discover`, `brandkit.apply`. ## 7. Diagnostics & Privacy AnnexCode logs errors and actions locally via `AnnexLog` into rotating JSON log files under `~/Library/Logs/AnnexCREATE/AnnexCode/`, mirrored to `os_log` (subsystem `com.annexcreative.annexcode`). Logs are written with a PII filter – no paths, file names, or email addresses. Diagnostics are enabled by default during the development phase and can be switched off in Settings (Privacy); nothing is transmitted. Telemetry runs strictly on opt-in (default: off) and can be toggled at runtime in Settings. Passwords for server connections and API keys for AI providers are stored in the macOS Keychain. ## 8. FAQ **Do I need an internet connection to work?** No. The editor, preview, local servers, terminal, and project work all run offline. You only need network access for uploads, cloud AI, and license/update functions in AnnexHub. **Can I upload via SFTP or WebDAV?** Yes. FTP, SFTP, and WebDAV are all available in the connection picker; listing, upload, and download work over all three protocols – including in the FTP perspective. **Where are my FTP passwords stored?** In the macOS Keychain. They are never written into the project or the `.axcode` container. **Is there Git integration, linting, or autocompletion?** No – the editor is deliberately lean. For version control and checks, use external tools, for example via the integrated terminal. **Does the AI work without a cloud provider?** Yes. With Ollama or LM Studio, the AI panel runs locally with no API key. **How do I export my project as a ZIP or finished website?** There is no dedicated file export. Your files live in the project directory and leave the app via container saving, upload to your server, or the clipboard. **What is the difference between the `.axcode` container and the project package?** The container is a single document holding a snapshot of the project state; the project package is a directory with `project.json` and all project files. The open dialog currently supports the container. **Does the FTP perspective sync automatically?** No. It is a manual comparison: you see the sync status per file and upload or download individual files selectively.