@maincode-ai/matilda-code 0.21.12 → 0.21.13-nightly.20261027.e00306cd3

package/bundled/mainy/docs/features/language.md

@@ -1,171 +0,0 @@
-# Internationalization (i18n) & Language
-
-Matilda Code is built for multilingual workflows: it supports UI localization (i18n/l10n) in the CLI, lets you choose the assistant output language, and allows custom UI language packs.
-
-## Overview
-
-From a user point of view, Matilda Code’s “internationalization” spans multiple layers:
-
-| Capability / Setting     | What it controls                                                       | Where stored                    |
-| ------------------------ | ---------------------------------------------------------------------- | ------------------------------- |
-| `/language ui`           | Terminal UI text (menus, system messages, prompts)                     | `~/.matilda/settings.json`      |
-| `/language output`       | Language the AI responds in (an output preference, not UI translation) | `~/.matilda/output-language.md` |
-| Custom UI language packs | Overrides/extends built-in UI translations                             | `~/.matilda/locales/*.js`       |
-
-## UI Language
-
-This is the CLI’s UI localization layer (i18n/l10n): it controls the language of menus, prompts, and system messages.
-
-### Setting the UI Language
-
-Use the `/language ui` command:
-
-```bash
-/language ui zh-CN    # Chinese
-/language ui en-US    # English
-/language ui ru-RU    # Russian
-/language ui de-DE    # German
-/language ui ja-JP    # Japanese
-/language ui pt-BR    # Portuguese (Brazil)
-/language ui fr-FR    # French
-/language ui ca-ES    # Catalan
-```
-
-Aliases are also supported:
-
-```bash
-/language ui zh       # Chinese
-/language ui en       # English
-/language ui ru       # Russian
-/language ui de       # German
-/language ui ja       # Japanese
-/language ui pt       # Portuguese
-/language ui fr       # French
-/language ui ca       # Catalan
-```
-
-### Auto-detection
-
-On first startup, Matilda Code detects your system locale and sets the UI language automatically.
-
-Detection priority:
-
-1. `MATILDA_CODE_LANG` environment variable
-2. `LANG` environment variable
-3. System locale via JavaScript Intl API
-4. Default: English
-
-## LLM Output Language
-
-The LLM output language controls what language the AI assistant responds in, regardless of what language you type your questions in.
-
-### How It Works
-
-The LLM output language is controlled by a rule file at `~/.matilda/output-language.md`. This file is automatically included in the LLM's context during startup, instructing it to respond in the specified language.
-
-### Auto-detection
-
-On first startup, if no `output-language.md` file exists, Matilda Code automatically creates one based on your system locale. For example:
-
-- System locale `zh` creates a rule for Chinese responses
-- System locale `en` creates a rule for English responses
-- System locale `ru` creates a rule for Russian responses
-- System locale `de` creates a rule for German responses
-- System locale `ja` creates a rule for Japanese responses
-- System locale `pt` creates a rule for Portuguese responses
-- System locale `fr` creates a rule for French responses
-- System locale `ca` creates a rule for Catalan responses
-
-### Manual Setting
-
-Use `/language output <language>` to change:
-
-```bash
-/language output Chinese
-/language output English
-/language output Japanese
-/language output German
-```
-
-Any language name works. The LLM will be instructed to respond in that language.
-
-> [!note]
->
-> After changing the output language, restart Matilda Code for the change to take effect.
-
-### File Location
-
-```
-~/.matilda/output-language.md
-```
-
-## Configuration
-
-### Via Settings Dialog
-
-1. Run `/settings`
-2. Find "Language" under General
-3. Select your preferred UI language
-
-### Via Environment Variable
-
-```bash
-export MATILDA_CODE_LANG=zh
-```
-
-This influences auto-detection on first startup (if you haven’t set a UI language and no `output-language.md` file exists yet).
-
-## Custom Language Packs
-
-For UI translations, you can create custom language packs in `~/.matilda/locales/`:
-
-- Example: `~/.matilda/locales/es.js` for Spanish
-- Example: `~/.matilda/locales/fr.js` for French
-
-User directory takes precedence over built-in translations.
-
-> [!tip]
->
-> Contributions are welcome! If you’d like to improve built-in translations or add new languages.
-> For a concrete example, see [PR #1238: feat(i18n): add Russian language support](https://github.com/MaincodeHQ/matilda-code/pull/1238).
-
-### Maintaining `zh-TW` (Traditional Chinese for Taiwan)
-
-`zh-TW` is **not** an automatic OpenCC s2t conversion of `zh.js` — it is a hand-maintained Taiwan-vocabulary translation. When adding or updating keys, please follow the conventions below.
-
-The "CI enforced?" column indicates whether `npm run check-i18n` will fail the build on a violation. Rows marked **No** are style guidance enforced by review only — typically because the offending form has a legitimate non-UI meaning (`文件` can mean "document", `打開` is colloquially fine in Taiwan).
-
-| Avoid                 | Use instead           | CI enforced? | Reason                                                                                                                                                                           |
-| --------------------- | --------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 文件 (file)           | 檔案                  | No           | Taiwan term for filesystem files (but `文件` can legitimately mean "document")                                                                                                   |
-| 服務器 / 服务器       | 伺服器                | Yes          | Taiwan term for "server"                                                                                                                                                         |
-| 菜單 / 菜单           | 選單                  | Yes          | Taiwan term for "menu"                                                                                                                                                           |
-| 鏈接 / 链接           | 連結                  | Yes          | Taiwan term for "link" (bare `鏈` is fine — e.g. 區塊鏈)                                                                                                                         |
-| 打開                  | 開啟                  | No           | Taiwan-preferred verb for "open" (UI); `打開` is colloquially common                                                                                                             |
-| 爲 / 啓 / 曆史 / 鏈接 | 為 / 啟 / 歷史 / 連結 | Yes          | Variant Traditional forms from raw OpenCC s2t. Note: `曆` is context-dependent and correct in calendar terms (日曆, 農曆, 西曆); CI only flags the bigram `曆史`, not bare `曆`. |
-
-If you are not a Traditional Chinese speaker and need to bootstrap a value, **do not paste raw OpenCC `s2t` output**: the default s2t profile emits variant Traditional characters (e.g. 爲, 啓) that Taiwan does not use, and never rewrites Mainland-Chinese vocabulary (服務器, 菜單). Prefer `s2twp.json` (Simplified → Taiwan with phrase mapping) as a starting point and then ask a Taiwan-Chinese speaker to review.
-
-The `check-i18n` script (run in CI via `npm run check-i18n`) will fail the build if any of the CI-enforced substrings above end up in a `zh-TW` value. See `scripts/check-i18n.ts → ZH_TW_FORBIDDEN_PATTERNS` for the full list. If a translation legitimately needs to contain a CI-forbidden substring, add its key to `ZH_TW_ALLOWED_EXCEPTIONS` in the same file with a brief justification.
-
-> [!note]
->
-> The check uses plain substring matching, which does not understand Chinese word boundaries. A bigram pattern can therefore false-positive across compound-word boundaries — for example, `區塊鏈接口` (= `區塊鏈` + `接口`) contains the substring `鏈接` even though neither word is incorrect. If you hit a surprising CI failure of this kind, add the translation key to `ZH_TW_ALLOWED_EXCEPTIONS` rather than removing the pattern.
-
-### Language Pack Format
-
-```javascript
-// ~/.matilda/locales/es.js
-export default {
-  Hello: 'Hola',
-  Settings: 'Configuracion',
-  // ... more translations
-};
-```
-
-## Related Commands
-
-- `/language` - Show current language settings
-- `/language ui [lang]` - Set UI language
-- `/language output <language>` - Set LLM output language
-- `/settings` - Open settings dialog

package/bundled/mainy/docs/features/lsp.md

@@ -1,496 +0,0 @@
-# Language Server Protocol (LSP) Support
-
-Matilda Code provides native Language Server Protocol (LSP) support, enabling advanced code intelligence features like go-to-definition, find references, diagnostics, and code actions. This integration allows the AI agent to understand your code more deeply and provide more accurate assistance.
-
-## Overview
-
-LSP support in Matilda Code works by connecting to language servers that understand your code. Once you configure servers via `.lsp.json` (or extensions), Matilda Code can start them and use them to:
-
-- Navigate to symbol definitions
-- Find all references to a symbol
-- Get hover information (documentation, type info)
-- View diagnostic messages (errors, warnings)
-- Access code actions (quick fixes, refactorings)
-- Analyze call hierarchies
-
-## Quick Start
-
-LSP is an experimental feature in Matilda Code. To enable it, use the `--experimental-lsp` command line flag:
-
-```bash
-matilda --experimental-lsp
-```
-
-LSP servers are configuration-driven. You must define them in `.lsp.json` (or via extensions) for Matilda Code to start them.
-
-### Prerequisites
-
-You need to have the language server for your programming language installed:
-
-| Language              | Language Server            | Install Command                                                                |
-| --------------------- | -------------------------- | ------------------------------------------------------------------------------ |
-| TypeScript/JavaScript | typescript-language-server | `npm install -g typescript-language-server typescript`                         |
-| Python                | pylsp                      | `pip install python-lsp-server`                                                |
-| Go                    | gopls                      | `go install golang.org/x/tools/gopls@latest`                                   |
-| Rust                  | rust-analyzer              | [Installation guide](https://rust-analyzer.github.io/manual.html#installation) |
-| C/C++                 | clangd                     | Install LLVM/clangd via your package manager                                   |
-| Java                  | jdtls                      | Install JDTLS and a JDK                                                        |
-
-## Configuration
-
-### .lsp.json File
-
-You can configure language servers using a `.lsp.json` file in your project root. Each top-level key is a language identifier, and its value is the server configuration object.
-
-**Basic format:**
-
-```json
-{
-  "typescript": {
-    "command": "typescript-language-server",
-    "args": ["--stdio"],
-    "extensionToLanguage": {
-      ".ts": "typescript",
-      ".tsx": "typescriptreact",
-      ".js": "javascript",
-      ".jsx": "javascriptreact"
-    }
-  }
-}
-```
-
-### C/C++ (clangd) configuration
-
-Dependencies:
-
-- clangd (LLVM) must be installed and available in PATH.
-- A compile database (`compile_commands.json`) or `compile_flags.txt` is required for accurate results.
-
-Example:
-
-```json
-{
-  "cpp": {
-    "command": "clangd",
-    "args": [
-      "--background-index",
-      "--clang-tidy",
-      "--header-insertion=iwyu",
-      "--completion-style=detailed"
-    ]
-  }
-}
-```
-
-### Java (jdtls) configuration
-
-Dependencies:
-
-- JDK installed and available in PATH (`java`).
-- JDTLS installed and available in PATH (`jdtls`).
-
-Example:
-
-```json
-{
-  "java": {
-    "command": "jdtls",
-    "args": ["-configuration", ".jdtls-config", "-data", ".jdtls-workspace"]
-  }
-}
-```
-
-### Configuration Options
-
-#### Required Fields
-
-| Option    | Type   | Description                                                                                                                                       |
-| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `command` | string | Command to start the LSP server. Supports bare command names resolved via `PATH` (e.g. `clangd`) and absolute paths (e.g. `/opt/llvm/bin/clangd`) |
-
-#### Optional Fields
-
-| Option                  | Type     | Default   | Description                                             |
-| ----------------------- | -------- | --------- | ------------------------------------------------------- |
-| `args`                  | string[] | `[]`      | Command line arguments                                  |
-| `transport`             | string   | `"stdio"` | Transport type: `stdio`, `tcp`, or `socket`             |
-| `env`                   | object   | -         | Environment variables                                   |
-| `initializationOptions` | object   | -         | LSP initialization options                              |
-| `settings`              | object   | -         | Server settings via `workspace/didChangeConfiguration`  |
-| `extensionToLanguage`   | object   | -         | Maps file extensions to language identifiers            |
-| `workspaceFolder`       | string   | -         | Override workspace folder (must be within project root) |
-| `startupTimeout`        | number   | `10000`   | Startup timeout in milliseconds                         |
-| `shutdownTimeout`       | number   | `5000`    | Shutdown timeout in milliseconds                        |
-| `restartOnCrash`        | boolean  | `false`   | Auto-restart on crash                                   |
-| `maxRestarts`           | number   | `3`       | Maximum restart attempts                                |
-| `trustRequired`         | boolean  | `true`    | Require trusted workspace                               |
-
-### TCP/Socket Transport
-
-For servers that use TCP or Unix socket transport:
-
-```json
-{
-  "remote-lsp": {
-    "transport": "tcp",
-    "socket": {
-      "host": "127.0.0.1",
-      "port": 9999
-    },
-    "extensionToLanguage": {
-      ".custom": "custom"
-    }
-  }
-}
-```
-
-## Available LSP Operations
-
-Matilda Code exposes LSP functionality through the unified `lsp` tool. Here are the available operations:
-
-Location-based operations (`goToDefinition`, `findReferences`, `hover`, `goToImplementation`, and `prepareCallHierarchy`) require an exact `filePath` + `line` + `character` position. If you do not know the exact position, use `workspaceSymbol` or `documentSymbol` first to locate the symbol.
-
-### Code Navigation
-
-#### Go to Definition
-
-Find where a symbol is defined.
-
-```
-Operation: goToDefinition
-Parameters:
-  - filePath: Path to the file
-  - line: Line number (1-based)
-  - character: Column number (1-based)
-```
-
-#### Find References
-
-Find all references to a symbol.
-
-```
-Operation: findReferences
-Parameters:
-  - filePath: Path to the file
-  - line: Line number (1-based)
-  - character: Column number (1-based)
-  - includeDeclaration: Include the declaration itself (optional)
-```
-
-#### Go to Implementation
-
-Find implementations of an interface or abstract method.
-
-```
-Operation: goToImplementation
-Parameters:
-  - filePath: Path to the file
-  - line: Line number (1-based)
-  - character: Column number (1-based)
-```
-
-### Symbol Information
-
-#### Hover
-
-Get documentation and type information for a symbol.
-
-```
-Operation: hover
-Parameters:
-  - filePath: Path to the file
-  - line: Line number (1-based)
-  - character: Column number (1-based)
-```
-
-#### Document Symbols
-
-Get all symbols in a document.
-
-```
-Operation: documentSymbol
-Parameters:
-  - filePath: Path to the file
-```
-
-#### Workspace Symbol Search
-
-Search for symbols across the workspace.
-
-```
-Operation: workspaceSymbol
-Parameters:
-  - query: Search query string
-  - limit: Maximum results (optional)
-```
-
-### Call Hierarchy
-
-#### Prepare Call Hierarchy
-
-Get the call hierarchy item at a position.
-
-```
-Operation: prepareCallHierarchy
-Parameters:
-  - filePath: Path to the file
-  - line: Line number (1-based)
-  - character: Column number (1-based)
-```
-
-#### Incoming Calls
-
-Find all functions that call the given function.
-
-```
-Operation: incomingCalls
-Parameters:
-  - callHierarchyItem: Item from prepareCallHierarchy
-```
-
-#### Outgoing Calls
-
-Find all functions called by the given function.
-
-```
-Operation: outgoingCalls
-Parameters:
-  - callHierarchyItem: Item from prepareCallHierarchy
-```
-
-### Diagnostics
-
-#### File Diagnostics
-
-Get diagnostic messages (errors, warnings) for a file.
-
-```
-Operation: diagnostics
-Parameters:
-  - filePath: Path to the file
-```
-
-#### Workspace Diagnostics
-
-Get all diagnostic messages across the workspace.
-
-```
-Operation: workspaceDiagnostics
-Parameters:
-  - limit: Maximum results (optional)
-```
-
-#### Automatic diagnostics after edits
-
-When LSP is enabled, the agent does not need to ask for diagnostics explicitly after changing a file. Immediately after a successful file edit or write, the configured language servers are queried for that file and any errors and warnings are appended to the tool result, so the agent can correct mistakes in the same turn.
-
-This is best-effort: it only runs while LSP is enabled, it is bounded by a short timeout so a slow server never stalls the turn, it reports errors and warnings only (capped in volume), and a failure to fetch diagnostics never affects the edit itself. Servers that do not implement pull diagnostics contribute nothing to this feedback.
-
-### Code Actions
-
-#### Get Code Actions
-
-Get available code actions (quick fixes, refactorings) at a location.
-
-```
-Operation: codeActions
-Parameters:
-  - filePath: Path to the file
-  - line: Start line number (1-based)
-  - character: Start column number (1-based)
-  - endLine: End line number (optional, defaults to line)
-  - endCharacter: End column (optional, defaults to character)
-  - diagnostics: Diagnostics to get actions for (optional)
-  - codeActionKinds: Filter by action kind (optional)
-```
-
-Code action kinds:
-
-- `quickfix` - Quick fixes for errors/warnings
-- `refactor` - Refactoring operations
-- `refactor.extract` - Extract to function/variable
-- `refactor.inline` - Inline function/variable
-- `source` - Source code actions
-- `source.organizeImports` - Organize imports
-- `source.fixAll` - Fix all auto-fixable issues
-
-## Security
-
-LSP servers are only started in trusted workspaces by default. This is because language servers run with your user permissions and can execute code.
-
-### Trust Controls
-
-- **Trusted Workspace**: LSP servers start if configured
-- **Untrusted Workspace**: LSP servers won't start unless `trustRequired: false` is set in the server configuration
-
-To mark a workspace as trusted, use the `/trust` command.
-
-### Per-Server Trust Override
-
-You can override trust requirements for specific servers in their configuration:
-
-```json
-{
-  "safe-server": {
-    "command": "safe-language-server",
-    "args": ["--stdio"],
-    "trustRequired": false,
-    "extensionToLanguage": {
-      ".safe": "safe"
-    }
-  }
-}
-```
-
-## Troubleshooting
-
-### Server Not Starting
-
-1. **Verify `--experimental-lsp` flag**: Make sure you're using the flag when starting Matilda Code
-2. **Check if the server is installed**: Run the command manually (e.g. `clangd --version`) to verify
-3. **Check the command**: The server binary must be in your system `PATH`, or specified as an absolute path (e.g. `/opt/llvm/bin/clangd`). Relative paths that escape the workspace are blocked
-4. **Check workspace trust**: The workspace must be trusted for LSP (use `/trust`)
-5. **Check logs**: Start Matilda Code with `--debug`, then search for LSP-related entries in the debug log (see Debugging section below)
-6. **Check the process**: Run `ps aux | grep <server-name>` to verify the server process is running
-
-### Slow Performance
-
-1. **Large projects**: Consider excluding `node_modules` and other large directories
-2. **Server timeout**: Increase `startupTimeout` in server configuration for slow servers
-
-### No Results
-
-1. **Server not ready**: The server may still be indexing. For C/C++ projects with clangd, ensure `--background-index` is in the args and a `compile_commands.json` (or `compile_flags.txt`) exists in the project root or a parent directory. Use `--compile-commands-dir=<path>` if it is in a build subdirectory
-2. **File not saved**: Save your file for the server to pick up changes
-3. **Wrong language**: Check if the correct server is running for your language
-4. **Check the process**: Run `ps aux | grep <server-name>` to verify the server is actually running
-
-### Debugging
-
-LSP does not have a separate debug flag. Use Matilda Code's normal debug mode together with the LSP feature flag:
-
-```bash
-matilda --experimental-lsp --debug
-```
-
-Debug logs are written to the session debug log directory. To check LSP-related entries:
-
-```bash
-# Default runtime directory
-rg "LSP|Native LSP|clangd|connection closed" ~/.matilda/debug/latest
-# Or, without ripgrep:
-grep -E "LSP|Native LSP|clangd|connection closed" ~/.matilda/debug/latest
-
-# If MATILDA_RUNTIME_DIR is configured
-rg "LSP|Native LSP|clangd|connection closed" "$MATILDA_RUNTIME_DIR/debug/latest"
-```
-
-Useful entries include:
-
-- `[LSP] ...`: Logs emitted by the native LSP service and server manager.
-- `[CONFIG] Native LSP status after discovery: ...`: LSP server configuration discovered for the session.
-- `[CONFIG] Native LSP status after startup: ...`: Server startup result, including ready/failed counts.
-- `[STATUS] LSP status snapshot for /status: ...`: Status snapshot printed when running `/status` in debug mode.
-
-You can also run `/status` in the CLI to see a short LSP summary:
-
-```text
-LSP: disabled
-LSP: enabled, 1/1 ready
-LSP: enabled, 0/1 ready (1 failed)
-LSP: enabled, no servers configured
-LSP: enabled, status unavailable
-```
-
-For per-server details, run `/lsp`:
-
-```text
-**LSP Server Status**
-
-| Server | Command | Languages | Status |
-|--------|---------|-----------|--------|
-| clangd | `clangd` | c, cpp | READY |
-| pyright | `pyright-langserver` | python | FAILED - startup failed |
-```
-
-Common error messages to look for:
-
-```text
-command path is unsafe        -> relative path escapes workspace, use absolute path or add to PATH
-command not found             -> server binary not installed or not in PATH
-requires trusted workspace    -> run /trust first
-LSP connection closed         -> server started but exited or closed stdio before replying to initialize
-```
-
-For clangd startup failures, verify the server directly from the project root:
-
-```bash
-clangd --version
-clangd --check=/path/to/file.cpp --log=verbose
-```
-
-C/C++ projects should usually provide a `compile_commands.json` or `compile_flags.txt`. If the compile database is in a build directory, pass it to clangd:
-
-```json
-{
-  "cpp": {
-    "command": "clangd",
-    "args": ["--background-index", "--compile-commands-dir=build"]
-  }
-}
-```
-
-```bash
-ps aux | grep clangd   # or typescript-language-server, jdtls, etc.
-```
-
-## Extension LSP Configuration
-
-Extensions can provide LSP server configurations through the `lspServers` field in their `plugin.json`. This can be either an inline object or a path to a `.lsp.json` file. Matilda Code loads these configs when the extension is enabled. The format is the same language-keyed layout used in project `.lsp.json` files.
-
-## Best Practices
-
-1. **Install language servers globally**: This ensures they're available in all projects
-2. **Use project-specific settings**: Configure server options per project when needed via `.lsp.json`
-3. **Keep servers updated**: Update your language servers regularly for best results
-4. **Trust wisely**: Only trust workspaces from trusted sources
-
-## FAQ
-
-### Q: How do I enable LSP?
-
-Use the `--experimental-lsp` flag when starting Matilda Code:
-
-```bash
-matilda --experimental-lsp
-```
-
-### Q: How do I know which language servers are running?
-
-Start Matilda Code with LSP and debug mode enabled:
-
-```bash
-matilda --experimental-lsp --debug
-```
-
-Then run `/status` for a short summary, `/lsp` for per-server status, or inspect the debug log:
-
-```bash
-# Default runtime directory
-rg "LSP|Native LSP|<server-name>" ~/.matilda/debug/latest
-# Or:
-grep -E "LSP|Native LSP|<server-name>" ~/.matilda/debug/latest
-
-# If MATILDA_RUNTIME_DIR is configured
-rg "LSP|Native LSP|<server-name>" "$MATILDA_RUNTIME_DIR/debug/latest"
-```
-
-LSP uses Matilda Code's normal `--debug` mode; there is no separate LSP debug flag.
-
-### Q: Can I use multiple language servers for the same file type?
-
-Yes, but only one will be used for each operation. The first server that returns results wins.
-
-### Q: Does LSP work in sandbox mode?
-
-LSP servers run outside the sandbox to access your code. They're subject to workspace trust controls.