@maincode-ai/matilda-code 0.21.13 → 0.22.0

package/bundled/mainy/docs/features/channels/plugins.md

@@ -1,87 +0,0 @@
-# Custom Channel Plugins
-
-You can extend the channel system with custom platform adapters packaged as [extensions](../../extension/introduction). This lets you connect Matilda Code to any messaging platform, webhook, or custom transport.
-
-## How It Works
-
-Channel plugins are loaded at startup from active extensions. When `matilda channel start` runs, it:
-
-1. Scans all enabled extensions for `channels` entries in their `matilda-extension.json`
-2. Dynamically imports each channel's entry point
-3. Registers the channel type so it can be referenced in `settings.json`
-4. Creates channel instances using the plugin's factory function
-
-Your custom channel gets the full shared pipeline for free: sender gating, group policies, session routing, slash commands, crash recovery, and the ACP bridge to the agent.
-
-## Installing a Custom Channel
-
-Install an extension that provides a channel plugin:
-
-```bash
-# From a local path (for development or private plugins)
-matilda extensions install /path/to/my-channel-extension
-
-# Or link it for development (changes are reflected immediately)
-matilda extensions link /path/to/my-channel-extension
-```
-
-## Configuring a Custom Channel
-
-Add a channel entry to `~/.matilda/settings.json` using the custom type provided by the extension:
-
-```json
-{
-  "channels": {
-    "my-bot": {
-      "type": "my-platform",
-      "apiKey": "$MY_PLATFORM_API_KEY",
-      "senderPolicy": "open",
-      "cwd": "/path/to/project"
-    }
-  }
-}
-```
-
-The `type` must match a channel type registered by an installed extension. Check the extension's documentation for which plugin-specific fields are required (e.g., `apiKey`, `webhookUrl`).
-
-All standard channel options work with custom channels:
-
-| Option         | Description                                    |
-| -------------- | ---------------------------------------------- |
-| `senderPolicy` | `allowlist`, `pairing`, or `open`              |
-| `allowedUsers` | Static allowlist of sender IDs                 |
-| `sessionScope` | `user`, `thread`, or `single`                  |
-| `cwd`          | Working directory for the agent                |
-| `instructions` | Prepended to the first message of each session |
-| `model`        | Model override for the channel                 |
-| `groupPolicy`  | `disabled`, `allowlist`, or `open`             |
-| `groups`       | Per-group settings                             |
-
-See [Overview](./overview) for details on each option.
-
-## Starting the Channel
-
-```bash
-# Start all channels including custom ones
-matilda channel start
-
-# Start just your custom channel
-matilda channel start my-bot
-```
-
-## What You Get for Free
-
-Custom channels automatically support everything built-in channels do:
-
-- **Sender policies** — `allowlist`, `pairing`, and `open` access control
-- **Group policies** — Per-group settings with optional @mention gating
-- **Session routing** — Per-user, per-thread, or single shared sessions
-- **DM pairing** — Full pairing code flow for unknown users
-- **Slash commands** — `/help`, `/clear`, `/status` work out of the box
-- **Custom instructions** — Prepended to the first message in each session
-- **Crash recovery** — Automatic restart with session preservation
-- **Per-session serialization** — Messages are queued to prevent race conditions
-
-## Building Your Own Channel Plugin
-
-Want to build a channel plugin for a new platform? See the [Channel Plugin Developer Guide](/developers/channel-plugins) for the `ChannelPlugin` interface, the `Envelope` format, and extension points.

package/bundled/mainy/docs/features/channels/telegram.md

@@ -1,120 +0,0 @@
-# Telegram
-
-This guide covers setting up a Matilda Code channel on Telegram.
-
-## Prerequisites
-
-- A Telegram account
-- A Telegram bot token (see below)
-
-## Creating a Bot
-
-1. Open Telegram and search for [@BotFather](https://t.me/BotFather)
-2. Send `/newbot` and follow the prompts to choose a name and username
-3. BotFather will give you a bot token — save it securely
-
-## Finding Your User ID
-
-To use `senderPolicy: "allowlist"` or `"pairing"`, you need your Telegram user ID (a numeric ID, not your username).
-
-The easiest way to find it:
-
-1. Search for [@userinfobot](https://t.me/userinfobot) on Telegram
-2. Send it any message — it will reply with your user ID
-
-## Configuration
-
-Add the channel to `~/.matilda/settings.json`:
-
-```json
-{
-  "channels": {
-    "my-telegram": {
-      "type": "telegram",
-      "token": "$TELEGRAM_BOT_TOKEN",
-      "senderPolicy": "allowlist",
-      "allowedUsers": ["YOUR_USER_ID"],
-      "sessionScope": "user",
-      "cwd": "/path/to/your/project",
-      "instructions": "You are a concise coding assistant responding via Telegram. Keep responses short.",
-      "groupPolicy": "disabled",
-      "groups": {
-        "*": { "requireMention": true }
-      }
-    }
-  }
-}
-```
-
-Set the bot token as an environment variable:
-
-```bash
-export TELEGRAM_BOT_TOKEN=<your-token-from-botfather>
-```
-
-Or add it to a `.env` file that gets sourced before running.
-
-## Running
-
-```bash
-# Start only the Telegram channel
-matilda channel start my-telegram
-
-# Or start all configured channels together
-matilda channel start
-```
-
-Then open your bot in Telegram and send a message. You should see "Working..." appear immediately, followed by the agent's response.
-
-## Group Chats
-
-To use the bot in Telegram groups:
-
-1. Set `groupPolicy` to `"allowlist"` or `"open"` in your channel config
-2. **Disable privacy mode** in BotFather: `/mybots` → select your bot → Bot Settings → Group Privacy → Turn Off
-3. Add the bot to a group. If it was already in the group, **remove and re-add it** (Telegram caches privacy settings from when the bot joined)
-4. If using `groupPolicy: "allowlist"`, add the group's chat ID to `groups` in your config
-
-By default, the bot requires an @mention or a reply to respond in groups. Set `"requireMention": false` for a specific group to make it respond to all messages (useful for dedicated task groups). See [Group Chats](./overview#group-chats) for full details.
-
-## Images and Files
-
-You can send photos and documents to the bot, not just text.
-
-**Photos:** Send a photo and the agent will analyze it using its vision capabilities. This requires a multimodal model — add `"model": "matilda3.5-plus"` (or another vision-capable model) to your channel config. Photo captions are passed as the message text.
-
-**Documents:** Send a PDF, code file, or any document. The bot downloads it and saves it locally so the agent can read it with its file tools. This works with any model. Telegram's file size limit is 20MB.
-
-## Tips
-
-- **Keep instructions concise-focused** — Telegram has a 4096-character message limit. Adding instructions like "keep responses short" helps the agent stay within bounds.
-- **Use `sessionScope: "user"`** — This gives each user their own conversation. Use `/clear` to start fresh.
-- **Restrict access** — Use `senderPolicy: "allowlist"` for a fixed set of users, or `"pairing"` to let new users request access with a code you approve via CLI. See [DM Pairing](./overview#dm-pairing) for details.
-
-## Message Formatting
-
-The agent's markdown responses are automatically converted to Telegram-compatible HTML. Code blocks, bold, italic, links, and lists are all supported.
-
-## Troubleshooting
-
-### Bot doesn't respond
-
-- Check that the bot token is correct and the environment variable is set
-- Verify your user ID is in `allowedUsers` if using `senderPolicy: "allowlist"`, or that you've been approved if using `"pairing"`
-- Check the terminal output for errors
-
-### Bot doesn't respond in groups
-
-- Check that `groupPolicy` is set to `"allowlist"` or `"open"` (default is `"disabled"`)
-- If using `"allowlist"`, verify the group's chat ID is in the `groups` config
-- Make sure **Group Privacy is turned off** in BotFather — without this, the bot can't see non-command messages in groups
-- If you changed privacy mode after adding the bot to a group, **remove and re-add the bot** to the group
-- By default, the bot requires an @mention or a reply. Send `@yourbotname hello` to test
-
-### "Sorry, something went wrong processing your message"
-
-This usually means the agent encountered an error. Check the terminal output for details.
-
-### Bot takes a long time to respond
-
-The agent may be running multiple tool calls (reading files, searching, etc.). The "Working..." indicator shows while the agent is processing. Complex tasks can take a minute or more.

package/bundled/mainy/docs/features/code-review.md

@@ -1,291 +0,0 @@
-# Code Review
-
-> Review code changes for correctness, security, performance, and code quality using `/review`.
-
-## Quick Start
-
-```bash
-# Review local uncommitted changes
-/review
-
-# Review a pull request (by number or URL)
-/review 123
-/review https://github.com/org/repo/pull/123
-
-# Review and post inline comments on the PR
-/review 123 --comment
-
-# Review a specific file
-/review src/utils/auth.ts
-```
-
-If there are no uncommitted changes, `/review` will let you know and stop — no agents are launched.
-
-## How It Works
-
-The `/review` command runs a multi-stage pipeline:
-
-```
-Step 1:  Determine scope (local diff / PR worktree / file)
-Step 2:  Load project review rules
-Step 3:  Run deterministic analysis (linter, typecheck)    [zero LLM cost]
-Step 4:  9 parallel review agents                          [9 LLM calls]
-           |-- Agent 1: Correctness
-           |-- Agent 2: Security
-           |-- Agent 3: Code Quality
-           |-- Agent 4: Performance & Efficiency
-           |-- Agent 5: Test Coverage
-           |-- Agent 6: Undirected Audit (3 personas: 6a/6b/6c)
-           '-- Agent 7: Build & Test (runs shell commands)
-Step 5:  Deduplicate --> Batch verify --> Aggregate         [1 LLM call]
-Step 6:  Iterative reverse audit (1-3 rounds, gap finding) [1-3 LLM calls]
-Step 7:  Present findings + verdict
-Step 8:  Autofix (user-confirmed, optional)
-Step 9:  Post PR inline comments (if requested)
-Step 10: Save report + incremental cache
-Step 11: Clean up (remove worktree + temp files)
-```
-
-### Review Agents
-
-| Agent                             | Focus                                                                                       |
-| --------------------------------- | ------------------------------------------------------------------------------------------- |
-| Agent 1: Correctness              | Logic errors, edge cases, null handling, race conditions, type safety                       |
-| Agent 2: Security                 | Injection, XSS, SSRF, auth bypass, sensitive data exposure                                  |
-| Agent 3: Code Quality             | Style consistency, naming, duplication, dead code                                           |
-| Agent 4: Performance & Efficiency | N+1 queries, memory leaks, unnecessary re-renders, bundle size                              |
-| Agent 5: Test Coverage            | Untested code paths in the diff, missing branch coverage, weak assertions                   |
-| Agent 6: Undirected Audit         | 3 parallel personas (attacker / 3am-oncall / maintainer) — catches cross-dimensional issues |
-| Agent 7: Build & Test             | Runs build and test commands, reports failures                                              |
-
-All agents run in parallel (Agent 6 launches 3 persona variants concurrently, totaling 9 parallel tasks for same-repo reviews). Findings from Agents 1-6 are verified in a **single batch verification pass** (one agent reviews all findings at once, keeping verification cost fixed regardless of finding count). After verification, **iterative reverse audit** runs 1-3 rounds of gap-finding — each round receives the cumulative finding list from prior rounds, so successive rounds focus on whatever's left undiscovered. The loop stops as soon as a round returns "No issues found", or after 3 rounds (hard cap). Reverse audit findings skip verification (the agent already has full context) and are included as high-confidence results.
-
-## Deterministic Analysis
-
-Before the LLM agents run, `/review` automatically runs your project's existing linters and type checkers:
-
-| Language              | Tools detected                                                   |
-| --------------------- | ---------------------------------------------------------------- |
-| TypeScript/JavaScript | `tsc --noEmit`, `npm run lint`, `eslint`                         |
-| Python                | `ruff`, `mypy`, `flake8`                                         |
-| Rust                  | `cargo clippy`                                                   |
-| Go                    | `go vet`, `golangci-lint`                                        |
-| Java                  | `mvn compile`, `checkstyle`, `spotbugs`, `pmd`                   |
-| C/C++                 | `clang-tidy` (if `compile_commands.json` available)              |
-| Other                 | Auto-discovered from CI config (`.github/workflows/*.yml`, etc.) |
-
-For projects that don't match standard patterns (e.g., OpenJDK), `/review` reads CI configuration files to discover what lint/check commands the project uses. No user configuration needed.
-
-Deterministic findings are tagged with `[linter]` or `[typecheck]` and skip LLM verification — they are ground truth.
-
-- **Errors** → Critical severity
-- **Warnings** → Nice to have (terminal only, not posted as PR comments)
-
-If a tool is not installed or times out, it is skipped with an informational note.
-
-## Severity Levels
-
-| Severity         | Meaning                                                             | Posted as PR comment?      |
-| ---------------- | ------------------------------------------------------------------- | -------------------------- |
-| **Critical**     | Must fix before merging (bugs, security, data loss, build failures) | Yes (high-confidence only) |
-| **Suggestion**   | Recommended improvement                                             | Yes (high-confidence only) |
-| **Nice to have** | Optional optimization                                               | No (terminal only)         |
-
-Low-confidence findings appear in a separate "Needs Human Review" section in the terminal and are never posted as PR comments.
-
-## Autofix
-
-After presenting findings, `/review` offers to auto-apply fixes for Critical and Suggestion findings that have clear solutions:
-
-```
-Found 3 issues with auto-fixable suggestions. Apply auto-fixes? (y/n)
-```
-
-- Fixes are applied using the `edit` tool (targeted replacements, not full-file rewrites)
-- Per-file linter checks run after fixes to verify they don't introduce new issues
-- For PR reviews, fixes are committed and pushed from the worktree automatically — your working tree stays clean
-- Nice to have and low-confidence findings are never auto-fixed
-- PR review submission always uses the **pre-fix verdict** (e.g., "Request changes") since the remote PR hasn't been updated until the autofix push completes
-
-## Worktree Isolation
-
-When reviewing a PR, `/review` creates a temporary git worktree (`.matilda/tmp/review-pr-<number>`) instead of switching your current branch. This means:
-
-- Your working tree, staged changes, and current branch are **never touched**
-- Dependencies are installed in the worktree (`npm ci`, etc.) so linting and build/test work
-- Build and test commands run in isolation without polluting your local build cache
-- If anything goes wrong, your environment is unaffected — just delete the worktree
-- The worktree is automatically cleaned up after the review completes
-- If a review is interrupted (Ctrl+C, crash), the next `/review` of the same PR automatically cleans up the stale worktree before starting fresh
-- Review reports and cache are saved to the main project directory (not the worktree)
-
-## Cross-repo PR Review
-
-You can review PRs from other repositories by passing the full URL:
-
-```bash
-/review https://github.com/other-org/other-repo/pull/456
-```
-
-This runs in **lightweight mode** — no worktree, no linter, no build/test, no autofix. The review is based on the diff text only (fetched via GitHub API). PR comments can still be posted if you have write access.
-
-| Capability                                                 | Same-repo | Cross-repo                    |
-| ---------------------------------------------------------- | --------- | ----------------------------- |
-| LLM review (Agents 1-6 + verify + iterative reverse audit) | ✅        | ✅                            |
-| Agent 7: Build & test                                      | ✅        | ❌ (no local codebase)        |
-| Deterministic analysis (linter/typecheck)                  | ✅        | ❌                            |
-| Cross-file impact analysis                                 | ✅        | ❌                            |
-| Autofix                                                    | ✅        | ❌                            |
-| PR inline comments                                         | ✅        | ✅ (if you have write access) |
-| Incremental review cache                                   | ✅        | ❌                            |
-
-## PR Inline Comments
-
-Use `--comment` to post findings directly on the PR:
-
-```bash
-/review 123 --comment
-```
-
-Or, after running `/review 123`, type `post comments` to publish findings without re-running the review.
-
-**What gets posted:**
-
-- High-confidence Critical and Suggestion findings as inline comments on specific lines
-- For Approve/Request changes verdicts: a review summary with the verdict
-- For Comment verdict with all inline comments posted: no separate summary (inline comments are sufficient)
-- Model attribution footer on each comment (e.g., _— matilda3-coder via Matilda Code /review_)
-
-**What stays terminal-only:**
-
-- Nice to have findings (including linter warnings)
-- Low-confidence findings
-
-**Self-authored PRs:** GitHub does not allow you to submit `APPROVE` or `REQUEST_CHANGES` reviews on your own pull request — both fail with HTTP 422. When `/review` detects that the PR author matches the current authenticated user, it automatically downgrades the API event to `COMMENT` regardless of verdict, so the submission still succeeds. The terminal still shows the honest verdict ("Approve" / "Request changes" / "Comment") — only the GitHub-side review event is neutralized. The actual findings still appear as inline comments on specific lines, so substantive feedback is unchanged.
-
-**Re-reviewing a PR with prior Matilda Code comments:** when `/review` runs on a PR that already has previous Matilda Code review comments, it classifies them before posting new ones. Only **same-line overlap** (an existing comment on the same `(path, line)` as a new finding) prompts you to confirm — that's the case where you'd see a visual duplicate on the same code line. Comments from older commits, replied-to comments (treated as resolved), and comments that simply don't overlap with any new finding are silently skipped, with a terminal log line so you know what was filtered.
-
-**CI / build status check before APPROVE:** if the verdict is "Approve", `/review` queries the PR's check-runs and commit statuses before submitting. If any check has failed (or all checks are still pending), the API event is automatically downgraded from `APPROVE` to `COMMENT`, with the review body explaining why. Rationale: the LLM review reads code statically and cannot see runtime test failures; approving while CI is red would be misleading. The inline findings are still posted unchanged. If you want to approve anyway (e.g., a known-flaky CI failure), submit the GitHub approval manually after verifying.
-
-## Follow-up Actions
-
-After the review, context-aware tips appear as ghost text. Press Tab to accept:
-
-| State after review                 | Tip                | What happens                            |
-| ---------------------------------- | ------------------ | --------------------------------------- |
-| Local review with unfixed findings | `fix these issues` | LLM interactively fixes each finding    |
-| PR review with findings            | `post comments`    | Posts PR inline comments (no re-review) |
-| PR review, zero findings           | `post comments`    | Approves the PR on GitHub (LGTM)        |
-| Local review, all clear            | `commit`           | Commits your changes                    |
-
-Note: `fix these issues` is only available for local reviews. For PR reviews, use Autofix (Step 8) — the worktree is cleaned up after the review, so post-review interactive fixing is not possible.
-
-## Project Review Rules
-
-You can customize review criteria per project. `/review` reads rules from these files (in order):
-
-1. `.matilda/review-rules.md` (Matilda Code native)
-2. `.github/copilot-instructions.md` (preferred) or `copilot-instructions.md` (fallback — only one is loaded, not both)
-3. `AGENTS.md` — `## Code Review` section
-4. `MATILDA.md` — `## Code Review` section
-
-Rules are injected into the LLM review agents (1-6) as additional criteria. For PR reviews, rules are read from the **base branch** to prevent a malicious PR from injecting bypass rules.
-
-Example `.matilda/review-rules.md`:
-
-```markdown
-# Review Rules
-
-- All API endpoints must validate authentication
-- Database queries must use parameterized statements
-- React components must not use inline styles
-- Error messages must not expose internal paths
-```
-
-## Incremental Review
-
-When reviewing a PR that was previously reviewed, `/review` only examines changes since the last review:
-
-```bash
-# First review — full review, cache created
-/review 123
-
-# PR updated with new commits — only new changes reviewed
-/review 123
-```
-
-### Cross-model review
-
-If you switch models (via `/model`) and re-review the same PR, `/review` detects the model change and runs a full review instead of skipping:
-
-```bash
-# Review with model A
-/review 123
-
-# Switch model
-/model
-
-# Review again — full review with model B (not skipped)
-/review 123
-# → "Previous review used matilda3-coder. Running full review with gpt-4o for a second opinion."
-```
-
-Cache is stored in `.matilda/review-cache/` and tracks both the commit SHA and model ID. Make sure this directory is in your `.gitignore` (a broader rule like `.matilda/*` also works). If the cached commit was rebased away, it falls back to a full review.
-
-## Review Reports
-
-For same-repo reviews, results are saved as a Markdown file in your project's `.matilda/reviews/` directory (cross-repo lightweight reviews skip report persistence):
-
-```
-.matilda/reviews/2026-04-06-143022-pr-123.md
-.matilda/reviews/2026-04-06-150510-local.md
-```
-
-Reports include: timestamp, diff stats, deterministic analysis results, all findings with verification status, and the verdict.
-
-## Cross-file Impact Analysis
-
-When code changes modify exported functions, classes, or interfaces, the review agents automatically search for all callers and check compatibility:
-
-- Parameter count/type changes
-- Return type changes
-- Removed or renamed public methods
-- Breaking API changes
-
-For large diffs (>10 modified symbols), analysis prioritizes functions with signature changes.
-
-## Token Efficiency
-
-The review pipeline uses a bounded number of LLM calls regardless of how many findings are produced:
-
-| Stage                            | LLM calls         | Notes                                               |
-| -------------------------------- | ----------------- | --------------------------------------------------- |
-| Deterministic analysis (Step 3)  | 0                 | Shell commands only                                 |
-| Review agents (Step 4)           | 9 (or 8)          | Run in parallel; Agent 7 skipped in cross-repo mode |
-| Batch verification (Step 5)      | 1                 | Single agent verifies all findings at once          |
-| Iterative reverse audit (Step 6) | 1-3               | Loops until "No issues found" or 3-round cap        |
-| **Total**                        | **11-13 (10-12)** | Same-repo: 11-13; cross-repo: 10-12 (no Agent 7)    |
-
-Most PRs converge to the lower end of the range (1 reverse audit round); the cap prevents runaway cost on pathological cases.
-
-## What's NOT Flagged
-
-The review intentionally excludes:
-
-- Pre-existing issues in unchanged code (focus on the diff only)
-- Style/formatting/naming that matches your codebase conventions
-- Issues a linter or type checker would catch (handled by deterministic analysis)
-- Subjective "consider doing X" suggestions without a real problem
-- Minor refactoring that doesn't fix a bug or risk
-- Missing documentation unless the logic is genuinely confusing
-- Issues already discussed in existing PR comments (avoids duplicating human feedback)
-
-## Design Philosophy
-
-> **Silence is better than noise.** Every comment should be worth the reader's time.
-
-- If unsure whether something is a problem → don't report it
-- Linter/typecheck issues are handled by tools, not LLM guesses
-- Same pattern across N files → aggregated into one finding
-- PR comments are high-confidence only
-- Style/formatting issues matching codebase conventions are excluded