chore: updated documentation

DOCUMENTATION.md

@@ -13,10 +13,12 @@
 - [Using scripting](#using-scripting)
 - [Using the AI assistant](#using-the-ai-assistant)
 - [Organizing with tags](#organizing-with-tags)
+- [Using blogmarks](#using-blogmarks)
 - [Importing from WordPress (WXR)](#importing-from-wordpress-wxr)
 - [Using Git (Source Control)](#using-git-source-control)
 - [Configuring settings](#configuring-settings)
-- [Publishing in bDS (current scope)](#publishing-in-bds-current-scope)
+- [Managing templates](#managing-templates)
+- [Generating and publishing](#generating-and-publishing)
 - [Typical editorial workflows](#typical-editorial-workflows)
 - [Working fully offline](#working-fully-offline)
 - [Troubleshooting and recovery](#troubleshooting-and-recovery)
@@ -382,6 +384,26 @@ After significant taxonomy cleanup, create a commit that captures the transition
 
 ---
 
+## Using blogmarks
+
+Blogmarks provide a quick way to save links from any browser directly into bDS as new posts. bDS registers the custom `bds://new-post` protocol, so clicking a blogmark link or bookmarklet opens bDS and creates a draft post pre-filled with the page title, URL, and selected text.
+
+To set up blogmarks, generate a bookmarklet from the Settings view and drag it to your browser bookmark bar. When you find a page worth saving, click the bookmarklet. bDS opens (or comes to the foreground) and creates a draft post automatically.
+
+Transform scripts can modify incoming blogmark posts before they are created. This is useful for normalizing titles, adding default categories or tags, or restructuring content. If you have multiple active transforms, they run in sequence. When a transform fails, bDS surfaces an error toast and writes diagnostics to the Output panel so you can adjust and retry.
+
+Transform scripts can also receive a `context` argument containing `source` (always `"blogmark"`) and `url` (the original bookmarked URL), which is helpful for URL-based routing or domain-specific formatting.
+
+### Key takeaways
+
+- Blogmarks turn any browser into a one-click content capture tool.
+- Generate the bookmarklet from Settings and add it to your browser bar.
+- Use transform scripts to normalize or enrich incoming posts automatically.
+
+[↑ Back to In this article](#in-this-article)
+
+---
+
 ## Importing from WordPress (WXR)
 
 The Import section supports migration from WordPress exports and should be treated as a structured process rather than a one-click operation. A good migration flow reduces surprises by separating analysis from execution.
@@ -436,19 +458,46 @@ Data maintenance actions are repair tools for specific situations, such as exter
 
 ---
 
-## Publishing in bDS (current scope)
+## Managing templates
 
-In the current product stage, publishing in bDS means marking local content state and generating supported local outputs, not automatically deploying to remote hosting. This distinction is important for planning release workflows and setting team expectations.
+Templates control the Liquid layout used when bDS generates your blog's HTML pages. bDS ships with built-in templates, but you can create and manage your own through the Templates view in the Activity Bar.
 
-At present, the key publishing output is sitemap generation. To generate a sitemap successfully, ensure the Public Base URL is configured in project settings before running the sitemap command. If generation fails, URL configuration should be your first verification step.
+Each template has a kind that determines where it is used: **post** templates render individual post pages, **list** templates render archive and index pages, **not-found** templates render 404 pages, and **partial** templates are reusable fragments included by other templates. You edit template code using the built-in Monaco editor, which provides syntax highlighting for Liquid and HTML.
 
-Because publish does not equal deploy, Source Control remains the mechanism for versioned distribution and collaboration. Teams should treat publish plus commit as the minimum handoff standard.
+Templates are stored as files with YAML frontmatter in your project's data directory, which means they are Git-friendly and portable between machines. bDS validates template syntax when you save, reporting any Liquid parse errors before the template can be used in generation.
+
+Templates follow the same draft/published workflow as scripts. You can iterate on a template in draft state, preview the results, and then enable it for generation when satisfied. If your project uses Git, bDS reconciles template files with the database on sync so that templates added or modified externally are picked up automatically.
 
 ### Key takeaways
 
-- Current publish behavior is local-state focused.
+- Templates define the HTML layout for generated pages.
-- Sitemap generation depends on a valid Public Base URL.
+- Four template kinds: post, list, not-found, and partial.
-- For team workflows, publish should be followed by commit.
+- Templates are files with YAML frontmatter — Git-reviewable and portable.
+- Validate before enabling; preview before generating.
+
+[↑ Back to In this article](#in-this-article)
+
+---
+
+## Generating and publishing
+
+Publishing in bDS is a two-stage process: first you generate the static site locally, then you optionally deploy it to a remote server.
+
+**Generation** produces a complete static blog from your published content. This includes individual post pages, paginated category, tag, and date archive routes, standalone pages, plus `sitemap.xml`, `rss.xml`, `atom.xml`, and `calendar.json`. Generation uses content-hash-based incremental writes, so only changed pages are rewritten. Before generating, ensure the Public Base URL is configured in project settings — sitemap and feed URLs depend on it.
+
+After generation, you can run **site validation** to compare the sitemap against generated HTML files. Validation detects missing, extra, or stale pages and can auto-repair by re-rendering only the affected routes.
+
+**SSH publishing** uploads generated files to a remote server via `scp` or `rsync`. Configure your SSH connection details in project settings, then publish from the application. bDS uploads HTML, thumbnails, and media in parallel for efficiency.
+
+The recommended lifecycle is: publish content locally (mark as published), generate the site, validate, commit the generated output, and then deploy via SSH when ready.
+
+### Key takeaways
+
+- Generation produces a full static site with incremental writes.
+- Public Base URL must be set before generation.
+- Site validation catches inconsistencies between sitemap and generated files.
+- SSH publishing deploys via `scp` or `rsync` with parallel uploads.
+- Commit generated output before deploying for recoverability.
 
 [↑ Back to In this article](#in-this-article)
 

README.md

@@ -2,14 +2,14 @@
 
 Desktop-first blogging workspace built with Electron + TypeScript + React + SQLite (Drizzle), with filesystem-based content as source of truth.
 
-## Current State (February 2026)
+## Current State (March 2026)
 
 Implemented and actively used:
 
 - **Offline-first by default** — full local editing, preview, generation, and git-based workflows; all online features are optional
 - **Multi-project workflow** with active project switching and optional custom data paths
 - **Post & page management** (draft/published/archived), pagination, filtering, multi-language full-text search (Snowball stemming), canonical URL handling, inter-post link graph with backlinks/outlinks
-- **Media pipeline** with import, metadata sidecars, three thumbnail sizes (Sharp), linked-media references, and cleanup tooling
+- **Media pipeline** with import, metadata sidecars, three thumbnail sizes (Sharp), linked-media references, cleanup tooling, and AI-assisted metadata suggestions (title, alt text, caption from image vision)
 - **Tag management** including merge/rename/sync from content, color support
 - **Menu editor** for hierarchical site navigation (OPML-based), with page picker and submenu nesting
 - **WordPress WXR import pipeline** (analysis, import definitions, 4-phase execution with progress tracking, HTML-to-Markdown conversion)
@@ -19,23 +19,30 @@ Implemented and actively used:
 - **SSH publishing** via `scp` or `rsync` with parallel upload of HTML, thumbnails, and media
 - **Preview server** with local assets only, Liquid templates, macro processing, archive routes, draft preview support, and style preview
 - **Style & theming** — 19 Pico CSS color themes with live preview (auto/light/dark modes), all assets served locally
+- **Template management** — user-facing Liquid template editor with CRUD, YAML frontmatter, validation, draft/published workflow, and Git reconciliation; template kinds: post, list, not-found, partial
 - **Python scripting** (Pyodide WebAssembly runtime) — three script kinds:
     - *Transform scripts* — modify incoming blogmark posts before creation
-    - *Macro scripts* — custom `[[macro_name ...]]` blocks that expand during preview/generation, with full access to the bDS Python API (~65+ methods)
+    - *Macro scripts* — custom `[[macro_name ...]]` blocks that expand during preview/generation, with full access to the bDS Python API (~116 methods across 11 modules)
     - *Utility scripts* — general-purpose Python automation
 - **Built-in macros** — `youtube`, `vimeo`, `gallery` (lightbox), `photo_archive`, `tag_cloud` (D3 word cloud)
 - **Liquid template system** for all generated pages with i18n support (English, German, French, Italian, Spanish) and custom Markdown filter with internal link rewriting
-- **AI assistant** (OpenCode Zen API, supporting Claude, GPT-5, Gemini 3, and more) with streaming responses, tool use (search/read/update posts, media analysis including image vision, blog stats), and rich interactive responses via the A2UI protocol (charts, tables, forms, cards, metrics, lists, tabs)
+- **AI assistant** (OpenCode Zen API, Mistral direct API, Ollama local models) with streaming responses, tool use (search/read/update posts, media analysis including image vision, blog stats), AI-powered taxonomy analysis, and rich interactive responses via the A2UI protocol (charts, tables, forms, cards, metrics, lists, tabs)
+- **MCP server** — full Model Context Protocol integration exposing the blog to external coding agents; 10 tools, 13 resources, 3 prompts, and interactive review views; supports Streamable HTTP transport (in-app) and stdio transport (standalone CLI); auto-configures into Claude Code, Claude Desktop, GitHub Copilot, Gemini CLI, OpenCode, Mistral Vibe, and OpenAI Codex agent configs
+- **Model catalog** — fetches and caches model metadata from models.dev with conditional GET refresh; provides pricing, context windows, capabilities, and modalities; works fully offline after first fetch
+- **Secure key storage** — API keys encrypted via OS keychain (macOS Keychain, Windows DPAPI, Linux libsecret) using Electron safeStorage
 - **Git integration** (status, diff, commit history with sync status, fetch/pull/push, init, .gitignore management, LFS configure/prune, branch operations)
 - **Metadata diff tooling** for comparing filesystem metadata vs database metadata with sync in either direction
-- **Rich editing** — Milkdown WYSIWYG Markdown editor for posts, Monaco code editor for Python scripts
+- **Rich editing** — Milkdown WYSIWYG Markdown editor for posts, Monaco code editor for Python scripts and Liquid templates
 - **Task system** for background progress reporting across long-running operations with grouping, cancellation, and status bar integration
+- **In-app documentation** — rendered user guide with navigable table of contents and heading anchors
 - **i18n** — UI language follows OS locale; render/preview language from project preferences; 5 supported languages
 
 ## Architecture
 
 ```text
 src/
+├── cli/
+│   └── bds-mcp.ts       # Standalone MCP stdio server (runs without Electron)
 ├── main/
 │   ├── database/        # Drizzle schema, migrations, connection
 │   ├── engine/          # Core business logic (no UI)
@@ -46,6 +53,7 @@ src/
 │   │   ├── MetaEngine             # Project metadata, categories
 │   │   ├── TagEngine              # Tag CRUD, merge, rename, colors
 │   │   ├── ScriptEngine           # Python script management & Git sync
+│   │   ├── TemplateEngine         # Liquid template CRUD, validation, Git sync
 │   │   ├── MenuEngine             # OPML-based navigation menus
 │   │   ├── PreviewServer          # Local HTTP preview with Liquid
 │   │   ├── BlogGenerationEngine   # Static site generation
@@ -56,7 +64,12 @@ src/
 │   │   ├── PythonMacroWorkerRuntime   # Pyodide macro execution
 │   │   ├── GitEngine              # Git operations (simple-git)
 │   │   ├── MetadataDiffEngine     # DB ↔ file metadata comparison
-│   │   ├── ChatEngine / OpenCodeManager  # AI chat & model integration
+│   │   ├── ChatEngine             # AI chat with streaming & tool use
+│   │   ├── MCPServer              # Model Context Protocol server (HTTP + stdio)
+│   │   ├── MCPAgentConfigEngine   # Auto-configure MCP into coding agents
+│   │   ├── ModelCatalogEngine     # Model metadata from models.dev
+│   │   ├── SecureKeyStore         # OS keychain encryption for API keys
+│   │   ├── NotificationWatcher    # CLI ↔ app DB change synchronization
 │   │   └── TaskManager            # Background task queue
 │   ├── a2ui/            # A2UI protocol: types, catalog, generator
 │   ├── ipc/             # IPC handlers; bridges renderer to engines