> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usegandalf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trust contract: safety boundaries Gandalf promises

> Gandalf's trust contract: read-only discovery, no MCP or hook execution, no network by default, path-confined writes, symlink refusal, and explicit apply flags.

The trust contract is the safety boundary Gandalf enforces across scan, snapshot, diff, restore, and bundle flows. Every claim below is a runtime rule, not a suggestion.

## What Gandalf does by default

* Reads local user-global agent configuration only.
* Does not execute MCP server commands, hooks, scripts, plugins, or agent tools discovered during a scan.
* Does not use the network unless `GANDALF_UPDATE_CHECK=1` is set.
* Writes only to `~/.gandalf` (or `$GANDALF_STORE`) for saves.
* Changes supported user-global agent setup only through a reviewed, provider-backed action or an explicit `restore --apply --experimental`.
* Omits raw secrets from evidence and does not manage project `.env` values.
* Does not follow symlinks on write targets.
* Requires explicit `--apply` and `--experimental` (or `GANDALF_EXPERIMENTAL=1`) before restoring content.
* Creates rollback paths for restore operations where the evidence kind supports it.
* Reports missing local tools and env keys without installing packages or restoring secret values.

## Path confinement

All restore and bundle writes are confined to the declared home and project roots. Confinement is checked in plan parsing, apply, rollback, and bundle import. Callers must supply roots, or the operation fails closed.

The path that is actually written must be the same path that was validated. Symlink write targets are refused rather than resolved.

## Review Changes before mutation

Every mutating flow shows Review Changes first:

* Restore-backed applies compare a baseline snapshot to current evidence and list writable items, unsupported items with reasons, risk metadata, and rollback instructions.
* Provider-backed setup actions preview the target, expected effect, and execution mechanism before running.
* Marketplace-originated Review Actions stay non-mutating unless a concrete provider can preview and execute the effect.

Review is not apply authority. Mutating flows refresh or revalidate the underlying plan at apply time so the action still matches what you reviewed.

## Unsupported items stay observe-only

Evidence kinds without dedicated apply handlers are not force-fitted into generic file replacement. They surface in inventory and diffs but are marked unsupported for mutation with a concrete reason.

## Experimental gating

Destructive operations require an explicit opt-in:

* `restore --apply` requires `--experimental` or `GANDALF_EXPERIMENTAL=1`.
* `bundle import --apply-content` requires `--experimental`.
* `bundle import` with sensitive prefixes should be previewed with `--dry-run` or `--quarantine` first.

## Update checks

Update notices are off by default. Set `GANDALF_UPDATE_CHECK=1` to enable them. See [Environment variables](/reference/environment-variables).