@maincode-ai/matilda-code 0.21.13 → 0.22.0

package/bundled/mainy/docs/features/followup-suggestions.md

@@ -1,109 +0,0 @@
-# Followup Suggestions
-
-Matilda Code can predict what you want to type next and show it as ghost text in the input area. This feature uses an LLM call to analyze the conversation context and generate a natural next step suggestion.
-
-This feature works end-to-end in the CLI. In the WebUI, the hook and UI plumbing are available, but host applications must trigger suggestion generation and wire the followup state for suggestions to appear.
-
-## How It Works
-
-After Matilda Code finishes responding, a suggestion appears as dimmed text in the input area after a short delay (~300ms). For example, after fixing a bug, you might see:
-
-```
-> run the tests
-```
-
-The suggestion is generated by sending the conversation history to the model, which predicts what you would naturally type next. If the response contains an explicit tip (e.g., `Tip: type post comments to publish findings`), the suggested action is extracted automatically.
-
-## Accepting Suggestions
-
-| Key           | Action                                           |
-| ------------- | ------------------------------------------------ |
-| `Tab`         | Accept the suggestion and fill it into the input |
-| `Enter`       | Accept the suggestion and submit it immediately  |
-| `Right Arrow` | Accept the suggestion and fill it into the input |
-| Any typing    | Dismiss the suggestion and type normally         |
-
-## When Suggestions Appear
-
-Suggestions are generated when all of the following conditions are met:
-
-- The model has completed its response (not during streaming)
-- At least 2 model turns have occurred in the conversation
-- There are no errors in the most recent response
-- No confirmation dialogs are pending (e.g., shell confirmation, permissions)
-- The approval mode is not set to `plan`
-- The feature is enabled in settings (disabled by default — set `ui.enableFollowupSuggestions` to `true` to turn it on)
-
-Suggestions will not appear in non-interactive mode (e.g., headless/SDK mode).
-
-Suggestions are automatically dismissed when:
-
-- You start typing
-- A new model turn begins
-- The suggestion is accepted
-
-## Fast Model
-
-By default, suggestions use the same model as your main conversation. For faster and cheaper suggestions, configure a dedicated fast model:
-
-### Via command
-
-```
-/model --fast matilda3-coder-flash
-```
-
-Or use `/model --fast` (without a model name) to open a selection dialog.
-
-### Via settings.json
-
-```json
-{
-  "fastModel": "matilda3-coder-flash"
-}
-```
-
-The fast model is used for prompt suggestions and speculative execution. When not configured, the main conversation model is used as fallback.
-
-Thinking/reasoning mode is automatically disabled for all background tasks (suggestion generation and speculation), regardless of your main model's thinking configuration. This avoids wasting tokens on internal reasoning that isn't needed for these tasks.
-
-## Configuration
-
-These settings can be configured in `settings.json`:
-
-| Setting                        | Type    | Default | Description                                                        |
-| ------------------------------ | ------- | ------- | ------------------------------------------------------------------ |
-| `ui.enableFollowupSuggestions` | boolean | `false` | Enable or disable followup suggestions                             |
-| `ui.enableCacheSharing`        | boolean | `true`  | Use cache-aware forked queries to reduce cost (experimental)       |
-| `ui.enableSpeculation`         | boolean | `false` | Speculatively execute suggestions before submission (experimental) |
-| `fastModel`                    | string  | `""`    | Model for prompt suggestions and speculative execution             |
-
-### Example
-
-```json
-{
-  "fastModel": "matilda3-coder-flash",
-  "ui": {
-    "enableFollowupSuggestions": true,
-    "enableCacheSharing": true
-  }
-}
-```
-
-## Monitoring
-
-Suggestion model usage appears in `/stats` output, showing tokens consumed by the fast model for suggestion generation.
-
-The fast model is also shown in `/about` output under "Fast Model".
-
-## Suggestion Quality
-
-Suggestions go through quality filters to ensure they are useful:
-
-- Must be 2-12 words (CJK: 2-30 characters), under 100 characters total
-- Cannot be evaluative ("looks good", "thanks")
-- Cannot use AI voice ("Let me...", "I'll...")
-- Cannot be multiple sentences or contain formatting (markdown, newlines)
-- Cannot be meta-commentary ("nothing to suggest", "silence")
-- Cannot be error messages or prefixed labels ("Suggestion: ...")
-- Single-word suggestions are only allowed for common commands (yes, commit, push, etc.)
-- Slash commands (e.g., `/commit`) are always allowed as single-word suggestions

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

@@ -1,448 +0,0 @@
-# Headless Mode
-
-Headless mode allows you to run Matilda Code programmatically from command line
-scripts and automation tools without any interactive UI. This is ideal for
-scripting, automation, CI/CD pipelines, and building AI-powered tools.
-
-## Overview
-
-The headless mode provides a headless interface to Matilda Code that:
-
-- Accepts prompts via command line arguments or stdin
-- Returns structured output (text or JSON)
-- Supports file redirection and piping
-- Enables automation and scripting workflows
-- Provides consistent exit codes for error handling
-- Can resume previous sessions scoped to the current project for multi-step automation
-
-## Basic Usage
-
-### Direct Prompts
-
-Use the `--prompt` (or `-p`) flag to run in headless mode:
-
-```bash
-matilda --prompt "What is machine learning?"
-```
-
-### Stdin Input
-
-Pipe input to Matilda Code from your terminal:
-
-```bash
-echo "Explain this code" | matilda
-```
-
-### Combining with File Input
-
-Read from files and process with Matilda Code:
-
-```bash
-cat README.md | matilda --prompt "Summarize this documentation"
-```
-
-### Resume Previous Sessions (Headless)
-
-Reuse conversation context from the current project in headless scripts:
-
-```bash
-# Continue the most recent session for this project and run a new prompt
-matilda --continue -p "Run the tests again and summarize failures"
-
-# Resume a specific session ID directly (no UI)
-matilda --resume 123e4567-e89b-12d3-a456-426614174000 -p "Apply the follow-up refactor"
-
-# Start a fresh session with a caller-chosen ID (must be a valid UUID)
-matilda --session-id 123e4567-e89b-12d3-a456-426614174000 -p "Start a tracked run"
-```
-
-> [!note]
->
-> - Session data is project-scoped JSONL under `~/.matilda/projects/<sanitized-cwd>/chats`.
-> - Restores conversation history, tool outputs, and chat-compression checkpoints before sending the new prompt.
-> - `--session-id` must be a valid UUID (e.g. from `uuidgen`). Non-UUID values are rejected at parse time.
-
-## Customize the Main Session Prompt
-
-You can change the main session system prompt for a single CLI run without editing shared memory files.
-
-### Override the Built-in System Prompt
-
-Use `--system-prompt` to replace Matilda Code's built-in main-session prompt for the current run:
-
-```bash
-matilda -p "Review this patch" --system-prompt "You are a terse release reviewer. Report only blocking issues."
-```
-
-### Append Extra Instructions
-
-Use `--append-system-prompt` to keep the built-in prompt and add extra instructions for this run:
-
-```bash
-matilda -p "Review this patch" --append-system-prompt "Be terse and focus on concrete findings."
-```
-
-You can combine both flags when you want a custom base prompt plus an extra run-specific instruction:
-
-```bash
-matilda -p "Summarize this repository" \
-  --system-prompt "You are a migration planner." \
-  --append-system-prompt "Return exactly three bullets."
-```
-
-> [!note]
->
-> - `--system-prompt` applies only to the current run's main session.
-> - Loaded memory and context files such as `MATILDA.md` are still appended after `--system-prompt`.
-> - `--append-system-prompt` is applied after the built-in prompt and loaded memory, and can be used together with `--system-prompt`.
-
-## Output Formats
-
-Matilda Code supports multiple output formats for different use cases:
-
-### Text Output (Default)
-
-Standard human-readable output:
-
-```bash
-matilda -p "What is the capital of France?"
-```
-
-Response format:
-
-```
-The capital of France is Paris.
-```
-
-For long-horizon / redirected runs, assistant text is **streamed to stdout as
-it arrives** (not held until the process exits). Tool starts are reported on
-**stderr** as `[tool] <name>` so progress is visible without contaminating the
-final answer:
-
-```bash
-matilda -p "Implement the full TASK.md" --max-wall-time 10m --bogan \
-  > out.txt 2> progress.txt
-# progress.txt will show [tool] lines while out.txt grows with the answer
-```
-
-### JSON Output
-
-Returns structured data as a JSON array. All messages are buffered and output together when the session completes. This format is ideal for programmatic processing and automation scripts.
-
-The JSON output is an array of message objects. The output includes multiple message types: system messages (session initialization), assistant messages (AI responses), and result messages (execution summary).
-
-#### Example Usage
-
-```bash
-matilda -p "What is the capital of France?" --output-format json
-```
-
-Output (at end of execution):
-
-```json
-[
-  {
-    "type": "system",
-    "subtype": "session_start",
-    "uuid": "...",
-    "session_id": "...",
-    "model": "matilda3-coder-plus",
-    ...
-  },
-  {
-    "type": "assistant",
-    "uuid": "...",
-    "session_id": "...",
-    "message": {
-      "id": "...",
-      "type": "message",
-      "role": "assistant",
-      "model": "matilda3-coder-plus",
-      "content": [
-        {
-          "type": "text",
-          "text": "The capital of France is Paris."
-        }
-      ],
-      "usage": {...}
-    },
-    "parent_tool_use_id": null
-  },
-  {
-    "type": "result",
-    "subtype": "success",
-    "uuid": "...",
-    "session_id": "...",
-    "is_error": false,
-    "duration_ms": 1234,
-    "result": "The capital of France is Paris.",
-    "usage": {...}
-  }
-]
-```
-
-### Stream-JSON Output
-
-Stream-JSON format emits JSON messages immediately as they occur during execution, enabling real-time monitoring. This format uses line-delimited JSON where each message is a complete JSON object on a single line.
-
-```bash
-matilda -p "Explain TypeScript" --output-format stream-json
-```
-
-### Dual output (`--json-file` / `--json-fd`)
-
-Headless runs can also emit a **sidecar** stream of structured JSON events
-while keeping the primary `--output-format` on stdout. This is useful for
-long-horizon / CI monitoring without switching the main output to stream-json.
-
-```bash
-# Text answer on stdout; full event stream on disk
-matilda -p "Implement the feature in TASK.md" \
-  --output-format text \
-  --json-file ./logs/events.jsonl \
-  --max-wall-time 10m \
-  --bogan
-
-# Tail progress while the run is in flight
-tail -f ./logs/events.jsonl
-```
-
-- Works in both interactive (TUI) and headless modes.
-- Parent directories for `--json-file` are created when missing.
-- Mutually exclusive with `--json-fd`.
-
-Output (streaming as events occur):
-
-```json
-{"type":"system","subtype":"session_start","uuid":"...","session_id":"..."}
-{"type":"assistant","uuid":"...","session_id":"...","message":{...}}
-{"type":"result","subtype":"success","uuid":"...","session_id":"..."}
-```
-
-When combined with `--include-partial-messages`, additional stream events are emitted in real-time (message_start, content_block_delta, etc.) for real-time UI updates.
-
-```bash
-matilda -p "Write a Python script" --output-format stream-json --include-partial-messages
-```
-
-### Input Format
-
-The `--input-format` parameter controls how Matilda Code consumes input from standard input:
-
-- **`text`** (default): Standard text input from stdin or command-line arguments
-- **`stream-json`**: JSON message protocol via stdin for bidirectional communication
-
-> **Note:** Stream-json input mode is currently under construction and is intended for SDK integration. It requires `--output-format stream-json` to be set.
-
-### File Redirection
-
-Save output to files or pipe to other commands:
-
-```bash
-# Save to file
-matilda -p "Explain Docker" > docker-explanation.txt
-matilda -p "Explain Docker" --output-format json > docker-explanation.json
-
-# Append to file
-matilda -p "Add more details" >> docker-explanation.txt
-
-# Pipe to other tools
-matilda -p "What is Kubernetes?" --output-format json | jq '.response'
-matilda -p "Explain microservices" | wc -w
-matilda -p "List programming languages" | grep -i "python"
-
-# Stream-JSON output for real-time processing
-matilda -p "Explain Docker" --output-format stream-json | jq '.type'
-matilda -p "Write code" --output-format stream-json --include-partial-messages | jq '.event.type'
-```
-
-## Configuration Options
-
-Key command-line options for headless usage:
-
-| Option                       | Description                                                              | Example                                                                     |
-| ---------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
-| `--prompt`, `-p`             | Run in headless mode                                                     | `matilda -p "query"`                                                        |
-| `--output-format`, `-o`      | Specify output format (text, json, stream-json)                          | `matilda -p "query" --output-format json`                                   |
-| `--input-format`             | Specify input format (text, stream-json)                                 | `matilda --input-format text --output-format stream-json`                   |
-| `--include-partial-messages` | Include partial messages in stream-json output                           | `matilda -p "query" --output-format stream-json --include-partial-messages` |
-| `--system-prompt`            | Override the main session system prompt for this run                     | `matilda -p "query" --system-prompt "You are a terse reviewer."`            |
-| `--append-system-prompt`     | Append extra instructions to the main session system prompt for this run | `matilda -p "query" --append-system-prompt "Focus on concrete findings."`   |
-| `--debug`, `-d`              | Enable debug mode                                                        | `matilda -p "query" --debug`                                                |
-| `--all-files`, `-a`          | Include all files in context                                             | `matilda -p "query" --all-files`                                            |
-| `--include-directories`      | Include additional directories                                           | `matilda -p "query" --include-directories src,docs`                         |
-| `--yolo`, `-y`               | Auto-approve all actions                                                 | `matilda -p "query" --yolo`                                                 |
-| `--approval-mode`            | Set approval mode                                                        | `matilda -p "query" --approval-mode auto_edit`                              |
-| `--continue`                 | Resume the most recent session for this project                          | `matilda --continue -p "Pick up where we left off"`                         |
-| `--resume [sessionId]`       | Resume a specific session (or choose interactively)                      | `matilda --resume 123e... -p "Finish the refactor"`                         |
-| `--max-session-turns`        | Cap the number of user/model/tool turns in the run                       | `matilda -p "..." --max-session-turns 30`                                   |
-| `--max-wall-time`            | Wall-clock budget; accepts `90` (s), `30s`, `5m`, `1h`, `1.5h`           | `matilda -p "..." --max-wall-time 10m`                                      |
-| `--max-tool-calls`           | Cumulative tool-call budget for the run                                  | `matilda -p "..." --max-tool-calls 50`                                      |
-
-For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](../configuration/settings).
-
-## Safety in unattended runs
-
-Headless / CI runs combined with `--yolo` (or `--approval-mode=yolo`) auto-approve every tool call, including `shell`, `write`, and `edit`. **`--yolo` does not enable a sandbox** — those tools run at the host process's privilege level. When Matilda Code detects this combination with no sandbox configured, it prints a one-line warning to stderr at startup. Suppress the warning with `MATILDA_CODE_SUPPRESS_YOLO_WARNING=1` once you've reviewed the trade-off.
-
-### Run-level budgets
-
-Matilda Code can abort an unattended run when it crosses one of the following thresholds. Each is `-1` (unlimited) by default; setting any one is enough to bound runaway behavior. They are enforced cooperatively against the same `AbortController` that already carries SIGINT, so a budget abort emits a structured `FatalBudgetExceededError` (exit code **55**) — distinct from the turn-cap exit code 53 and SIGINT's 130 so CI scripts can branch on the reason.
-
-| Flag                  | Settings key               | What it bounds                                                                                                                                                                                                |
-| --------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--max-wall-time`     | `model.maxWallTimeSeconds` | Wall-clock duration of the whole run. Flag accepts `90` (s), `30s`, `5m`, `1h`, `1.5h` (fractional units supported). Minimum 1s — sub-second values are rejected as typos. Settings is seconds.               |
-| `--max-tool-calls`    | `model.maxToolCalls`       | Cumulative top-level tool calls dispatched by the main run loop (counts successes _and_ failures — the model still consumes tokens on errors). See "Scope" below for subagent / structured-output exemptions. |
-| `--max-session-turns` | `model.maxSessionTurns`    | Number of user/model/tool turns; pre-existing. Exits with code 53 on overrun (distinct from budget exit 55).                                                                                                  |
-
-#### Scope
-
-- **`--max-tool-calls` counts top-level dispatches only.** When the model calls the `agent` tool, the dispatch counts as **1**; inner tool calls performed by the spawned subagent are **not** counted. A model that funnels work through subagents can do unbounded inner work under a small top-level budget. Combine with `--exclude-tools agent` if you need a tighter cap.
-- **`structured_output` is exempt from `--max-tool-calls`.** Under `--json-schema`, the model's terminal `structured_output` call is the "I'm done" contract, not real work — it doesn't count against `--max-tool-calls` so a budget-edge completion isn't aborted as a false positive. The exemption is unconditional (including failed Ajv validations), so a model stuck in a malformed-output retry loop is NOT bounded by `--max-tool-calls`; combine with `--max-session-turns` or `--max-wall-time` to cap retries.
-- **`structured_output` is NOT exempt from `--max-session-turns`.** That counter is pre-existing and bumps for every turn including the terminal contract. Size `--max-session-turns` to `N+1` if you want to allow `N` real-work turns under `--json-schema`.
-- **Single-shot vs `--input-format stream-json`:** in stream-json input mode the daemon resets the budget counters at the start of every user message; the budget is per-message, not per-process.
-- **`matilda serve` / ACP sessions:** the daemon ACP session path does NOT currently consult `--max-wall-time` / `--max-tool-calls` from settings.json. These budgets only apply to single-shot `matilda -p` runs and to `--input-format stream-json` sessions. (`matilda serve` does emit the YOLO-no-sandbox warning at boot if `tools.approvalMode: 'yolo'` is set in settings.)
-
-### Recommended combinations
-
-- **Trusted, isolated environment (ephemeral CI runner, container):** `matilda -p "..." --yolo --max-session-turns N --max-wall-time 10m --output-format json`. Pin a turn budget and a wall-clock budget so a stuck agent can't burn through your CI minutes, and capture `--output-format json` for post-run usage / tool-call auditing.
-- **Local machine or shared infra:** also pass `--sandbox` (or set `MATILDA_SANDBOX=1`) so shell / write / edit tools run inside the sandbox image.
-- **Long-running CI with retry-on-rate-limit:** combine `MATILDA_CODE_UNATTENDED_RETRY=1` with `--max-wall-time`. The retry env keeps the run alive past transient 429 / 529 responses; the wall-clock budget ensures a persistently-failing provider can't extend the job indefinitely.
-- **Bounded auditing / exploration:** for read-only tasks, `--max-tool-calls 25` caps how aggressively the model can grep / read. Combine with `--exclude-tools shell,write,edit` to make the bound meaningful.
-
-## Examples
-
-### Code review
-
-```bash
-cat src/auth.py | matilda -p "Review this authentication code for security issues" > security-review.txt
-```
-
-### Generate commit messages
-
-```bash
-result=$(git diff --cached | matilda -p "Write a concise commit message for these changes" --output-format json)
-echo "$result" | jq -r '.response'
-```
-
-### API documentation
-
-```bash
-result=$(cat api/routes.js | matilda -p "Generate OpenAPI spec for these routes" --output-format json)
-echo "$result" | jq -r '.response' > openapi.json
-```
-
-### Batch code analysis
-
-```bash
-for file in src/*.py; do
-    echo "Analyzing $file..."
-    result=$(cat "$file" | matilda -p "Find potential bugs and suggest improvements" --output-format json)
-    echo "$result" | jq -r '.response' > "reports/$(basename "$file").analysis"
-    echo "Completed analysis for $(basename "$file")" >> reports/progress.log
-done
-```
-
-### PR code review
-
-```bash
-result=$(git diff origin/main...HEAD | matilda -p "Review these changes for bugs, security issues, and code quality" --output-format json)
-echo "$result" | jq -r '.response' > pr-review.json
-```
-
-### Log analysis
-
-```bash
-grep "ERROR" /var/log/app.log | tail -20 | matilda -p "Analyze these errors and suggest root cause and fixes" > error-analysis.txt
-```
-
-### Release notes generation
-
-```bash
-result=$(git log --oneline v1.0.0..HEAD | matilda -p "Generate release notes from these commits" --output-format json)
-response=$(echo "$result" | jq -r '.response')
-echo "$response"
-echo "$response" >> CHANGELOG.md
-```
-
-### Model and tool usage tracking
-
-```bash
-result=$(matilda -p "Explain this database schema" --include-directories db --output-format json)
-total_tokens=$(echo "$result" | jq -r '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
-models_used=$(echo "$result" | jq -r '.stats.models // {} | keys | join(", ") | if . == "" then "none" else . end')
-tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0')
-tools_used=$(echo "$result" | jq -r '.stats.tools.byName // {} | keys | join(", ") | if . == "" then "none" else . end')
-echo "$(date): $total_tokens tokens, $tool_calls tool calls ($tools_used) used with models: $models_used" >> usage.log
-echo "$result" | jq -r '.response' > schema-docs.md
-echo "Recent usage trends:"
-tail -5 usage.log
-```
-
-## Persistent Retry Mode
-
-When Matilda Code runs in CI/CD pipelines or as a background daemon, a brief API outage (rate limiting or overload) should not kill a multi-hour task. **Persistent retry mode** makes Matilda Code retry transient API errors indefinitely until the service recovers.
-
-### How it works
-
-- **Transient errors only**: HTTP 429 (Rate Limit) and 529 (Overloaded) are retried indefinitely. Other errors (400, 500, etc.) still fail normally.
-- **Exponential backoff with cap**: Retry delays grow exponentially but are capped at **5 minutes** per retry.
-- **Heartbeat keepalive**: During long waits, a status line is printed to stderr every **30 seconds** to prevent CI runners from killing the process due to inactivity.
-- **Graceful degradation**: Non-transient errors and interactive mode are completely unaffected.
-
-### Activation
-
-Set the `MATILDA_CODE_UNATTENDED_RETRY` environment variable to `true` or `1` (strict match, case-sensitive):
-
-```bash
-export MATILDA_CODE_UNATTENDED_RETRY=1
-```
-
-> [!important]
-> Persistent retry requires an **explicit opt-in**. `CI=true` alone does **not** activate it — silently turning a fast-fail CI job into an infinite-wait job would be dangerous. Always set `MATILDA_CODE_UNATTENDED_RETRY` explicitly in your pipeline configuration.
-
-### Examples
-
-#### GitHub Actions
-
-```yaml
-- name: Automated code review
-  env:
-    MATILDA_CODE_UNATTENDED_RETRY: '1'
-  run: |
-    matilda -p "Review all files in src/ for security issues" \
-      --output-format json \
-      --yolo > review.json
-```
-
-#### Overnight batch processing
-
-```bash
-export MATILDA_CODE_UNATTENDED_RETRY=1
-matilda -p "Migrate all callback-style functions to async/await in src/" --yolo
-```
-
-#### Background daemon
-
-```bash
-MATILDA_CODE_UNATTENDED_RETRY=1 nohup matilda -p "Audit all dependencies for known CVEs" \
-  --output-format json > audit.json 2> audit.log &
-```
-
-### Monitoring
-
-During persistent retry, heartbeat messages are printed to **stderr**:
-
-```
-[matilda-code] Waiting for API capacity... attempt 3, retry in 45s
-[matilda-code] Waiting for API capacity... attempt 3, retry in 15s
-```
-
-These messages keep CI runners alive and let you monitor progress. They do not appear in stdout, so JSON output piped to other tools remains clean.
-
-## Resources
-
-- [CLI Configuration](../configuration/settings#command-line-arguments) - Complete configuration guide
-- [Authentication](../configuration/settings#environment-variables-for-api-access) - Setup authentication
-- [Commands](../features/commands) - Interactive commands reference
-- [Tutorials](../quickstart) - Step-by-step automation guides