From 651d0028ac2dac0480d000dbd5d7a85a233eaa2c Mon Sep 17 00:00:00 2001 From: Erik van der Boom Date: Sun, 19 Apr 2026 22:33:37 +0200 Subject: [PATCH] docs: rewrite READMEs with complete tool tables and setup guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Root README: expand feature list, add CI badge section, update installation and development instructions. vscode-ext README: full rewrite — add complete command table (12), MCP tool table (25), dialect/translation workflow, autodetect docs, and format-on-save configuration details. --- README.md | 42 ++++++++-- vscode-ext/README.md | 181 +++++++++++++++++++++++++++++-------------- 2 files changed, 157 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 5b2a3e3..dbd71cf 100644 --- a/README.md +++ b/README.md @@ -18,12 +18,12 @@ The bigger shift came with Claude Cowork, which combines the session memory of a The **Bindery** extension provides: -- **Typography formatting** — curly quotes, em-dashes, ellipses, smart apostrophes -- **Chapter merge & export** — Markdown, DOCX, EPUB, PDF output via Pandoc + LibreOffice -- **Dialect conversion** — US→UK spelling with extensible substitution rules (`.bindery/translations.json`) -- **Multi-language support** — configurable per-language chapter labelling and folder structure +- **Typography formatting** — curly quotes, em-dashes, ellipses, smart apostrophes (on save or on demand) +- **Chapter merge & export** — Markdown, DOCX, EPUB, PDF output via Pandoc + LibreOffice, with auto-detection of tool paths +- **Dialect & translation management** — extensible substitution rules for dialect exports (e.g. US→UK), plus cross-language glossaries in `.bindery/translations.json` +- **Multi-language support** — configurable per-language chapter labelling and folder structure, with dialect derivatives - **Workspace config** — `.bindery/settings.json` for project-level settings -- **MCP integration** — registers Bindery tools for GitHub Copilot Chat and writes `.vscode/mcp.json` for Claude / Codex +- **MCP integration** — registers 25 Bindery tools for GitHub Copilot Chat and writes `.vscode/mcp.json` for Claude / Codex Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=option-a.bindery) or: @@ -43,10 +43,13 @@ A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes - **BM25 full-text search** — fast lexical search across all chapters and notes via [MiniSearch](https://lucaong.github.io/minisearch/) - **Optional semantic search** — set `BINDERY_OLLAMA_URL` for semantic reranking, or enable a full semantic index for precomputed embedding search - **Version tracking** — `get_review_text` shows uncommitted changes as a structured diff; `git_snapshot` saves progress as a git commit scoped to story/notes/arc folders. Git is auto-initialized during workspace setup if available +- **Translation & dialect management** — glossary entries and dialect substitution rules in `.bindery/translations.json`, queryable and updatable by agents +- **Session memory** — persistent `.bindery/memories/` files for cross-session decisions, with append, list, and compact operations +- **Chapter status tracking** — per-chapter progress tracker (`draft`, `in-progress`, `done`, `needs-review`) - **Multi-book support** — configure one or more books via `--book Name=path` CLI args or `BINDERY_BOOKS` env var; every tool call specifies which book to use by name (agents never see raw paths) - **Container/mount aware** — agents in sandboxed environments (e.g. Cowork) can call `identify_book` with their working directory to discover their book name, even when mount paths differ from the configured paths -See [mcpb/README.md](mcpb/README.md) for full documentation and tool list. +See [mcpb/README.md](mcpb/README.md) for the full 27-tool reference and usage examples. ### [mcpb/](mcpb/) — Claude Desktop Extension @@ -108,6 +111,29 @@ The VS Code extension works standalone — no server setup needed for typography - **Ollama** (optional) — needed for semantic reranking and search. - Install via package manager or from [https://ollama.com/](https://ollama.com/) +### Pandoc / LibreOffice auto-detection + +On all platforms the extension resolves tool paths in this order: + +1. Explicit `bindery.pandocPath` / `bindery.libreOfficePath` user setting (if set and the file exists) +2. Command on `PATH` (`where.exe` on Windows, `which` elsewhere) +3. Well-known install locations: + - **Windows**: `%LOCALAPPDATA%\Pandoc\pandoc.exe`, `%ProgramFiles%\Pandoc\pandoc.exe`, `%ProgramFiles%\LibreOffice\program\soffice.exe` + - **macOS**: `/opt/homebrew/bin/pandoc`, `/usr/local/bin/pandoc`, `/Applications/LibreOffice.app/Contents/MacOS/soffice` + - **Linux**: `/usr/bin/pandoc`, `/usr/bin/libreoffice` + +You usually do not need to configure anything — install Pandoc/LibreOffice normally and exports will work. Use the `bindery_health` MCP tool to see what was detected. + +## Known limitations + +- **Git** must be on `PATH` (or at a standard install location) for `get_review_text` and `git_snapshot`. If git isn't found, these tools fail with a clear error; all other tools still work. +- **Pandoc** is required for DOCX, EPUB, and PDF export. Markdown-only export has no external dependencies. +- **LibreOffice** is required only for PDF export. Bindery generates PDFs by producing a DOCX via Pandoc and then converting with LibreOffice headless. +- **Semantic search** requires an optional [Ollama](https://ollama.com/) instance. Without it, lexical BM25 search still works offline. Configure with `BINDERY_OLLAMA_URL`; optional tuning via `BINDERY_OLLAMA_TIMEOUT_MS` (default 15000) and `BINDERY_OLLAMA_RETRIES` (default 1). +- **Large books with semantic indexing** can take several minutes to embed on first build. Rebuilds are incremental when chapter content is unchanged. +- **Chapter numbering**: the tools sort chapters by filename but accept non-contiguous numbers. `get_overview` now flags gaps (e.g. chapters 1, 3 with no 2) as a warning. +- **Search index format**: bumped automatically when the on-disk format changes. Older indexes are silently ignored and rebuilt on next use — no manual action required. + ## Privacy Bindery stays within your workspace, only if the optional Ollama URL is filled for the MCP server will texts be sent to Ollama for embedding / semantic search. The full privacy policy can be viewed at [https://evdboom.nl/projects/bindery/privacy](https://evdboom.nl/projects/bindery/privacy) @@ -153,9 +179,11 @@ but differs from the source — this is what CI catches. The CI workflow (`.github/workflows/ci.yml`) runs on every push and pull request: -1. Builds and tests the MCP server. +1. Builds and tests the MCP server (Ubuntu, Windows, macOS). 2. Copies `mcp-ts/src/templates.ts` → `vscode-ext/src/ai-setup-templates.ts`. 3. Verifies the copy is identical to the source (fails with a clear remediation message if not). 4. Builds and tests the VS Code extension. +5. Runs the **tool parity guard** (`scripts/check-tool-parity.mjs`) — verifies all MCP tools are registered consistently across all 5 surfaces (server, VS Code LM tools, package.json, mcpb manifest, implementation). +6. Enforces **coverage thresholds** (statements 80%, branches 65%, functions 90%, lines 80%) for both packages. If CI fails on the sync check, fix it by running the copy command above and committing the result. diff --git a/vscode-ext/README.md b/vscode-ext/README.md index fd69eb9..75504a2 100644 --- a/vscode-ext/README.md +++ b/vscode-ext/README.md @@ -1,6 +1,6 @@ # Bindery -Markdown book authoring tools for VS Code: typography formatting (curly quotes, em-dashes, ellipses), multi-language chapter export (DOCX, EPUB, PDF), and dialect conversion. +Markdown book authoring tools for VS Code: typography formatting, multi-language chapter export (DOCX, EPUB, PDF), dialect conversion, translation management, and AI assistant integration via a bundled MCP server. ## Features @@ -9,12 +9,12 @@ Markdown book authoring tools for VS Code: typography formatting (curly quotes, Converts plain-text typography to professional typographic characters: | Input | Output | Description | -|-------|------—|-------------| -| `…` | `…` | Ellipsis | -| `—` | `—` | Em-dash (preserves `---` for markdown HR) | -| `”text”` | `”text”` | Curly double quotes | -| `’text’` | `’text’` | Curly single quotes | -| `don’t` | `don’t` | Smart apostrophes | +|-------|--------|-------------| +| `...` | `…` | Ellipsis | +| `--` | `—` | Em-dash (preserves `---` for markdown HR) | +| `"text"` | `"text"` | Curly double quotes | +| `'text'` | `'text'` | Curly single quotes | +| `don't` | `don't` | Smart apostrophes | HTML comments are preserved and not modified. @@ -34,37 +34,64 @@ Merges ordered chapter files into a single document with TOC generation: - **EPUB** (`.epub`) — via Pandoc, with chapter splitting and optional cover - **PDF** (`.pdf`) — via Pandoc (intermediate DOCX) + LibreOffice headless conversion, giving consistent output quality across all platforms -For `UK` exports, the extension auto-generates `Story/UK` from `Story/EN` at export time, applies US→UK spelling conversion before merge, and removes `Story/UK` again after export completes. +Dialect exports (e.g. British English from a US English source) are handled automatically: the extension copies the source language folder to a temporary dialect folder, applies all configured substitution rules, merges, and removes the temp folder after export. **How to use:** - **Editor toolbar** — click the $(book) **Bindery Export** button (visible on markdown files) -- **Command Palette** (`Ctrl+Shift+P`) → search “Bindery” +- **Command Palette** (`Ctrl+Shift+P`) → search "Bindery" -Supported commands: -- `Bindery: Merge Chapters → Markdown` -- `Bindery: Merge Chapters → DOCX` -- `Bindery: Merge Chapters → EPUB` -- `Bindery: Merge Chapters → PDF` -- `Bindery: Merge Chapters → All Formats` -- `Bindery: Find Probable US→UK Words` -- `Bindery: Add Substitution Rule` -- `Bindery: Open translations.json` -- `Bindery: Initialize Workspace` -- `Bindery: Setup AI Assistant Files` -- `Bindery: Register MCP Server` +### Dialect & Translation Management + +Substitution rules (e.g. US→UK spelling) are applied in tiers (later tiers win): + +1. **Built-in** — common US→UK conversions (color→colour, center→centre, etc.) +2. **General** — `bindery.generalSubstitutions` in VS Code user settings (follows you to every workspace) +3. **Project** — `.bindery/translations.json` in the workspace + +Cross-language glossary entries (e.g. EN→NL world terms) are also stored in `.bindery/translations.json` for agent reference and consistency checking. ### AI Assistant Integration (MCP) -Bindery includes a bundled MCP server that makes your book's chapters, notes, and search index available to AI assistants directly inside VS Code. +Bindery includes a bundled MCP server that makes your book's chapters, notes, search index, memory, and translation data available to AI assistants directly inside VS Code. **GitHub Copilot Chat** — tools are registered automatically when the extension activates. Use `#bindery_search`, `#bindery_get_chapter`, etc. in chat. **Claude for VS Code / Codex** — run `Bindery: Register MCP Server` once per workspace. This writes `.vscode/mcp.json` pointing to the bundled server. Both extensions pick this up automatically on next reload. -Available tools: `bindery_health`, `bindery_index_build`, `bindery_index_status`, `bindery_get_text`, `bindery_get_chapter`, `bindery_get_overview`, `bindery_get_notes`, `bindery_search`, `bindery_format`. +#### Available MCP tools (25) -`bindery_search` supports `lexical`, `semantic_rerank`, and `full_semantic` modes. Semantic modes fall back to lexical results with a warning if Ollama or the semantic index is unavailable. +| Tool | Description | +|------|-------------| +| `bindery_health` | Check workspace status: settings, search index, and embedding backend | +| `bindery_init_workspace` | Create or update `.bindery/settings.json` and `translations.json` | +| `bindery_setup_ai_files` | Generate AI instruction files (CLAUDE.md, copilot-instructions.md, etc.) | +| `bindery_settings_update` | Merge a partial patch into `.bindery/settings.json` | +| `bindery_index_build` | Build or rebuild the search index (lexical + optional semantic) | +| `bindery_index_status` | Show index metadata and stale-status hints | +| `bindery_search` | Full-text search: lexical BM25, semantic rerank, or full semantic mode | +| `bindery_get_text` | Read any file by relative path, with optional line range | +| `bindery_get_chapter` | Full chapter content by number and language | +| `bindery_get_book_until` | Chapters from a start through a target chapter, concatenated in order | +| `bindery_get_overview` | Chapter structure — acts, chapters, titles | +| `bindery_get_notes` | Notes files, filterable by category or character name | +| `bindery_format` | Apply typography formatting to a file or folder | +| `bindery_get_review_text` | Structured git diff of uncommitted changes | +| `bindery_git_snapshot` | Save a snapshot (git commit) of story/notes/arc changes | +| `bindery_get_translation` | Look up cross-language glossary entries | +| `bindery_add_translation` | Add or update a glossary entry | +| `bindery_get_dialect` | Look up dialect substitution rules | +| `bindery_add_dialect` | Add or update a dialect substitution rule | +| `bindery_add_language` | Add a language and scaffold its story folder | +| `bindery_memory_list` | List session memory files with line counts | +| `bindery_memory_append` | Append a dated entry to a memory file | +| `bindery_memory_compact` | Overwrite a memory file with a summary (backs up original) | +| `bindery_chapter_status_get` | Read per-chapter progress (draft, in-progress, done, needs-review) | +| `bindery_chapter_status_update` | Upsert chapter progress entries | + +`bindery_search` supports `lexical`, `semantic_rerank`, and `full_semantic` modes. Semantic modes require an Ollama instance and fall back to lexical results with a warning if unavailable. + +For the standalone MCP server (Claude Desktop / Cowork), two additional tools are available: `list_books` and `identify_book` for multi-book discovery. See [mcpb/README.md](../mcpb/README.md) for full MCP documentation and usage examples. ### File Discovery @@ -82,69 +109,105 @@ Story/ Epilogue.md ← last ``` +Localized prologue/epilogue names are supported (e.g. `Proloog.md` for Dutch) via the language configuration. + +## Commands + +All commands are available from the Command Palette (`Ctrl+Shift+P`) under the **Bindery** category. + +| Command | Description | +|---------|-------------| +| `Initialize Workspace` | Create `.bindery/settings.json` and `translations.json` | +| `Setup AI Assistant Files` | Generate CLAUDE.md, copilot-instructions.md, .cursor/rules, AGENTS.md | +| `Register MCP Server` | Write `.vscode/mcp.json` for Claude / Codex MCP discovery | +| `Format Typography` | Apply typography formatting to the active markdown file | +| `Format All Markdown in Folder` | Apply typography to all `.md` files in a folder | +| `Merge Chapters → Markdown` | Merge chapters into a single `.md` file | +| `Merge Chapters → DOCX` | Merge chapters and export via Pandoc | +| `Merge Chapters → EPUB` | Merge chapters and export via Pandoc | +| `Merge Chapters → PDF` | Merge chapters via Pandoc + LibreOffice | +| `Merge Chapters → All Formats` | Export all configured formats at once | +| `Find Probable US→UK Words` | Scan `Story/EN` for likely US spellings | +| `Add Dialect Rule` | Add a dialect substitution rule (e.g. color→colour) | +| `Add Translation (Glossary)` | Add a cross-language glossary entry | +| `Add Language` | Add a new language and scaffold its story folder | +| `Open translations.json` | Open the translations file in the editor | + ## Configuration +Settings can be defined in `.bindery/settings.json` (preferred) or VS Code settings (fallback). + | Setting | Default | Description | |---------|---------|-------------| -| `bindery.storyFolder` | `”Story”` | Folder containing language subfolders | +| `bindery.storyFolder` | `"Story"` | Folder containing language subfolders | | `bindery.languages` | EN | Language configurations (see below) | -| `bindery.mergedOutputDir` | `”Merged”` | Output directory for merged files | -| `bindery.author` | `””` | Author name for EPUB/DOCX metadata | -| `bindery.bookTitle` | `””` | Book title (auto-detected if empty) | -| `bindery.pandocPath` | `”pandoc”` | Path to Pandoc executable | -| `bindery.libreOfficePath` | `”libreoffice”` | Path to LibreOffice executable for PDF export. On Linux/WSL: `libreoffice` (default). On Windows: full path to `soffice.exe`, e.g. `C:\Program Files\LibreOffice\program\soffice.exe` | -| `bindery.formatOnSave` | `false` | Auto-format typography on save | -| `bindery.mergeFilePrefix` | `”Book”` | Prefix for output filenames | +| `bindery.mergedOutputDir` | `"Merged"` | Output directory for merged files | +| `bindery.author` | `""` | Author name for EPUB/DOCX metadata | +| `bindery.bookTitle` | `""` | Book title (string or per-language map) | +| `bindery.pandocPath` | `"pandoc"` | Path to Pandoc executable (auto-detected if left as default) | +| `bindery.libreOfficePath` | `"libreoffice"` | Path to LibreOffice executable (auto-detected if left as default) | +| `bindery.formatOnSave` | `false` | Auto-format typography on save (only files inside the story folder) | +| `bindery.mergeFilePrefix` | `"Book"` | Prefix for output filenames | | `bindery.generalSubstitutions` | `[]` | Dialect substitution rules applied across all projects | -### Dialect Conversion - -Substitution rules are applied in tiers (later tiers win): -1. **Built-in** — common US→UK conversions -2. **General** — `bindery.generalSubstitutions` in VS Code user settings -3. **Project** — `.bindery/translations.json` in the workspace - -You can extend conversion rules without editing code: - -- Run `Bindery: Find Probable US→UK Words` to scan `Story/EN` for likely US spellings (like `-ize` forms), then add selected entries. -- Run `Bindery: Add Substitution Rule` to manually add one mapping. - ### Language Configuration Each language entry supports: ```json { - “code”: “EN”, - “folderName”: “EN”, - “chapterWord”: “Chapter”, - “actPrefix”: “Act”, - “prologueLabel”: “Prologue”, - “epilogueLabel”: “Epilogue” + "code": "EN", + "folderName": "EN", + "chapterWord": "Chapter", + "actPrefix": "Act", + "prologueLabel": "Prologue", + "epilogueLabel": "Epilogue", + "isDefault": true, + "bookTitle": "The Hollow Road", + "dialects": [ + { "code": "en-gb", "label": "British English" } + ] } ``` +- `isDefault` marks the primary language (used as fallback for title resolution) +- `bookTitle` provides a per-language title override for export metadata +- `dialects` lists dialect codes that derive from this language; during export the extension copies the source folder, applies substitution rules from `.bindery/translations.json`, and merges the converted content + ### Adding a New Language Add to `.bindery/settings.json` (or `bindery.languages` in VS Code settings): ```json { - “languages”: [ - { “code”: “EN”, “folderName”: “EN”, “chapterWord”: “Chapter”, “actPrefix”: “Act”, “prologueLabel”: “Prologue”, “epilogueLabel”: “Epilogue” }, - { “code”: “FR”, “folderName”: “FR”, “chapterWord”: “Chapitre”, “actPrefix”: “Acte”, “prologueLabel”: “Prologue”, “epilogueLabel”: “Épilogue” } + "languages": [ + { "code": "EN", "folderName": "EN", "chapterWord": "Chapter", "actPrefix": "Act", "prologueLabel": "Prologue", "epilogueLabel": "Epilogue", "isDefault": true }, + { "code": "FR", "folderName": "FR", "chapterWord": "Chapitre", "actPrefix": "Acte", "prologueLabel": "Prologue", "epilogueLabel": "Épilogue" } ] } ``` +Or use the `Bindery: Add Language` command, which scaffolds the story folder with stub files mirroring the default language structure. + ## Requirements - **VS Code** 1.85+ -- **Git** (recommended) — needed for version tracking and review features (`get_review_text`, `git_snapshot`). Auto-initialized during workspace setup. [Install](https://git-scm.com) -- **Pandoc** (needed for DOCX/EPUB/PDF export) — [Install](https://pandoc.org/installing.html) -- **LibreOffice** (needed for PDF export) — used to convert the intermediate DOCX to PDF - - Linux/WSL: `sudo apt install libreoffice` - - Windows: [Download from libreoffice.org](https://www.libreoffice.org/download/download-libreoffice/), then set `bindery.libreOfficePath` to the full path of `soffice.exe` (e.g. `C:\Program Files\LibreOffice\program\soffice.exe`) +- **Git** (recommended) — needed for version tracking and review features. Auto-initialized during workspace setup. [Install](https://git-scm.com) +- **Pandoc** (optional) — needed for DOCX/EPUB/PDF export. [Install](https://pandoc.org/installing.html) +- **LibreOffice** (optional) — needed for PDF export only. [Install](https://www.libreoffice.org/download/download-libreoffice/) + +### Pandoc / LibreOffice Auto-Detection + +On all platforms the extension resolves tool paths automatically: + +1. Explicit `bindery.pandocPath` / `bindery.libreOfficePath` user setting (if set and the file exists) +2. Command on `PATH` (`where.exe` on Windows, `which` elsewhere) +3. Well-known install locations: + - **Windows**: `%LOCALAPPDATA%\Pandoc\pandoc.exe`, `%ProgramFiles%\Pandoc\pandoc.exe`, `%ProgramFiles%\LibreOffice\program\soffice.exe` + - **macOS**: `/opt/homebrew/bin/pandoc`, `/Applications/LibreOffice.app/Contents/MacOS/soffice` + - **Linux**: `/usr/bin/pandoc`, `/usr/bin/libreoffice` + +You usually do not need to configure anything — install Pandoc/LibreOffice normally and exports will work. ## Building from Source @@ -159,5 +222,5 @@ To install locally: ```bash npm install -g @vscode/vsce vsce package -code —install-extension bindery-0.2.0.vsix +code --install-extension bindery-*.vsix ```