Reference

Note Nothing here is needed to use Fettler. The quick start gets it working. This page is the argument behind it, for anybody who has to satisfy themselves the boundary holds.

The three levels

Fettler does three kinds of work, called levels: tools, guardrails and screenings. The tools level is always on and needs no file. Each of the other two is on when the configuration file has a section of that name. Tools, Guardrails and Screenings each have a page.

Why three. The tools are what no other tool offers: the batch, the hash, the caps and the document readers. Guardrails help on some projects and get in the way on others, so a project turns them on. Screenings are for the few projects that hold regulated data.

The configuration file's three sections

.fettler.json holds any of tools, guardrails and screenings, and nothing else at the top. An unknown key at the top is refused, and the message names the three. Here is a file with all three:

{
  "tools": {
    "generated": ["bin", "obj", ".git", "artifacts", "node_modules"],
    "scratch": "path/to/a/folder",
    "scratch-root": "path",
    "client-root": "path"
  },
  "guardrails": {
    "trees": {
      "work": { "path": ".", "can": ["list", "read", "create", "update", "rename", "delete", "execute"],
                "scopes": { "secrets": { "can": [] }, "docs": { "can": ["list", "read"] },
                            "records": { "can": ["list", "read"] }, "public": { "can": ["list", "read"] } } },
      "shoddy": { "path": "../shoddy" }
    },
    "tasks": { "build": { "run": "pwsh -NoProfile -File build.ps1", "cwd": "." } },
    "replacements": { "feature-branch": "halifax" }
  },
  "screenings": {
    "models": "../screening-models",
    "screen": { "work": ["identifiers"], "work/records": true, "work/public": false }
  }
}

• tools is optional. generated replaces the folder names that find and search skip. scratch names a folder to open as the scratch tree by hand. scratch-root names the folder that holds every project's scratch folders. client-root names the folder that holds the client's per-project folders (by default ~/.claude/projects). Nothing else goes here. The caps, the hashes and the readers cannot be configured.
• guardrails holds trees, tasks and replacements, with the meanings this page gives them. The tree holding the file gets everything but execute. Every other tree gets list read. A guardrails section with no trees is refused.
• screenings holds models, the directory of screening models, and screen. Each screen key is a tree name, or a tree name, a slash and a scope path. Each value is true, false or a list of category words. The tree must be declared, or be work when guardrails are off. A scope named in a key must be declared under its tree. In the example, work/records is screened for every category, and work/public takes the screen off inside a screened tree.
• The overlay, .fettler.local.json, may hold any section. It merges over .fettler.json section by section. Inside a section, an entry named in both files is the overlay's entirely.
• Three tree names are taken. A declared tree may not be called scratch, tool-results or memory, because fettle opens those folders itself.
• The old flat shape is refused. trees, tasks, replacements or models at the top, or a screen inside a tree, is refused. The message shows the file's own entries moved under the new sections.

The verbs

The CLI verb and the MCP tool name are the same word, and both front ends reach the operations through one dispatcher. That makes "this capability is for a model but not a script" impossible to write, rather than merely forbidden.

Every verb except tasks and run belongs to the tools level and works with no configuration file. tasks and run belong to guardrails. fettle help opens with a here: line naming the levels that are on where it was run. It then lists the verbs grouped by level, tools first, and ends with the exit codes.

$ fettle find "src/**/*.cs" --sort mtime --limit 3
src/Fettler/Glob.cs           4812  2026-08-14T09:22:07Z
src/Fettler/PathRoot.cs       6104  2026-08-13T17:40:11Z
src/Fettler/Edits.cs         11233  2026-08-12T08:05:52Z
3 files (77 excluded: bin, obj, .git - pass --include-generated)

$ fettle roots
levels
  tools       on, always
  guardrails  on, from C:\github\app\.fettler.json
  screenings  off

trees
work        C:\github\app  (default)
            can: list read create update rename delete execute
            branch: main (local)
            secrets  can: nothing

screens
work        identifiers

found by fettle
scratch     C:\Users\you\AppData\Local\Temp\claude\c--github-app\1f0c...\scratchpad
            can: list read create update rename delete
            found: this session's folder, named by the environment variable NAME
tool-results C:\Users\you\.claude\projects\c--github-app\1f0c...\tool-results
            can: list read
            found: in the client's folder for this project, in this session's folder; ...
memory      C:\Users\you\.claude\projects\c--github-app\memory
            can: list read create update rename delete
            found: in the client's folder for this project

declared by C:\github\app\.fettler.json

• A level that is off prints off. At the tools level, the trees part shows only work, the launch folder.
• The screens heading appears only when something is screened or a models directory is named.
• The --json answer gains a levels object, such as {"tools":{"on":true,"from":[]},"guardrails":{"on":false,"from":[]},...}, and a found field on each tree fettle opened itself.
• The machine file is named on the level line when it supplied something.

The branch line is local. It is printed for declared trees only, never for a tree fettle found itself. For a tree whose top, or a folder above it, holds .git, roots prints branch: NAME (local), or detached at HASH (local) when HEAD holds a commit. When the .git is above the tree, the next line names that folder as the repository. The line says what this machine has checked out. It does not say what a remote holds, and only a fetch answers that, so do not take it as proof that a branch is current. Only .git/HEAD is read, and the one gitdir: pointer a worktree or a submodule uses. No ref, index, object or configuration file is opened. A .git that cannot be read answers as no .git. The --json answer carries branch, detached and repository, and over MCP the branch is read at every call, so a switch made in a terminal shows on the next one.

A path inside a script is a tree path. In an edit script, replaceFile, withFile and textFile name a file whose text the script uses. That file is read through the boundary with read, relative to the default tree or written as tree:path, on both front ends. A file outside every tree is refused as outside, and the batch does not run. The refusal names the edit and the field. A script named by --script-path follows the same rule. --script FILE on the command line is a caller's own file, read directly, as --text-file is. A large script goes in a file in a tree, so the call that names it is one short line.

setup, by level

The level is the first word, then the client. The clients are claude-code, claude-desktop, vscode-copilot and github-copilot. --local writes in this project and --global writes for every project.

--dry-run, --force, --command PATH and --all keep their meanings. fettle setup CLIENT, the old spelling, is refused with the new spellings shown.

Worked twins

# scripts/list-types.ps1
$out = fettle search "^public sealed" --glob "src/**/*.cs" --json
if ($LASTEXITCODE -ne 0) { throw "search failed: $out" }
$out

# scripts/list-types.sh
out=$(fettle search '^public sealed' --glob 'src/**/*.cs' --json) || {
  printf '%s\n' "$out" >&2; exit 1;
}
printf '%s\n' "$out"

In machine-readable mode the complete result, failures included, is on stdout, the normal output stream. That matters on Windows. PowerShell 5.1 turns a native program's redirected error output into NativeCommandError records, and sets $? false even on exit code 0. Any design that needs 2>&1 to retrieve an answer is broken on the primary development platform.

What it can read

On a machine where the assistant's own reader has been denied, Fettler is the only reader. A type it cannot open is a file nobody can open.

• read stops at 2000 lines unless --to says otherwise, and says how many are left. find stops at a thousand, search at two hundred.
• read also stops at 40,000 characters, which --to does not lift. Those two caps are in different units on purpose. A line cap bounds how much of a file you asked for. A character cap bounds how much of it survives the trip, and lines vary in length by two orders of magnitude. A 593-line page, well under the line cap, was still large enough for a caller to reject the answer whole. A rejected answer costs a turn and returns nothing, which is worse than a short one. So the size is measured here, and the answer comes back short and says what is left. The budget is spent across the whole call rather than per path, and at least one line is always served. A minified file is a single enormous line, and an empty answer is a dead end rather than a smaller answer.
• --numbered puts the line numbers in the text, in the form the terminal prints: N | text, with N right-aligned in five columns. The prefix counts toward the 40,000-character cap, so a numbered read of a large file stops earlier. The hash is still the file's, and an edit may present it as expect. The numbered text is a rendering, not the file's content, so leave the prefix out of an edit. A rendered document is numbered by rendered line.
• --tail N is the end of the file, counted backwards. Reaching the end of a log or a build transcript needs neither its length nor any arithmetic. It cannot be combined with --from/--to. The end of a file and a named range are two different questions, and answering one of them by precedence would be a confident wrong answer rather than an error.
• A notebook's non-text output is measured rather than pasted. One output cell routinely holds a megabyte of encoded image data that nobody can see.
• A document is searched, not only read. A PDF in the path of a search is rendered and matched along with everything else, and a hit inside one cites its page. Searching inside one says what that costs.
• Word and Excel are read here rather than exported first. Telling a person to save as PDF or CSV describes a chore rather than a workflow. It makes somebody convert a file before the assistant may read it, which is the hindrance and not the remedy. The obvious objection, that parsers for those formats are a maintenance liability, is answered by what the formats are: a zip full of XML, opened with the archive support already here, and so with no new dependency at all.
• A workbook comes back as rows, not as cells. A cell to a line would make every hit a single value with nothing around it. What a person wants from a search of a workbook is the record the value sits in. Formulas are rendered as well as values, because the two answer different questions and only one of them is in the file twice. A search for VLOOKUP is a search for how a sheet works and would find nothing in the cached results. A search for a customer name would find nothing in the formulas. And dates are rendered as dates. Excel stores the cell you see as 2026-03-15 as the number 46096, so rendering the number would leave a workbook full of dates nobody can search for. That is the same readable-but-unfindable fault that had search skipping PDFs.
• A Word document is located by its headings. Word does not store where the pages break. That is worked out at layout time by whatever is displaying the file, and it moves with the font and the paper. A heading is in the file, is stable, and is what a person would say if you asked them where in the document something was.
• The macro-bearing twins are in. The older formats are not. .xlsm and .docm are the same formats carrying macros, read the same way, and nothing here executes anything. .xlsb and .doc are not here. Both are binary formats under a familiar extension, and a reader that claimed them would fail on every file.
• Neither reader trusts the file. A document arrives from wherever documents arrive from, and these run inside a server whose whole job is to be a boundary. So there is no DTD and no resolver, which closes the external entity that reads a file off the machine and the internal one that expands to gigabytes. No part is read past a cap however comfortable a number its own header claims. A rendering stops at 200,000 lines and says that the rest was left unread.
• A rendering does not go back. write, edit and replace refuse a PDF, a workbook and a Word document outright. What comes back for one is text pulled out of it, with the sheets, the formulas, the tables and every piece of structure left behind. Writing that text back would not edit the file. It would replace it with a fraction of itself, still under the name that says it is a document. An image, an archive and a lone .gz are refused for the plainer reason that they are not text at all. The verbs move, copy and delete do not inspect content and are the way to shift one of these. The extract verb writes an archive member's own bytes and is deliberately not caught.
• Still no plugins. A declared command needs an explicit execute grant, so a loader running unnamed code in process at full trust would be a hole straight through the boundary. A reader is a class in this tree with tests beside it, never a file found at startup. For a format Fettler does not ship, a declared converter task is the right form, and it already exists.

Searching inside one

Readable and unfindable is the trap this closes. A tool can render a PDF for read and still let search try to decode it as text, fail, and move on without counting it. That leaves a tree full of documents answering every search with a confident nothing. It is the failure this whole tool exists to prevent, and it would be sitting inside the tool.

• The rendering happens on the way into the search, and a hit cites the page rather than a line number into a rendering nobody can see. A line number that cannot be checked against the document is not a citation, and it moves the moment the renderer changes.
• Renderings are cached on the file's length and modification time, so a second search over the same tree does not pay for the same parse again. A file that has changed is rendered again.
• A document over 32 MB is not opened, and neither is one that will not render. Neither fails the sweep. Both are counted.
• What was not looked inside is said out loud. A search that never opened a file has not established that there is nothing in it. So the count travels with the answer rather than being left to be inferred from a total that looks complete.
• --no-documents leaves them shut where the cost is not worth paying. The count is still reported.

Unpacking one

extract ARCHIVE --into DIR writes. Everything above only reads. An archive is a list of paths somebody else chose. That is exactly why the tool that already refuses a path outside a tree is the right one to unpack with.

$ fettle read fettle-1.0.0-win-x64.zip
79605839  2026-08-16 16:08  - fettle.exe
    2545  2026-08-16 14:09  - NOTICE
    1133  2026-07-30 04:52  - LICENSE
3 members, 79609517 bytes uncompressed

$ fettle extract fettle-1.0.0-win-x64.zip --into tools
extracted 3 members (79609517 bytes) from work:fettle-1.0.0-win-x64.zip into work:tools

• Refused whole, or not at all. Every member is resolved through the boundary before a byte is written. An archive that would escape, or that lands anywhere it may not, leaves nothing behind. A half-unpacked archive is the state nobody can see the shape of, which is the same reason edit is all-or-nothing.
• Zip slip is refused by construction, not by a bolted-on check. Zip slip is the classic attack where an archive member is named something like ../../etc/passwd so it lands outside the unpack folder. Here that member resolves outside every tree and comes back exit 4, exactly like a path somebody typed.
• A member that escapes only the destination is refused too. out/../elsewhere.txt normalises to somewhere the boundary is happy with. The tree check passes, and the file still lands nowhere near where you said. Nothing is wrong with the path. What is wrong is that it is not where you put it.
• A link member is refused rather than skipped. Creating links is out of scope anyway. And a symbolic link inside a tar is the one member that can point out of the tree after every path check has passed. Skipping it silently would produce an extraction that looks complete and is not.
• The executable bit is carried. R6.9 is this project's own requirement clause about that bit, and its release depends on a fettle arriving out of a tar still able to run.
• Bounded, not endured. There is a cap on member count and on total unpacked bytes, refused with a reason. That is the same posture as the bound on a runaway pattern. A compressed archive can name far more content than it occupies, and finding that out by running out of disk is finding out too late.
• Nothing is overwritten without --overwrite. An existing file is a refusal before anything is written, not a surprise halfway through.

The trees fettle finds

At every level, fettle opens some trees with no declaration. They are folders the model already reaches through the client, or through another server. Opening them lets Fettler's own tools work there.

• <project> is the launch path with separators and the drive colon replaced by hyphens. c:\github\app becomes c--github-app.
• This session's folder is chosen in two steps. First, a value in fettle's environment that is exactly a session folder's name. Otherwise, the newest session folder. roots says which route it used.
• Older sessions are not trees, and neither are the session transcripts beside these folders. A path into them is refused in the same words as any path outside.
• A folder that does not exist yet is not a tree, and it is not a finding. It appears on the next call, once the client makes it.
• The tool settings can move them. Under tools, scratch names a folder to open as scratch by hand, scratch-root names the folder that holds every project's scratch folders, and client-root names the folder that holds the client's per-project folders (by default ~/.claude/projects).
• Paths in answers are written tree:path whenever more than one tree is open, which is now almost always.

A companion is another MCP server whose registration passes --root PATH. sparky is one. fettle opens that folder as a tree named for the server, read and write, because the model already reaches it through the companion. So fettle can write a file there, and the companion can load it in the same turn. A declared tree with the same name on the same folder stands. The same name on a different folder is refused. With guardrails on, a companion's root inside a declared tree is finding 2.19.

What it touches besides content

Arguments it will not guess at

• A flag no verb knows is refused, never ignored, one dash or two. A flag that takes a value swallows the argument after it. So a misspelt --gob "*.cs" would eat the pattern, and the search would then run against the whole tree with complete confidence. A single dash is the same trap with one fewer character. Take search PATTERN -i, the spelling every grep in the world uses. It would otherwise be read as a second pattern and answer the union of two questions. There is one short flag, -e. A pattern or path that starts with a hyphen goes after a bare --, or through --pattern-file or --pattern-stdin.
• A known flag with no value is refused too. The name was right. The value was missing. Write --NAME= for a deliberately empty one.
• A pattern may arrive as file content instead of an argument. --pattern-file and --pattern-stdin take one pattern per line. So do --replace-file, --with-file and --text-file. Text with quotes and newlines never has to be escaped onto a command line.
• A leading byte-order mark on a stream is taken off. A byte-order mark is an invisible marker character some tools put at the start of text. Windows PowerShell emits one whether asked to or not. Keeping it made a pattern match nothing, and spliced an invisible character into the middle of a source file. This applies to the command line's streams and the MCP front end's alike. A mark further along is left alone.
• Text an edit brings in is rewritten into the file's own line endings. Text already there is untouched. A PowerShell here-string is CRLF whatever the file is. Splicing that in verbatim leaves a file disagreeing with itself by one line, which nothing notices until a version control system does.
• A file that disagrees with itself says so. read marks it (MIXED) beside the dominant ending. Nothing is silently regularised.

The rules a caller has to know

How a declared path is written

Relative, forward-slashed, no drive letter. There is no formal standard for this. There is a convention, and it is git's. It is what .gitignore, Docker, npm and VS Code's own task files use, and it is the only spelling that means one thing on all three platforms.

Refused rather than converted, because converting would make a file legitimately called a\b unreachable on the platforms where that is a legal name. The same rule applies to a scope key, to a task's cwd, to a screen key, and to the folders named under tools (scratch, scratch-root, client-root) and under screenings (models). Each of those paths resolves against the folder of the file that names it.

The boundary: what it can say

Nothing outside an open tree exists. A tree is a folder fettle has opened, with a name and a list of what may be done in it. At the tools level the open trees are the launch folder, as work, and the trees fettle finds. With guardrails on, they are the declared trees and the trees fettle finds. Outside them, nothing is writable, readable, listable or knowable. A path outside every tree is refused with exit 4, and refused in the same words whether or not something is there, so the refusal itself cannot be used to probe a disk. There is no current directory to change, no path that climbs out, and no shell to reach past it with.

The rest of this section is the guardrails level. Inside a declared tree, everything that may be done is stated, never assumed. The first question to settle is not how this works. It is whether it can express the rule you already have in your head. Most people arrive with one of these.

Every word in that table is one of seven, and the next section defines them all. They combine freely, per tree and per folder. That is what makes "may reorganise, may not destroy" a rule you can state, rather than a thing you hope for.

Saying it at a depth

A tree is a path and a set of permissions. A scope states permissions somewhere inside one. Trees and scopes are declared in the guardrails section. Here is a real one, shown to read rather than to copy. Guardrails shows how to write your own:

{
  "guardrails": {
    "trees": {
      "work": {
        "path": ".",
        "can": ["list", "read", "create", "update", "rename", "delete"]
      },
      "requirements": {
        "path": "../shoddy-requirements",
        "can": ["list", "read"],
        "scopes": {
          "backlog":           { "can": ["list", "read", "create", "update", "rename"] },
          "backlog/cancelled": { "can": [] }
        }
      }
    }
  }
}

That reads: work may be changed but nothing in it may be run. The requirements tree is readable throughout. Its backlog folder may be added to, changed, and reorganised, but never destroyed. And backlog/cancelled is not there at all, as far as anything can tell.

Two rules decide what a given file gets, and they are the two to know before you write one of these:

• The most specific scope containing the path decides. Not the tree, and not the shallowest scope that matches. cancelled sits inside backlog, so cancelled wins there.
• A scope replaces what its tree grants. It does not add to it. That is what lets a scope take a permission away, which is how a folder inside a readable tree ends up invisible. It is also the trap to state out loud: a scope naming create and nothing else grants create and nothing else, not even read.

Paths resolve against the file, never against the caller. Read against a current directory, a relative path names a different tree from every folder you run it in. Read against the file's own directory, it names one tree from everywhere. That is what lets the file be checked in.

A tree, not a repository. A folder with no version control in it is the ordinary case, not an exception. Nothing in the configuration, the default names, or this page assumes a checkout, a remote, or a .git. A folder that is also a checkout has its branch named by roots.

A malformed configuration is refused, never fallen back from. A silent fallback usually widens the boundary.

The seven permissions

Move is two permissions, not one. Moving into a subfolder needs rename on the source and create at the destination. Moving out of a scope needs delete as well, because a file that leaves is gone from here either way. That is what makes "may reorganise, may not destroy" possible to say at all.

A move that replaces something needs delete at the destination too, whatever the verb was called. Replacing a file destroys it.

Verbs that do not name what they touch

A recursive delete and a recursive copy reach paths nobody wrote down. That is how a protected scope gets taken anyway. So both are refused when any scope inside the target does not grant what the operation needs. The refusal names no path, because saying where would tell a caller where a hidden scope is. That costs one bit of information. It buys a destructive operation refused out loud, instead of half-done in silence.

The defaults, which are the safe ones

The default is decided by where the tree is, not by how its path was spelled. "." and an absolute path to the same folder mean the same thing.

A malformed file is a refusal, never a fallback to the tools level. Falling back from a broken boundary is how a boundary silently widens.

Why the launch folder, and not a folder above it. Before 2.1.0, a folder with no file was refused. That changed on purpose, and it is the one widening in 2.1.0. The launch folder is the narrowest honest tree. It is the folder the client was started in, which is the folder the work is in. The old objection was that a current directory often sits above the tree somebody meant. The upward search answers it. The search for a .fettler.json runs first, so a file in a folder above is always found and honoured.

Where a permission may come from

This is the central rule, and it is the answer to --root. fettle reads up to three files, in this order, and a later file wins section by section.

The machine file is not ~/.fettler.json. The upward search would find a file of that name and take the whole home folder as the tree. roots and doctor name the machine file when it supplied something.

serve looks again on every call while it has no file. Writing a guardrails section into a new .fettler.json binds on the next call, with no restart. Once a file is found, that file is the one read again before every call. fettle never searches upward again from there, because a fresh search could find a broader file above.

--root stays because the MCP server has to be launched somehow, and because ad-hoc reading is useful. It can no longer hand anybody write access. To write to a declared tree, you put a file in it.

The single exception, and the only one: setup may write outside every tree, to a fixed, compiled-in list of client-configuration paths, and nowhere else. It is the same closed list doctor reads. Nothing else in the tool may write outside a tree that granted it.

Fettler never writes its own rules

The configuration file names the trees, what may be done in each, and the commands Fettler may run. Before this rule existed, Fettler could write that file and then act on what it had just written. Declaring a task and running it took two commands. Two things follow.

execute must not be a default, even on the tree the configuration sits in. That tree is writable by definition, and the configuration lives inside it. Write-by-default plus execute-by-default is arbitrary code execution. The tool could be walked into running anything. And it defeats every other permission at once, because a scope protected from delete means nothing to a task that can run del.

An explicit grant is not enough on its own, either. If the declaration can be written by the thing the grant applies to, the grant has no bound. Whoever holds execute also chooses what executes.

Therefore, compiled in and not configurable at any permission level:

That is nine files. The ninth is matched on its last two path segments, like the client's files below it in the table.

The second group is the same argument, arrived at later. Fettler's own declaration was protected from the start. Meanwhile .claude/settings.json, the file naming which tools a model may use at all, stayed an ordinary writable file. No boundary had to be breached to reach it. A project's assistant configuration lives in the project, so the file governing the assistant and a file the assistant may write were the same file. A model that can edit its own deny list has no deny list. Being asked to edit it is no safeguard. An instruction can arrive from a prompt, from a file just read, or from a misreading of either.

pick's files are the same argument once more. The .picker pair is the whole boundary of the assistant's SQL tool. pick itself has no write path at all and re-reads the pair before every call. A fettle that could write them would hand the assistant that boundary through the side door, and the very next pick call would obey the edit.

The client's files and the machine file are matched on the last two path segments, not on the file name alone. A rule refusing every settings.json would be unusable, and also wrong. .vscode/settings.json is a person's editor configuration and has no say in what an assistant may do. CLAUDE.md is deliberately not on the list either. It persuades rather than permits, and an assistant maintaining a project's instructions is ordinary work.

setup still writes the ones it needs, by construction and not by exemption. It uses plain file IO and resolves no path through the boundary, so a guard that lives on the path-resolving route every tool verb takes is not in its way.

The names cover all three sections alike, since the trees, the tasks and the screens are declared in the same file.

The names are matched at any depth, so a configuration in a subdirectory is protected too. They are matched by name, so .fettler.json.bak and .fettler.json.md are ordinary files. Reading them is fine and stays fine. A caller asking what the rules are is the opposite of the problem.

The refusal has its own outcome and its own wording, Fettler does not write those files, and its own exit code, 11. It is deliberately not a permission denial, because nothing is missing. No grant would have allowed it, and a caller sent looking for one is being sent somewhere there is nothing to find. setup guardrails and setup screenings may add a starter section where the file has none. Changing a section that exists is a person's job, with an ordinary editor.

Why an assistant cannot override any of this

Worth stating plainly, because it is the whole point.

• A model never supplies the boundary. The MCP server reads its boundary from files a person wrote: the machine file, the project's .fettler.json and its overlay. serve reads them again before every call, so a person's edit binds on the next call. The model cannot write any of them.
• No tool can name a tree it was not given. No tool schema carries a root or a config flag, and a test asserts that none ever will. The only related field is in, which selects among trees already open.
• --root cannot grant write at all, so even a careless launch cannot hand write access to anybody.
• And the model cannot edit the files that would grant it more. That was the real hole. Not the flag, but that the tool would happily rewrite the document governing it, and then act on the new version.

So the answer to why does an MCP server need a root is that it does not need --root. It needs a boundary, from a source the model cannot write. A file in the tree is that source.

Hidden is not secret

A scope with no list is absent from find and search, and absent from their counts and totals. A direct path into it is refused in the same words as a path outside every tree, including a path to a file that was never there. The difference between hidden and absent cannot be probed.

This is not encryption, and it does not pretend to be. Somebody at a terminal can open the folder. What it stops is an assistant finding cancelled requirements by searching, and reading them back as current.

Declared tasks

Tasks belong to the guardrails level. They are declared in tasks under guardrails, and with guardrails off there are none. run executes only what the configuration declares, and never composes a shell command. Guardrails shows how to declare one. What a declaration means is here.

The command grammar, in full

• Whitespace separates arguments. Runs of spaces and tabs are one separator.
• A double-quoted span is one argument, or part of one. The quotes are removed. "one two" is a single argument.
• Two double quotes inside a quoted span are one literal quote.
• A backslash is never an escape. It is an ordinary character, so a Windows path is written once rather than doubled.
• Nothing else is special. No single quotes, no variables, no globbing, no redirection, no &&. The string is split once, and the program is launched with the resulting list.
• An unclosed quote is refused, not guessed at.

$ fettle run build --release
refused: no such flag: --release. Run fettle help for the list
$ fettle run build release
refused: run takes only a task name; 'release' is extra. A task takes no arguments.
Declare a second task for a variant

cwd, the folder the task runs in, is optional. It defaults to the top of the default tree, and is checked for containment like any other path.

Values the file supplies

Declaring a second task answers test versus machines. It cannot answer the branch to cut or the note to commit under, which are strings invented fresh each time. A command line may name a value the configuration declares:

"guardrails": {
  "trees": { "work": { "path": ".", "can": ["list", "read", "create", "update", "rename", "delete", "execute"] } },
  "replacements": {
    "feature-branch": "hebdenbridge"
  },
  "tasks": {
    "feature": { "run": "pwsh -File scripts/shoddy-branch.ps1 feature {feature-branch}" }
  }
}

• Filling happens after the split, into a word. A value is one argument whatever is in it. A space does not make two arguments, and a quote does not change the parse. Filling the line and splitting afterwards would hand the grammar a value, which is the entire failure class the split-once rule exists to remove.
• A placeholder may be part of a word. --message={note} and v{release-tag} are each one argument.
• Only an identifier between braces is a name: a letter, then letters, digits, dots, underscores or hyphens. Everything else is ordinary text, so { $_.Name }, {a:.b} and {0} go on meaning what they meant. Write {{ for a literal brace where a name would otherwise be read.
• One pass. A value carrying braces is inserted literally and never looked up again, so a replacement cannot build another.
• An undeclared name is refused and the configuration does not load. It is never passed through. Passed through, new {feature-branch} does not fail. It creates a branch called {feature-branch}.
• The overlay is where a value belongs. .fettler.local.json is kept out of source control. Its guardrails section merges over the checked-in one, and its replacements replace the checked-in ones name by name. The project declares the task while today's branch name stays out of source control.
• They are not for secrets. tasks shows every value, deliberately, so that what is listed is what runs. A token belongs in the environment of the process a task launches.

When it refuses

Every refusal belongs to one level. A refusal can happen only when its level is on, except for the configuration refusals, which happen while the file is read. Each refusal prints its whole answer on stdout, the normal output stream, so no redirection is needed to read a failure. The exit codes are below.

Real transcripts of the common ones follow.

A path outside every declared tree

$ fettle read ../secrets.txt
refused: the path is outside every declared tree. Run roots to see the trees
$ echo $LASTEXITCODE
4

Climbing out with .., an absolute path elsewhere, and a link leaving the tree all land here. So does a path into an older session's scratch folder, or into the session transcripts beside the client's folders. All of them answer the same whether or not the file exists.

Writing a file that says what the tool may do

$ fettle write .fettler.json --text "{}" --overwrite
refused: .fettler.json is a file that says what this tool and the assistant may do.
Fettler does not write those files. Change it with an editor. The files are:
.fettler.json, .fettler.local.json, .mcp.json, .picker.json, .picker.local.json,
.claude/settings.json, .claude/settings.local.json, .vscode/mcp.json,
fettler/fettler.json (C:\github\app\.fettler.json)
$ echo $LASTEXITCODE
11

This has its own outcome rather than a permission denial, because nothing is missing. No grant would have allowed it. Without the rule, the escape is two commands: write a task declaration, then run what you just wrote.

A write that would put a secret on disk

$ fettle write config.json --text-file staged.json --overwrite
refused: this write would add a credential to the file: line 14 (aws-access-key-id).
The secret is not quoted, because the refusal would then disclose it. Use a reference
such as ${ENV_VAR} instead, or pass --allow-credential on the command line if this is
not a credential.
$ echo $LASTEXITCODE
12

It judges what the write adds, not what the file contains. A configuration that already holds a key stays editable. That is the whole difference between a rule people keep and a rule people switch off. Only a secret absent from the previous content stops anything, so reformatting, reordering, and editing the lines around one all still work.

The refusal never repeats what it found. A line number and a detector name, and nothing else. A message naming the secret would write it into the log, the transcript, and whatever ships those onward, which is a worse outcome than the write it was refusing.

--allow-credential is offered by the command line and by nothing else. No MCP tool carries it, and a test asserts none ever will. Deciding that a random-looking string is not a secret is a judgement about your own file, and a person makes it. That is the same reasoning that keeps setup out of a model's hands.

A read that would disclose regulated data

$ fettle read ward-round.docx
refused: this response would disclose regulated data: 2 in identifiers. The matches are
not quoted, because the refusal would then disclose them. Read a narrower range, or
take the screen off this scope if the content is not regulated.
$ echo $LASTEXITCODE
13

This is the mirror of the credential refusal above. That one is a write going in. This one is a payload coming out. It happens only when the screenings level is on, in a tree or scope the screen names. Screenings is the whole of it.

Running a task in a tree that does not grant execute

$ fettle run hello
refused: 'hello' would run in a tree that does not allow execute. Add "execute" to
that tree's or scope's "can" under "guardrails" in .fettler.json. execute is never
a default.
$ echo $LASTEXITCODE
8

The tree holding the configuration is writable by definition. So write-by-default plus execute-by-default would be arbitrary code execution, and a scope protected from delete means nothing to a task that can run del.

A task nobody declared

$ fettle run deploy
refused: no task called 'deploy'; .fettler.json declares: hello
$ echo $LASTEXITCODE
3

With guardrails off there are no tasks, and every name gets this answer:

$ fettle run build
refused: no task is declared, because tasks belong to the guardrails level and it is off.
Write a .fettler.json with a "guardrails" section holding "trees" and "tasks"
$ echo $LASTEXITCODE
3

A flag with no value, and a flag no verb knows

$ fettle edit f.txt --insert-after 1 --text
refused: --text needs a value. Write --NAME= to pass an empty one
$ fettle find --gob
refused: no such flag: --gob. Run fettle help for the list

Both answer 2. Ignoring either would produce a wrong answer rather than a failure. A flag with no value would swallow the next word as its value and write the word true into the file.

A configuration in the old flat shape

Before 2.1.0, trees, tasks, replacements and models sat at the top of the file, and a screen sat inside a tree. That shape is refused with exit 2, not read. A file that means one thing to the old version and another to this one has a boundary nobody can state. Take this file:

{
  "trees": { "work": { "path": ".", "screen": true } },
  "tasks": { "build": { "run": "dotnet build" } }
}

The refusal names the first old key it found and the file. It ends with the file's own entries moved under the new sections, so the fix is to paste them:

has "trees" at the top, which is the shape this version no longer reads. Rewrite the
file with three sections, one per level. Your entries, rewritten:
{"guardrails":{"trees":{"work":{"path":"."}},"tasks":{"build":{"run":"dotnet build"}}},
"screenings":{"screen":{"work":true}}}

The message is printed on one line. It is wrapped here to fit the page. trees, tasks and replacements move under guardrails. models moves under screenings. Each screen leaves its tree or scope and goes under screenings, keyed by the tree name, or the tree name, a slash and the scope path.

A section or a key in the wrong place

Each of these is exit 2, and the configuration does not load. The message names the file.

• An unknown key at the top says: has "NAME" at the top. The top holds three sections, one per level: tools, guardrails, screenings.
• A guardrails section in the machine file says: is the machine file, and it has a "guardrails" section. A tree, a task or an execute grant here would apply to every project on the machine, and no project reviewed it. Move the section to a project's .fettler.json.
• A screen inside a tree entry says: tree 'work' has a "screen". A screen now goes under "screenings", keyed by the tree or scope: {"screenings":{"screen":{"work":true}}}. A screen inside a scope gets the same message with the key work/SCOPE.
• A screen key naming no tree, such as "/records", says: has a "screen" key that names no tree. Write the tree name first. A key naming a tree that is not declared lists the trees there are.
• A guardrails section with no trees says: has a "guardrails" section that declares no trees. Add a "trees" object to it, or remove the section to use the launch folder as the tree.

A tree name fettle already uses

fettle opens some trees itself (see the trees fettle finds), and a declared tree may not take their names. Both of these are exit 2.

• A declared tree called scratch, tool-results or memory says: declares a tree called 'scratch'. fettle gives that name to the client's scratch folder and finds the folder itself. Remove the tree, or give it another name.
• A declared tree with a companion's name, on a different folder, says: tree 'sparky' is declared on FOLDER, and fettle also opens OTHER under that name: HOW. Give the declared tree another name. A declared tree of the same name on the same folder is allowed. It is the same pairing written by hand.

setup with the client first

$ fettle setup claude-code --local
refused: setup takes the level first, then the client. Run: fettle setup tools claude-code,
fettle setup guardrails claude-code or fettle setup screenings claude-code
$ echo $LASTEXITCODE
2

Exit codes

An exit code is the number a program hands back when it finishes. 0 means success. Callers chain on exit codes because PowerShell 5.1 has no &&. The machine-readable answer carries the same word as an outcome field.

doctor is the exception, because it reports rather than operates: 0 healthy or not applicable, 1 warnings only, 2 anything broken (a broken registration, or finding 2.19). --hook always exits 0, and says nothing about a level that is off.

Where to say it so it is read

Ranked by how much each changes behaviour.

What each says depends on the levels that are on. The MCP instructions open with the tools. Then one sentence says whether guardrails are on for this launch, and one says whether screenings are on.

setup tools writes no instruction block, because it writes only the registration. The guardrails paragraph says the built-ins are denied, which is true only once setup guardrails has written the deny list.

Everything doctor can report, and how to clear it

fettle doctor prints the version and the PATH line, then one section per level. Each section opens with the level's name and whether it is on. A level that is off is one line. A finding is reported only when its level is on. With guardrails off, nothing in the guardrails rows below can appear.

• The tools section holds the wiring rows, the client's folders with how each was found, the machine file when it supplied something, each companion's root as a fact, and finding 2.11.
• The guardrails section holds every other numbered finding. Each one is a way round the boundary the section declares.
• The screenings section lists burler beside fettle, the models directory, and the model installed for each category.

A finding marked ! is serious. One marked - is worth knowing. doctor exits 0 when healthy, 1 for warnings only, and 2 when something is broken: a broken registration, or finding 2.19.

Note setup adds and never deletes. So anything below whose fix is "remove" is a person's edit, in an editor. That is deliberate. A tool that quietly removed your configuration would be doing the very thing this design objects to.

The wiring

The wiring belongs to the tools level. It is one row per client, for the global registration and the one in this project, ending in a verdict.

In doctor --json, each row's "reach" is "global" or "repo". Before 2.1.0 that key was called level.

The findings

With guardrails off, a companion's root is one line of fact in the tools section and never a finding. No declared tree states a rule the companion could ignore.

What this defends against, and what it does not

That bound matters, because it says how far each rule has to go.

• The rule-file refusal has to be reliable, not tamper-proof. It must never be reached by a tool call in normal use. It does not have to survive somebody editing .fettler.json in a text editor. That person is the author of the rules, not a threat to them.
• No integrity checking, no signing, no lockfiles. All of that defends against an adversary who is not in the model.
• Path comparison is what containment is. It does not defend against another process replacing a path component between the check and the operation. Closing that gap needs operating-system support this does not have. A synced folder (Dropbox, OneDrive, a network share) is where it is likeliest to matter. Those are ordinary trees and get no special handling, because none exists and none is wanted.

This is stated because the alternative is scope creep. Every rule here could be hardened indefinitely against an attacker nobody is worried about.

Routes this tool does not close

Each item below is a way for data to reach the model, or leave it, that does not pass through a Fettler tool. Each is stated so that nobody mistakes it for something Fettler covers.

• At the tools level there is no deny list. Fettler's own tools stay inside the open trees. The client's own built-in tools (its reader, its editor, its shell) are not Fettler's, and they reach whatever the client lets them reach. Turning the guardrails level on is what closes that. fettle setup guardrails CLIENT --local writes the deny list, and doctor's findings report the routes that are still open.
• A companion server can send what the model has read. A companion is another MCP server whose registration passes --root. If it has commands that open a network connection, the model can hand it text it read through Fettler, and the companion can send that text anywhere. That route does not pass through a file. It is not a boundary this tool claims.
• The client's own publishing tools are the same. A client tool that publishes a page or posts a message (Claude's Artifact tool is one) sends whatever the model gives it. Fettler bounds which files are read. It does not bound where the text goes after the model has it.