docs: rewrite READMEs with complete tool tables and setup guides

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.
This commit is contained in:
Erik van der Boom 2026-04-19 22:33:37 +02:00
parent 1c38716a67
commit 651d0028ac
2 changed files with 157 additions and 66 deletions

View file

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

View file

@ -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 |
| `dont` | `dont` | 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
```