# Configuration Reference

The exported Schemastery `Config` validates profile configuration and fills defaults. The Host registers that schema under the `coding-tools` settings namespace, with the profile row as its base layer and persistent user settings above it. The browser half contributes an explicit **Coding tools** card to **Settings → Plugins → Plugin configuration** for four tool-availability switches, two approval-policy switches, and one warned native-Windows compatibility switch; advanced limits and language-server plans remain profile configuration. Each committed settings field applies live through a serialized generation replacement: tool registrations, approval policy, cursors, observations, and process-backed resources are replaced as one lifecycle unit. A browser Save spanning several nested fields is not one atomic transaction: it commits revision-fenced fields in a safe order (approval tightening first, protected-feature disablement before opt-outs, and reduced isolation/approval opt-outs last). A later write failure can leave that safely ordered prefix persisted, and the user must review the refreshed state before retrying. In-flight reads and queries are cancelled, edits that may already have committed are drained to an explicit result, and existing cursors and `code_read` version tokens are invalidated. If a committed configuration cannot activate, the runtime stays fail-closed with these tools guarded off until a later valid commit succeeds; Settings watcher failures are contained and logged by the Host. Unknown or invalid values are rejected; `versionedEdit.enabled` cannot be true when `codeRead.enabled` is false. Patch layers replace matching Cordis row configuration rather than deep-merging it, so include the full intended base configuration in the final matching row.

## Global

| Key | Default | Purpose |
|---|---:|---|
| `inlineMaxBytes` | 8192 | Model-facing native-render budget. |
| `cursorTtlMs` | 300000 | Server-stored cursor idle lifetime. |
| `maxCursors` | 256 | Global per-subsystem cursor entry cap. |

## `approvals`

| Key | Default | Purpose |
|---|---:|---|
| `editRanges` | `true` | Require generic one-shot approval before ordinary exact-version writes. Disabling it does not bypass writable sandbox policy or approval for explicit sandbox escalation. |
| `processStart` | `true` | Require generic one-shot approval before ast-grep and language-server process startup. Disabling it does not bypass executable resolution or forced read-only process policy. |

These are explicit operator trust controls. Keep both enabled for untrusted repositories or shared deployments.

## `processPolicy`

| Key | Default | Purpose |
|---|---:|---|
| `allowWindowsPartialReadOnlyProcessConfinement` | `false` | Native Windows only: allow `ast_grep` and configured LSP starts to accept DSH-reported `partial` restricted-token enforcement after policy is forced to `read-only`. |

This option is intentionally separate from approval and defaults off. Full confinement is always accepted under forced read-only policy; unknown enforcement values always fail. Partial enforcement is accepted only when this exact boolean is true and the native Host platform is Windows. It has no effect on other platforms.

Windows partial confinement has material limits: Everyone-writable ACLs and NTFS hard links can weaken write isolation, FAT-class targets outside granted roots remain writable, and reads, network access, and process visibility are not isolated by this backend. Use the opt-in only with trusted repositories and operator-configured executables. Changing it replaces the complete live tool generation and terminates existing process-backed resources.

## `codeRead`

Exact versions require reading the complete file. `maxFileBytes` is the complete-file ceiling used by `code_read` and `edit_ranges`; `maxBytes` independently bounds returned code content; and `snapshotMaxBytes` bounds retained conflict context across observations. `maxBytes <= maxFileBytes <= snapshotMaxBytes` is required. Canonical structured/read rendering is also bounded by `inlineMaxBytes`, and only complete returned lines become observed edit ranges.

## `versionedEdit`

`requireObservedRanges` should remain true. Every edit follows the public `fs/write-intent` observation-policy waterfall and supplies an explicitly writable resolved policy to `ctx.fs.writeText`. Read-only sessions fail before mutation and advertise the standard one-call `sandbox_permissions` + `justification` retry only when `ctx.fs.sandboxMode` confirms enforcement; a bare filesystem cannot escalate. An already-writable session requires generic one-shot mutation approval when `approvals.editRanges` is enabled.

## `ast`

An empty `executable` resolves the exact optional native binary owned by pinned `@ast-grep/cli`. A non-empty override must be an absolute operator-configured path. The tool never reads project configuration to select a binary, rewrite, or executable arguments.

The secure initial mode accepts exactly one non-symlink regular file and requires a language. It reads a stable byte-bounded snapshot through `ctx.fs`, then sends that snapshot to ast-grep over stdin. Directory and multi-file scans fail closed until DSH exposes an atomic read-confinement/open-handle seam.

## `lsp`

`servers` is a dictionary keyed by a profile name. Each entry requires:

- `command`: absolute executable path
- `args`: fixed operator-configured arguments
- `extensions`: dot-prefixed selectors; an empty list is a wildcard
- `languageId`: LSP document language ID
- `env`: explicit environment overrides
- optional `initializationOptions`

If multiple profiles match one extension, calls must name `profile` explicitly. Workspace symbol calls without a file also require it.

Protocol/lifecycle caps include initialization and request timeouts, idle timeout, frame bytes, pending requests, event queue, retained projects, normalized result items, open-document count, complete bytes per synchronized document, diagnostic items, and aggregate diagnostic bytes. `maxDocumentBytes` is independent from `codeRead.maxBytes`; every file-backed action either synchronizes the complete stable file under that LSP limit or fails without querying a source prefix. Old documents are closed deterministically before eviction. Structured and rendered pages share the `inlineMaxBytes` ceiling.

## `debug`

`debug.enabled` must remain false. Enabling it fails startup because DAP is intentionally unavailable until the later security phase is implemented and tested.