@maincode-ai/matilda-code 0.21.11 → 0.21.13-nightly.20261026.e0eae1d8c

package/bundled/mainy/SKILL.md

@@ -72,8 +72,6 @@ Use this index to locate the right document for the user's question. Load only t
 | Topic                   | Doc Path                                     |
 | ----------------------- | -------------------------------------------- |
 | VS Code integration     | `docs/integration-vscode.md`                 |
-| Zed IDE integration     | `docs/integration-zed.md`                    |
-| JetBrains integration   | `docs/integration-jetbrains.md`              |
 | GitHub Actions          | `docs/integration-github-action.md`          |
 | IDE companion spec      | `docs/ide-integration/ide-companion-spec.md` |
 | IDE integration details | `docs/ide-integration/ide-integration.md`    |

package/bundled/mainy/docs/_meta.ts

@@ -11,8 +11,6 @@ export default {
     title: 'Outside of the terminal', // Title is optional
   },
   'integration-vscode': 'Visual Studio Code',
-  'integration-zed': 'Zed IDE',
-  'integration-jetbrains': 'JetBrains IDEs',
   'integration-github-action': 'GitHub Actions',
   'matilda-serve': 'Daemon mode (matilda serve)',
   'matilda-serve-deploy-local': 'Daemon mode — local launch templates',

package/bundled/mainy/docs/configuration/auth.md

@@ -3,8 +3,8 @@
 Matilda Code's standard sign-in uses your Matilda account. For normal
 interactive use, you do not need to create, copy, or export an API key.
 
-You can also use a Matilda API token (CI/automation) or a third-party /
-custom OpenAI-compatible provider via `/auth`.
+You can also use a Matilda API token, through `/auth` or, for CI and
+automation, the `MATILDA_API_KEY` environment variable.
 
 ## Sign in
 
@@ -60,14 +60,9 @@ tokens or `~/.matilda/matilda-auth.json` to source control.
 
 ## Other model providers
 
-`/auth` inside an interactive Matilda Code session lets you choose:
-
-- **Matilda account** or **Matilda API token**
-- **Third-party providers** (DeepSeek, OpenRouter, MiniMax, Z.AI, ModelScope, …)
-- **Custom Provider** for any OpenAI-compatible endpoint
-
-For an advanced custom provider configuration, see the
-[Model Providers reference](model-providers.md).
+`/auth` inside an interactive Matilda Code session offers the Matilda account
+sign-in and a Matilda API token. Other providers are configured in
+`settings.json`; see the [Model Providers reference](model-providers.md).
 
 ## Troubleshooting
 

package/bundled/mainy/docs/configuration/model-providers.md

@@ -4,7 +4,7 @@ Matilda Code allows you to configure multiple model providers through the `model
 
 ## Overview
 
-Use `modelProviders` to declare curated model lists per auth type that the `/model` picker can switch between. Keys must be valid auth types (`openai`, `anthropic`, `gemini`, etc.). Each entry requires an `id` and **must include `envKey`**, with optional `name`, `description`, `baseUrl`, and `generationConfig`. Credentials are never persisted in settings; the runtime reads them from `process.env[envKey]`. Matilda OAuth models remain hard-coded and cannot be overridden.
+Use `modelProviders` to declare curated model lists per auth type that the `/model` picker can switch between. Keys must be valid auth types (currently only `openai`). Each entry requires an `id` and **must include `envKey`**, with optional `name`, `description`, `baseUrl`, and `generationConfig`. Credentials are never persisted in settings; the runtime reads them from `process.env[envKey]`.
 
 > [!note]
 
@@ -20,12 +20,9 @@ Below are comprehensive configuration examples for different authentication type
 
 The `modelProviders` object keys must be valid `authType` values. Currently supported auth types are:
 
-| Auth Type       | Description                                                                             |
-| --------------- | --------------------------------------------------------------------------------------- |
-| `openai`        | OpenAI-compatible APIs (OpenAI, Azure OpenAI, local inference servers like vLLM/Ollama) |
-| `anthropic`     | Anthropic Claude API                                                                    |
-| `gemini`        | Google Gemini API                                                                       |
-| `matilda-oauth` | Matilda OAuth (hard-coded, cannot be overridden in `modelProviders`)                    |
+| Auth Type | Description                                                                             |
+| --------- | --------------------------------------------------------------------------------------- |
+| `openai`  | OpenAI-compatible APIs (OpenAI, Azure OpenAI, local inference servers like vLLM/Ollama) |
 
 > [!warning]
 > If an invalid auth type key is used (e.g., a typo like `"openai-custom"`), the configuration will be **silently skipped** and the models will not appear in the `/model` picker. Always use one of the supported auth type values listed above.
@@ -34,24 +31,20 @@ The `modelProviders` object keys must be valid `authType` values. Currently supp
 
 Matilda Code uses the following official SDKs to send requests to each provider:
 
-| Auth Type       | SDK Package                                                                                           |
-| --------------- | ----------------------------------------------------------------------------------------------------- |
-| `openai`        | [`openai`](https://www.npmjs.com/package/openai) - Official OpenAI Node.js SDK                        |
-| `anthropic`     | [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) - Official Anthropic SDK       |
-| `gemini`        | [`@google/genai`](https://www.npmjs.com/package/@google/genai) - Official Google GenAI SDK            |
-| `matilda-oauth` | [`openai`](https://www.npmjs.com/package/openai) with custom provider (Matilda-compatible-compatible) |
+| Auth Type | SDK Package                                                                    |
+| --------- | ------------------------------------------------------------------------------ |
+| `openai`  | [`openai`](https://www.npmjs.com/package/openai) - Official OpenAI Node.js SDK |
 
 This means the `baseUrl` you configure should be compatible with the corresponding SDK's expected API format. For example, when using `openai` auth type, the endpoint must accept OpenAI API format requests.
 
 ### OpenAI-compatible providers (`openai`)
 
-This auth type supports not only OpenAI's official API but also any OpenAI-compatible endpoint, including aggregated model providers like OpenRouter.
+This auth type supports not only OpenAI's official API but also any OpenAI-compatible endpoint.
 
 ```json
 {
   "env": {
-    "OPENAI_API_KEY": "sk-your-actual-openai-key-here",
-    "OPENROUTER_API_KEY": "sk-or-your-actual-openrouter-key-here"
+    "OPENAI_API_KEY": "sk-your-actual-openai-key-here"
   },
   "modelProviders": {
     "openai": [
@@ -96,97 +89,6 @@ This auth type supports not only OpenAI's official API but also any OpenAI-compa
             "max_tokens": 2048
           }
         }
-      },
-      {
-        "id": "openai/gpt-4o",
-        "name": "GPT-4o (via OpenRouter)",
-        "envKey": "OPENROUTER_API_KEY",
-        "baseUrl": "https://openrouter.ai/api/v1",
-        "generationConfig": {
-          "timeout": 120000,
-          "maxRetries": 3,
-          "samplingParams": {
-            "temperature": 0.7
-          }
-        }
-      }
-    ]
-  }
-}
-```
-
-### Anthropic (`anthropic`)
-
-```json
-{
-  "env": {
-    "ANTHROPIC_API_KEY": "sk-ant-your-actual-anthropic-key-here"
-  },
-  "modelProviders": {
-    "anthropic": [
-      {
-        "id": "claude-3-5-sonnet",
-        "name": "Claude 3.5 Sonnet",
-        "envKey": "ANTHROPIC_API_KEY",
-        "baseUrl": "https://api.anthropic.com/v1",
-        "generationConfig": {
-          "timeout": 120000,
-          "maxRetries": 3,
-          "contextWindowSize": 200000,
-          "samplingParams": {
-            "temperature": 0.7,
-            "max_tokens": 8192,
-            "top_p": 0.9
-          }
-        }
-      },
-      {
-        "id": "claude-3-opus",
-        "name": "Claude 3 Opus",
-        "envKey": "ANTHROPIC_API_KEY",
-        "baseUrl": "https://api.anthropic.com/v1",
-        "generationConfig": {
-          "timeout": 180000,
-          "samplingParams": {
-            "temperature": 0.3,
-            "max_tokens": 4096
-          }
-        }
-      }
-    ]
-  }
-}
-```
-
-### Google Gemini (`gemini`)
-
-```json
-{
-  "env": {
-    "GEMINI_API_KEY": "AIza-your-actual-gemini-key-here"
-  },
-  "modelProviders": {
-    "gemini": [
-      {
-        "id": "gemini-2.0-flash",
-        "name": "Gemini 2.0 Flash",
-        "envKey": "GEMINI_API_KEY",
-        "baseUrl": "https://generativelanguage.googleapis.com",
-        "capabilities": {
-          "vision": true
-        },
-        "generationConfig": {
-          "timeout": 60000,
-          "maxRetries": 2,
-          "contextWindowSize": 1000000,
-          "schemaCompliance": "auto",
-          "samplingParams": {
-            "temperature": 0.4,
-            "top_p": 0.95,
-            "max_tokens": 8192,
-            "top_k": 40
-          }
-        }
       }
     ]
   }
@@ -266,7 +168,7 @@ export VLLM_API_KEY="not-needed"
 
 > [!note]
 >
-> The `extra_body` parameter is **only supported for OpenAI-compatible providers** (`openai`, `matilda-oauth`). It is ignored for Anthropic, and Gemini providers.
+> The `extra_body` parameter is **only supported for OpenAI-compatible providers** (`openai`).
 
 > [!note]
 >
@@ -289,88 +191,6 @@ export VLLM_API_KEY="not-needed"
 >
 > Each provider example includes an `env` field to illustrate how the API key should be configured.
 
-### Overview
-
-| Model ID                  | Name                    | Description                                               |
-| ------------------------- | ----------------------- | --------------------------------------------------------- |
-| `matilda3.5-plus`         | matilda3.5-plus         | Advanced model with thinking enabled                      |
-| `matilda3.6-plus`         | matilda3.6-plus         | Latest model with thinking enabled (Pro subscribers only) |
-| `matilda3.7-plus`         | matilda3.7-plus         | Advanced model with thinking enabled                      |
-| `matilda3-coder-plus`     | matilda3-coder-plus     | Optimized for coding tasks                                |
-| `matilda3-coder-next`     | matilda3-coder-next     | Experimental coding model                                 |
-| `matilda3-max-2026-01-23` | matilda3-max-2026-01-23 | Latest max model with thinking enabled                    |
-| `glm-5`                   | glm-5                   | GLM model with thinking enabled                           |
-| `glm-4.7`                 | glm-4.7                 | GLM model with thinking enabled                           |
-| `kimi-k2.5`               | kimi-k2.5               | Kimi model with thinking and vision/video support         |
-| `MiniMax-M2.5`            | MiniMax-M2.5            | MiniMax model with thinking enabled                       |
-
-### Setup
-
-2. Run the `/auth` command in Matilda Code
-3. Select your region
-4. Enter your API key when prompted
-
-The models will be automatically configured and added to your `/model` picker.
-
-### Regions
-
-| Region | Endpoint | Description |
-| ------ | -------- | ----------- |
-
-The region is selected during authentication and stored in `settings.json` under the `modelProviders` configuration. To switch regions, re-run the `/auth` command and select a different region.
-
-### API Key Storage
-
-> [!warning]
->
-> **Security Recommendation**: For better security, it is recommended to move the API key from `settings.json` to a separate `.env` file and load it as an environment variable. For example:
->
-> ```bash
-> # ~/.matilda/.env
-> ```
->
-> Then ensure this file is added to your `.gitignore` if you're using project-level settings.
-
-### Automatic Updates
-
-Coding Plan model configurations are versioned. When Matilda Code detects a newer version of the model template, you will be prompted to update. Accepting the update will:
-
-- Replace the existing Coding Plan model configurations with the latest versions
-- Preserve any custom model configurations you've added manually
-- Automatically switch to the first model in the updated configuration
-
-The update process ensures you always have access to the latest model configurations and features without manual intervention.
-
-### Manual Configuration (Advanced)
-
-If you prefer to manually configure Coding Plan models, you can add them to your `settings.json` like any OpenAI-compatible provider:
-
-```json
-{
-  "modelProviders": {
-    "openai": [
-      {
-        "id": "matilda3-coder-plus",
-        "name": "matilda3-coder-plus",
-        "envKey": "YOUR_CUSTOM_ENV_KEY"
-      }
-    ]
-  }
-}
-```
-
-> [!note]
->
-> When using manual configuration:
->
-> - You can use any environment variable name for `envKey`
-> - You do not need to configure `codingPlan.*`
-> - **Automatic updates will not apply** to manually configured Coding Plan models
-
-> [!warning]
->
-> If you also use automatic Coding Plan configuration, automatic updates may overwrite your manual configurations if they use the same `envKey` and `baseUrl` as the automatic configuration. To avoid this, ensure your manual configuration uses a different `envKey` if possible.
-
 ## Resolution Layers and Atomicity
 
 The effective auth/model/credential values are chosen per field using the following precedence (first present wins). You can combine `--auth-type` with `--model` to point directly at a provider entry; these CLI flags run before other layers.
@@ -382,9 +202,9 @@ The effective auth/model/credential values are chosen per field using the follow
 | CLI arguments              | `--auth-type`                          | `--model`                                         | `--openaiApiKey` (or provider-specific equivalents) | `--openaiBaseUrl` (or provider-specific equivalents) | —                      | —                                 |
 | Environment variables      | —                                      | Provider-specific mapping (e.g. `OPENAI_MODEL`)   | Provider-specific mapping (e.g. `OPENAI_API_KEY`)   | Provider-specific mapping (e.g. `OPENAI_BASE_URL`)   | —                      | —                                 |
 | Settings (`settings.json`) | `security.auth.selectedType`           | `model.name`                                      | `security.auth.apiKey`                              | `security.auth.baseUrl`                              | —                      | —                                 |
-| Default / computed         | Falls back to `AuthType.MATILDA_OAUTH` | Built-in default (OpenAI ⇒ `matilda3-coder-plus`) | —                                                   | —                                                    | —                      | `Config.getProxy()` if configured |
+| Default / computed         | None: sign in or set `MATILDA_API_KEY` | Built-in default (OpenAI ⇒ `matilda3-coder-plus`) | —                                                   | —                                                    | —                      | `Config.getProxy()` if configured |
 
-\*When present, CLI auth flags override settings. Otherwise, `security.auth.selectedType` or the implicit default determine the auth type. Matilda OAuth and OpenAI are the only auth types surfaced without extra configuration.
+\*When present, CLI auth flags override settings. Otherwise, `security.auth.selectedType` or the implicit default determine the auth type. `openai`, which the Matilda sign-in uses, is the only auth type surfaced without extra configuration.
 
 > [!warning]
 >
@@ -422,7 +242,7 @@ The configuration resolution follows a strict layering model with one crucial ru
 | 1        | Programmatic overrides                        | Runtime `/model`, `/auth` changes                                                                        |
 | 2        | `modelProviders[authType][].generationConfig` | **Impermeable layer** - completely replaces all generationConfig fields; lower layers do not participate |
 | 3        | `settings.model.generationConfig`             | Only used for **Runtime Models** (when no provider model is selected)                                    |
-| 4        | Content-generator defaults                    | Provider-specific defaults (e.g., OpenAI vs Gemini) - only for Runtime Models                            |
+| 4        | Content-generator defaults                    | Provider-specific defaults (e.g., Matilda vs other endpoints) - only for Runtime Models                  |
 
 ### Atomic field treatment
 
@@ -476,24 +296,24 @@ The merge strategy for `modelProviders` itself is REPLACE: the entire `modelProv
 
 ## Reasoning / thinking configuration
 
-The optional `reasoning` field under `generationConfig` controls how aggressively the model reasons before responding. The Anthropic and Gemini converters always honor it. The OpenAI-compatible pipeline honors it **unless** `generationConfig.samplingParams` is set — see the "Interaction with `samplingParams`" caveat below.
+The optional `reasoning` field under `generationConfig` controls how aggressively the model reasons before responding. The OpenAI-compatible pipeline honors it **unless** `generationConfig.samplingParams` is set (see the "Interaction with `samplingParams`" caveat below).
 
 ```jsonc
 {
   "modelProviders": {
     "openai": [
       {
-        "id": "deepseek-v4-pro",
-        "name": "DeepSeek V4 Pro",
-        "baseUrl": "https://api.deepseek.com/v1",
-        "envKey": "DEEPSEEK_API_KEY",
+        "id": "gpt-5",
+        "name": "GPT-5",
+        "baseUrl": "https://api.openai.com/v1",
+        "envKey": "OPENAI_API_KEY",
         "generationConfig": {
-          // The four-tier scale:
-          //   'low'    | 'medium' — server-mapped to 'high' on DeepSeek
-          //   'high'   — default reasoning intensity
-          //   'max'    — DeepSeek-specific extra-strong tier
-          // Or set `false` to disable reasoning entirely.
-          "reasoning": { "effort": "max" },
+          // OpenAI's Chat Completions API reads the flat `reasoning_effort`
+          // field, not the nested `reasoning` object, so set it through
+          // `samplingParams`, whose keys are sent unchanged.
+          "samplingParams": {
+            "reasoning_effort": "high",
+          },
         },
       },
     ],
@@ -503,29 +323,23 @@ The optional `reasoning` field under `generationConfig` controls how aggressivel
 
 ### Per-provider behavior
 
-| Protocol / provider                          | Wire shape                                                           | Notes                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| -------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **OpenAI / DeepSeek** (`api.deepseek.com`)   | Flat `reasoning_effort: <effort>` body parameter                     | When `reasoning.effort` is set in the nested config shape, it's rewritten to flat `reasoning_effort` and `'low'`/`'medium'` are normalized to `'high'`, `'xhigh'` to `'max'` — mirroring DeepSeek's [server-side back-compat](https://api-docs.deepseek.com/zh-cn/api/create-chat-completion). Top-level `samplingParams.reasoning_effort` or `extra_body.reasoning_effort` overrides skip this normalization and ship verbatim. |
-| **OpenAI** (other compatible servers)        | `reasoning: { effort, ... }` passed through verbatim                 | Set via `samplingParams` (e.g. `samplingParams.reasoning_effort` for GPT-5/o-series) when the provider expects a different shape.                                                                                                                                                                                                                                                                                                |
-| **Anthropic** (real `api.anthropic.com`)     | `output_config: { effort }` plus the `effort-2025-11-24` beta header | Real Anthropic accepts `'low'`/`'medium'`/`'high'` only. `'max'` is **clamped to `'high'`** with a `debugLogger.warn` line (once per generator); if you want max effort, switch the baseURL to a DeepSeek-compatible endpoint that supports it.                                                                                                                                                                                  |
-| **Anthropic** (`api.deepseek.com/anthropic`) | Same `output_config: { effort }` + beta header                       | `'max'` is passed through unchanged.                                                                                                                                                                                                                                                                                                                                                                                             |
-| **Gemini** (`@google/genai`)                 | `thinkingConfig: { includeThoughts: true, thinkingLevel }`           | `'low'` → `LOW`, `'high'`/`'max'` → `HIGH`, others → `THINKING_LEVEL_UNSPECIFIED` (Gemini has no `MAX` tier).                                                                                                                                                                                                                                                                                                                    |
+| Protocol / provider   | Wire shape                                           | Notes                                                                                                                             |
+| --------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **OpenAI-compatible** | `reasoning: { effort, ... }` passed through verbatim | Set via `samplingParams` (e.g. `samplingParams.reasoning_effort` for GPT-5/o-series) when the provider expects a different shape. |
 
 ### `reasoning: false`
 
 Setting `reasoning: false` (the literal boolean) explicitly disables thinking on every provider — useful for cheap side queries that don't benefit from reasoning. This is honored at the request level too via `request.config.thinkingConfig.includeThoughts: false` for one-off calls (e.g. suggestion generation).
 
-On a `api.deepseek.com` baseURL, the OpenAI pipeline emits the explicit `thinking: { type: 'disabled' }` field that DeepSeek V4+ requires — the server-side default is `'enabled'`, so simply omitting `reasoning_effort` would still pay thinking latency/cost. Self-hosted DeepSeek backends (sglang/vllm) and other OpenAI-compatible servers do **not** receive this field; if you need to disable thinking on those, inject `thinking: { type: 'disabled' }` (or whatever knob your inference framework exposes) via `samplingParams`/`extra_body`.
+On Matilda's endpoint the OpenAI pipeline also sends `enable_thinking: false`. Other OpenAI-compatible servers whose models think by default need their own knob, such as `thinking: { type: 'disabled' }`, injected via `samplingParams` or `extra_body`.
 
 ### Interaction with `samplingParams` (OpenAI-compatible only)
 
 > [!warning]
 >
-> When `generationConfig.samplingParams` is set on an OpenAI-compatible provider, the pipeline ships those keys to the wire **verbatim** and skips the separate `reasoning` injection entirely. So a config like `{ samplingParams: { temperature: 0.5 }, reasoning: { effort: 'max' } }` will silently drop the reasoning field on OpenAI/DeepSeek requests.
->
-> If you set `samplingParams`, include the reasoning knob inside it directly — for DeepSeek that's `samplingParams.reasoning_effort`, for GPT-5/o-series it's `samplingParams.reasoning_effort` (their flat field) or `samplingParams.reasoning` (the nested object). For OpenRouter and other providers the field name varies; consult the provider docs.
+> When `generationConfig.samplingParams` is set on an OpenAI-compatible provider, the pipeline ships those keys to the wire **verbatim** and skips the separate `reasoning` injection entirely. So a config like `{ samplingParams: { temperature: 0.5 }, reasoning: { effort: 'max' } }` will silently drop the reasoning field on OpenAI-compatible requests.
 >
-> The Anthropic and Gemini converters are unaffected — they always read `reasoning.effort` directly regardless of `samplingParams`.
+> If you set `samplingParams`, include the reasoning knob inside it directly. For GPT-5/o-series on Chat Completions that is `samplingParams.reasoning_effort`; for other servers the field name varies, so consult their docs.
 
 ### `budget_tokens`
 
@@ -535,7 +349,7 @@ You can pin an exact thinking-token budget by including `budget_tokens` alongsid
 "reasoning": { "effort": "high", "budget_tokens": 50000 }
 ```
 
-For Anthropic this becomes `thinking.budget_tokens`. For OpenAI/DeepSeek the field is preserved but currently ignored by the server — `reasoning_effort` is the load-bearing knob.
+It is passed through inside `reasoning`, and whether it is honored depends on the server.
 
 ## Provider Models vs Runtime Models
 

package/bundled/mainy/docs/configuration/settings.md

@@ -2,7 +2,7 @@
 
 > [!tip]
 >
-> **Authentication / API keys:** Authentication (API Key, Matilda Coding Plan) and auth-related environment variables (like `OPENAI_API_KEY`) are documented in **[Authentication](../configuration/auth)**.
+> **Authentication / API keys:** Authentication (Matilda account, API token) and auth-related environment variables (like `OPENAI_API_KEY`) are documented in **[Authentication](../configuration/auth)**.
 
 > [!note]
 >
@@ -23,6 +23,34 @@ Configuration is applied in the following order of precedence (lower numbers are
 | 6     | Environment variables  | System-wide or session-specific variables, potentially loaded from `.env` files |
 | 7     | Command-line arguments | Values passed when launching the CLI                                            |
 
+## Organization usage
+
+Pass `--organization-id <uuid>` to use an organization for this invocation's
+Matilda Core Code requests. Without this option, requests keep their personal
+scope. The selection is not saved to your settings or inferred from a previous
+session. Pass it again when resuming a session that should use the organization.
+
+The server checks your current membership, product access and applicable
+allowance. Selecting an organization does not grant access or authorize wallet
+spending. If the organization is unavailable, resolve the server error instead
+of removing the option to silently change who pays.
+
+The option requires the first-party Matilda Core Code endpoint. Third-party
+providers, direct model endpoints and legacy routes reject it. Organization
+and credit-spending headers cannot be supplied through `customHeaders`.
+
+## Optional Code credits
+
+Pass `--code-credit-limit-minor 100` to allow up to 100 USD cents for each primary model generation when Core confirms that your included allowance is exhausted. The amount is per generation, not a conversation or session budget. Each tool follow-up may start another generation with the same cap. Core still enforces your account and organization limits.
+
+The option is off by default and is never saved to settings. It requires the first-party Matilda Core Code endpoint and a Matilda OAuth session. Credit-enabled requests currently support text and tools with an output limit of at most 32,768 tokens; configured lower limits are preserved.
+
+Code records request IDs and non-secret recovery metadata before sending an included or paid request when credit consent is enabled. This journal is retained even with chat recording disabled; prompts, tokens and spending capabilities are not written to it. An interrupted generation retains its original intent, and financial recovery does not recover missing output.
+
+After a restart, inspect requests with `matilda credits list --session <session-id>` and use `matilda credits recover <intent-id> --session <session-id>` for the current financial state. Add `--json` for structured output. These commands require the original Matilda account and endpoint and cannot start a generation. Forks retain references to their original sessions rather than copying spending authority.
+
+Resumed sessions require a new user prompt before model work; automatic retries, continuations and pending tool follow-ups cannot replay the old generation, even when the credit option is omitted. A new prompt uses only the new invocation's settings, so pass the credit cap again to authorize new paid work. Production availability also depends on the server's paid Code rollout.
+
 ## Settings files
 
 Matilda Code uses JSON settings files for persistent configuration. There are four locations for these files:
@@ -118,6 +146,7 @@ Settings are organized into categories. Most settings should be placed within th
 | `ui.showThinkingTrace`                  | boolean          | Show the full reasoning trace in thinking blocks instead of the collapsed one-line summary. Toggle with `Ctrl+Q` during a session or via the Settings dialog. The setting persists across sessions.                                                                                                                                                                                                                                                                                                                                                      | `false`          |
 | `ui.shellOutputMaxLines`                | number           | Max number of shell output lines shown inline. Set to `0` to disable the cap and show full output. Hidden lines are surfaced via the `+N lines` indicator. Errors, `!`-prefix user-initiated commands, confirming tools, and focused embedded shells always show full output.                                                                                                                                                                                                                                                                            | `5`              |
 | `ui.maxFps`                             | number           | Cap on terminal render rate (frames per second). Higher values (e.g. `144`) reduce input-to-render latency on high-refresh displays at the cost of more CPU. Values `<= 0` are ignored (treated as the default). Requires restart.                                                                                                                                                                                                                                                                                                                       | `60`             |
+| `ui.maxHistoryItems`                    | number           | Max number of messages kept in the on-screen history of a session; once exceeded, the oldest messages are dropped from view and a trim notice marks the cut. Set to `0` (or a negative value) for unlimited. Bounds memory use and per-message render cost on long sessions. The full transcript always remains on disk (see `/export`) and is unaffected. Only applies with fullscreen rendering (`ui.useTerminalBuffer`) enabled.                                                                                                                      | `2000`           |
 | `ui.enableWelcomeBack`                  | boolean          | Show welcome back dialog when returning to a project with conversation history. When enabled, Matilda Code will automatically detect if you're returning to a project with a previously generated project summary (`.matilda/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. If you choose **Start new chat session**, that choice is remembered for the current project until the project summary changes. This feature integrates with the `/summary` command and quit confirmation dialog. | `true`           |
 | `ui.accessibility.enableLoadingPhrases` | boolean          | Enable loading phrases (disable for accessibility).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `true`           |
 | `ui.accessibility.screenReader`         | boolean          | Enables screen reader mode, which adjusts the TUI for better compatibility with screen readers.                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `false`          |
@@ -149,8 +178,8 @@ Settings are organized into categories. Most settings should be placed within th
 | `model.maxWallTimeSeconds`                         | number  | Wall-clock budget for headless / unattended runs, in seconds. `-1` means unlimited. Overridable per-invocation via `--max-wall-time`, which requires a positive duration (`90`, `30s`, `5m`, `1h`, `1.5h`); the minimum is 1 second — sub-second values (`500ms`, `0.5`) are rejected as typos. Omit the flag to fall back to this setting. Aborts with exit code 55 when exceeded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `-1`        |
 | `model.maxToolCalls`                               | number  | Cumulative tool-call budget for a run (counts every executed tool, success or failure; `structured_output` under `--json-schema` is exempt). `-1` means unlimited; `0` means "no tool calls allowed". Capped at 1,000,000 to catch typos. Overridable via `--max-tool-calls`. Aborts with exit code 55 when exceeded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `-1`        |
 | `model.generationConfig`                           | object  | Advanced overrides passed to the underlying content generator. Supports request controls such as `timeout`, `maxRetries`, `enableCacheControl`, `splitToolMedia` (default `true`; splits tool-returned media — including images read by the built-in read_file — into a follow-up user message instead of the spec-violating `role: "tool"` message, so strict OpenAI-compatible servers like doubao / new-api / LM Studio can see it; set `false` to restore the legacy embed-in-tool behavior), `contextWindowSize` (override model's context window size), `modalities` (override auto-detected input modalities), `customHeaders` (custom HTTP headers for API requests), and `extra_body` (additional body parameters for OpenAI-compatible API requests only), along with fine-tuning knobs under `samplingParams` (for example `temperature`, `top_p`, `max_tokens`). Leave unset to rely on provider defaults. | `undefined` |
-| `model.chatCompression.contextPercentageThreshold` | number  | **REMOVED.** Auto-compaction now uses a three-tier threshold ladder (warn / auto / hard) computed internally from the model's context window via the `computeThresholds()` function — no longer user-configurable. Setting this field in `settings.json` is silently ignored (no startup warning). There is currently no replacement for "disable compression entirely" — reactive overflow recovery remains the safety net at the API layer if compression itself fails. (See PR #4345 / `docs/design/auto-compaction-threshold-redesign.md` for the redesign rationale.)                                                                                                                                                                                                                                                                                                                                             | `N/A`       |
-| `model.chatCompression.maxRecentFilesToRetain`     | number  | Number of most-recently-touched files whose current content is restored (embedded if small, otherwise referenced by path) into history after auto-compaction. `0` restores none. Env override: `MATILDA_COMPACT_MAX_RECENT_FILES`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `5`         |
+| `model.chatCompression.contextPercentageThreshold` | number  | **REMOVED.** Auto-compaction now uses a three-tier threshold ladder (warn / auto / hard) computed internally from the model's context window via the `computeThresholds()` function — no longer user-configurable. Setting this field in `settings.json` is silently ignored (no startup warning). There is currently no replacement for "disable compression entirely" — reactive overflow recovery remains the safety net at the API layer if compression itself fails.                                                                                                                                                                                                                                                                                                                                                                                                                                              | `N/A`       |
+| `model.chatCompression.maxRecentFilesToRetain`     | number  | **REMOVED.** Compaction no longer restores file contents; it lists the files the session read and changed by path, and the model reads what it needs. Setting this field in `settings.json` or `MATILDA_COMPACT_MAX_RECENT_FILES` is silently ignored.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `N/A`       |
 | `model.chatCompression.maxRecentImagesToRetain`    | number  | Number of most-recent images (tool screenshots / user pastes) restored into history after auto-compaction. `0` restores none. Env override: `MATILDA_COMPACT_MAX_RECENT_IMAGES`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `3`         |
 | `model.chatCompression.enableScreenshotTrigger`    | boolean | When `true`, auto-compaction also fires once the number of tool-returned images accumulated in history reaches `screenshotTriggerThreshold`, independent of token usage — aimed at computer-use sessions where frequent screenshots dilute model attention. Counts only images returned inside tool results, not user-pasted images. Env override: `MATILDA_COMPACT_SCREENSHOT_TRIGGER` (`1`/`true`/`0`/`false`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `true`      |
 | `model.chatCompression.screenshotTriggerThreshold` | number  | Tool-returned image count at or above which the screenshot trigger fires (only when `enableScreenshotTrigger`). Compaction resets the count — surviving images are re-embedded as top-level parts, which the trigger doesn't count — so it won't immediately re-fire. Env override: `MATILDA_COMPACT_SCREENSHOT_THRESHOLD`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `50`        |
@@ -217,7 +246,7 @@ Overrides the auto-detected input modalities for the selected model. Matilda Cod
 
 Allows you to add custom HTTP headers to all API requests. This is useful for request tracing, monitoring, API gateway routing, or when different models require different headers. For provider models, define `customHeaders` in `modelProviders[].generationConfig.customHeaders`. For runtime models without a matching provider entry, define it in `model.generationConfig.customHeaders`. No merging occurs between the two levels.
 
-The `extra_body` field allows you to add custom parameters to the request body sent to the API. This is useful for provider-specific options that are not covered by the standard configuration fields. **Note: This field is only supported for OpenAI-compatible providers (`openai`, `matilda-oauth`). It is ignored for Anthropic and Gemini providers.** For provider models, define `extra_body` in `modelProviders[].generationConfig.extra_body`. For runtime models without a matching provider entry, define it in `model.generationConfig.extra_body`.
+The `extra_body` field allows you to add custom parameters to the request body sent to the API. This is useful for provider-specific options that are not covered by the standard configuration fields. **Note: This field is only supported for OpenAI-compatible providers (`openai`).** For provider models, define `extra_body` in `modelProviders[].generationConfig.extra_body`. For runtime models without a matching provider entry, define it in `model.generationConfig.extra_body`.
 
 **model.openAILoggingDir examples:**
 
@@ -442,7 +471,7 @@ LSP server configuration is done through `.lsp.json` files in your project root
 
 | Setting                        | Type    | Description                                       | Default     |
 | ------------------------------ | ------- | ------------------------------------------------- | ----------- |
-| `security.folderTrust.enabled` | boolean | Setting to track whether Folder trust is enabled. | `false`     |
+| `security.folderTrust.enabled` | boolean | Setting to track whether Folder trust is enabled. | `true`      |
 | `security.auth.selectedType`   | string  | The currently selected authentication type.       | `undefined` |
 | `security.auth.enforcedType`   | string  | The required auth type (useful for enterprises).  | `undefined` |
 | `security.auth.useExternal`    | boolean | Whether to use an external authentication flow.   | `undefined` |
@@ -453,7 +482,7 @@ LSP server configuration is done through `.lsp.json` files in your project root
 | ------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
 | `advanced.autoConfigureMemory` | boolean          | Automatically configure Node.js memory limits.                                                                                                                                                                                                                                                                                              | `false`                  |
 | `advanced.dnsResolutionOrder`  | string           | The DNS resolution order.                                                                                                                                                                                                                                                                                                                   | `undefined`              |
-| `advanced.excludedEnvVars`     | array of strings | Environment variables to exclude from project context. Specifies environment variables that should be excluded from being loaded from project `.env` files. This prevents project-specific environment variables (like `DEBUG=true`) from interfering with the CLI behavior. Variables from `.matilda/.env` files are never excluded.       | `["DEBUG","DEBUG_MODE"]` |
+| `advanced.excludedEnvVars`     | array of strings | Environment variables to exclude from project `.env` files. Configurable exclusions do not apply to `.matilda/.env` files; bootstrap and policy variables remain protected across all project environment sources.                                                                                                                          | `["DEBUG","DEBUG_MODE"]` |
 | `advanced.bugCommand`          | object           | Configuration for the bug report command. Overrides the default URL for the `/bug` command. Properties: `urlTemplate` (string): A URL that can contain `{title}` and `{info}` placeholders. Example: `"bugCommand": { "urlTemplate": "https://bug.example.com/new?title={title}&info={info}" }`                                             | `undefined`              |
 | `plansDirectory`               | string           | Custom directory for approved Plan Mode files. Relative paths are resolved from the project root, and the resolved path must stay within the project root. If unset, plan files are stored in `~/.matilda/plans`. **Requires restart.** If the directory is inside the project root, add it to `.gitignore` to avoid committing plan files. | `undefined`              |
 
@@ -466,6 +495,14 @@ How much a Goal may do on its own after you create it, or resume one whose budge
 | `goal.tokenBudget` | number | Tokens a Goal may spend on its own. `-1` means unlimited.                        | `30000000` |
 | `goal.turnBudget`  | number | Goal turns that may finish before the Goal stops and asks. `-1` means unlimited. | `50`       |
 
+#### planGate
+
+Settings for the plan approval gate that reviews plans before autonomous execution (leaving plan mode under an autonomous approval mode). Optional and advanced.
+
+| Setting                    | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Default |
+| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `planGate.systemOneTriage` | boolean | Screen plans with the System One evaluation endpoint (`matilda-jev`, `POST /api/systemone` on the session's Matilda Core origin) before the full gate review. An approve verdict skips the full review; an approve-with-comments verdict runs the review as advisory notes and approves; a reject verdict — or any evaluation failure — falls back to the full reviewer agent. Auth reuses the session credential: a signed-in Matilda account works as-is, while a raw `MATILDA_API_KEY` (`mc_live_…`) requires the `api:systemone` scope. Set `false` for the single-agent gate. | `true`  |
+
 #### mcpServers
 
 Configures connections to one or more Model-Context Protocol (MCP) servers for discovering and using custom tools. Matilda Code attempts to connect to each configured MCP server to discover available tools. If multiple MCP servers expose a tool with the same name, the tool names will be prefixed with the server alias you defined in the configuration (e.g., `serverAlias__actualToolName`) to avoid conflicts. Note that the system might strip certain schema properties from MCP tool definitions for compatibility. At least one of `command`, `url`, or `httpUrl` must be provided. If multiple are specified, the order of precedence is `httpUrl`, then `url`, then `command`.
@@ -583,7 +620,9 @@ For authentication-related variables (like `OPENAI_*`) and the recommended `.mat
 
 > [!tip]
 >
-> **Environment Variable Exclusion:** Some environment variables (like `DEBUG` and `DEBUG_MODE`) are automatically excluded from project `.env` files by default to prevent interference with the CLI behavior. Variables from `.matilda/.env` files are never excluded. You can customize this behavior using the `advanced.excludedEnvVars`setting in your `settings.json` file.
+> **Environment Variable Exclusion:** Some environment variables (like `DEBUG` and `DEBUG_MODE`) are automatically excluded from project `.env` files by default to prevent interference with the CLI behavior. The configurable exclusions do not apply to `.matilda/.env` files. Bootstrap and policy variables remain protected in all project environment sources. You can customize this behavior using the `advanced.excludedEnvVars`setting in your `settings.json` file.
+
+Project `.env`, project `.matilda/.env` and workspace `settings.env` cannot configure sandbox startup, IDE helper connections, simple mode, interpreter startup, global state paths or workspace consent. Configure these inputs in the launch environment or user settings instead. User-level initial environment values are preserved; hot reload leaves bootstrap values fixed. Ordinary project provider and gateway variables continue to load in trusted workspaces.
 
 ### Environment Variables Table
 
@@ -601,7 +640,7 @@ For authentication-related variables (like `OPENAI_*`) and the recommended `.mat
 | `MATILDA_SANDBOX`                                     | Alternative to the `sandbox` setting in `settings.json`.                                                                                                                                                                                                                          | Accepts `true`, `false`, `docker`, `podman`, or a custom command string.                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `MATILDA_SANDBOX_IMAGE`                               | Overrides sandbox image selection for Docker/Podman.                                                                                                                                                                                                                              | Takes precedence over `tools.sandboxImage`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `SEATBELT_PROFILE`                                    | (macOS specific) Switches the Seatbelt (`sandbox-exec`) profile on macOS.                                                                                                                                                                                                         | `permissive-open`: (Default) Restricts writes to the project folder (and a few other folders, see `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) but allows other operations. `strict`: Uses a strict profile that declines operations by default. `<profile_name>`: Uses a custom profile. To define a custom profile, create a file named `sandbox-macos-<profile_name>.sb` in your project's `.matilda/` directory (e.g., `my-project/.matilda/sandbox-macos-custom.sb`). |
-| `DEBUG` or `DEBUG_MODE`                               | (often used by underlying libraries or the CLI itself) Set to `true` or `1` to enable verbose debug logging, which can be helpful for troubleshooting.                                                                                                                            | **Note:** These variables are automatically excluded from project `.env` files by default to prevent interference with the CLI behavior. Use `.matilda/.env` files if you need to set these for Matilda Code specifically.                                                                                                                                                                                                                                                               |
+| `DEBUG` or `DEBUG_MODE`                               | (often used by underlying libraries or the CLI itself) Set to `true` or `1` to enable verbose debug logging, which can be helpful for troubleshooting.                                                                                                                            | **Note:** These variables are excluded from project environment sources. Set them in the launch environment or user-level `.matilda/.env` to configure Matilda Code.                                                                                                                                                                                                                                                                                                                     |
 | `NO_COLOR`                                            | Set to any value to disable all color output in the CLI.                                                                                                                                                                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `FORCE_HYPERLINK`                                     | Override the OSC 8 clickable-link detection in the markdown renderer. Set to `1` (or any non-zero value, or empty string) to force-enable, `0` to force-disable. Honors `NO_COLOR` / `MATILDA_DISABLE_HYPERLINKS` opt-outs above it.                                              | Use this to opt into OSC 8 inside `tmux` / GNU `screen` (auto-detection refuses by default because the host terminal's capabilities are hidden behind the multiplexer). Requires `set -g allow-passthrough on` on tmux 3.3+. Also enables Hyper, which isn't auto-detected.                                                                                                                                                                                                              |
 | `MATILDA_DISABLE_HYPERLINKS`                          | Set to `1` to hard-disable OSC 8 clickable hyperlinks in the markdown renderer even on terminals that auto-detect as capable.                                                                                                                                                     | Useful when a terminal advertises support but breaks on long URLs, or when piping output through an intermediary that mangles escape sequences. The renderer falls back to plain `label (url)` rendering.                                                                                                                                                                                                                                                                                |
@@ -652,7 +691,7 @@ For sandbox image selection, precedence is:
 | `--telemetry-otlp-endpoint`  |       | Sets the OTLP endpoint for telemetry.                                                                                                                                                                                                           |                                                | See [telemetry](../../developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `--telemetry-otlp-protocol`  |       | Sets the OTLP protocol for telemetry (`grpc` or `http`).                                                                                                                                                                                        |                                                | Defaults to `grpc`. See [telemetry](../../developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `--telemetry-log-prompts`    |       | Enables logging of prompts for telemetry.                                                                                                                                                                                                       |                                                | See [telemetry](../../developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `--acp`                      |       | Enables ACP mode (Agent Client Protocol). Useful for IDE/editor integrations like [Zed](../integration-zed).                                                                                                                                    |                                                | Stable. Replaces the deprecated `--experimental-acp` flag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `--acp`                      |       | Enables ACP mode (Agent Client Protocol), which the VS Code companion and Matilda Desktop use.                                                                                                                                                  |                                                | Stable. Replaces the deprecated `--experimental-acp` flag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `--experimental-lsp`         |       | Enables experimental [LSP (Language Server Protocol)](../features/lsp) feature for code intelligence (go-to-definition, find references, diagnostics, etc.).                                                                                    |                                                | Experimental. Requires language servers to be installed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `--extensions`               | `-e`  | Specifies a list of extensions to use for the session.                                                                                                                                                                                          | Extension names                                | If not provided, all available extensions are used. Use the special term `matilda -e none` to disable all extensions. Example: `matilda -e my-extension -e my-other-extension`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `--list-extensions`          | `-l`  | Lists all available extensions and exits.                                                                                                                                                                                                       |                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |