Cursor's configuration lives not in one file but in a family of files with different scopes: permissions, the sandbox, skills, roles, event handlers, external servers, plugins, trees and the cloud environment. The main mistake in working with them is not ignorance of a field but the right field in the wrong file. That is why the reference puts the scope, not the parameter's name, in the first column: without a scope a field name is nearly useless, since keys that mean much the same thing occur in several mechanisms and mean different things in each.
It helps to lay the files and their subjects out in a table once. Below is that map: what exactly each file describes, where it lies and what matters about its layers. This is the case where an overview is more useful than details: knowing which file is responsible for what, you will find the right key in a minute instead of hunting for it in four places.
| File | What it describes | What to remember |
|---|---|---|
| Permissions file | Terminal commands, server tools, review guidance | The layers merge, but a team configuration in the dashboard overrides them |
| Sandbox file | File and network boundaries of execution | The project layer outranks the user one |
| Project rules | Durable instructions with a scope of application | They require a header; plain markdown is ignored |
| Skills | Procedures with scripts and assets | Scripts are executable code and need review |
| Roles | Separate contexts with a model and rights | The read-only flag carries the main load |
| Event handlers | Lifecycle reactions | Executable policy with source priority |
| External servers | Transport, address, authorization, tools | Secrets are substituted from the environment |
| Plugins | A portable bundle of components | The manifest and contents are reviewed before installing |
| Trees | Preparing an isolated checkout | Setup scripts execute at creation |
| Cloud environment | Build, install, start |
| Install is idempotent; processes do not survive the stage |
Priorities deserve particular attention. Different mechanisms have different ones: somewhere the project file outranks the user one, somewhere arrays merge, somewhere the administrative layer cannot be loosened from below. There is no single rule, and that is fine - different mechanisms solve different tasks. But it means priority is checked in the documentation of the specific mechanism rather than inferred by analogy with a neighboring one.
How a conflict is actually resolved is best seen in the sandbox network policy. It has three parts: a list of what is allowed, a list of what is denied, and the action taken by default when no rule matched. Denial has the highest priority and blocks even what is simultaneously listed as allowed, and the default action is to deny. That scheme is not accidental: it makes the result predictable as rules are added, because a new allowing rule never weakens a denial already written. When checking someone else's configuration you start from the deny list and the default value rather than from the allow list - those are what define the shape of the boundary.
A separate group are files that contain executable content: event handlers, skill scripts, tree setup scripts, external server definitions. What distinguishes them is not the format but the consequences: they run code with your rights. The rule of reviewing them as code rather than as settings applies to them. A practical test: if a file can start a process, it belongs to this group even when it looks like a harmless list of paths.
There is also a useful organizational technique: separate the files by who owns them. Personal preferences in the user layer, team boundaries in the repository, mandatory requirements in administrative policy. When that separation holds, the question of who may change this has an obvious answer, and arguments about configuration turn into a discussion of layers rather than intentions.
A misplaced key has one common symptom: silence. An unknown field usually raises no error, the file is read, the mechanism runs on its defaults, and from the outside everything looks configured. Hence a set of frequent cases: a skill file without a header is taken for ordinary markdown and is never attached; a skill name that does not match the folder name breaks recognition; a rule with neither a description nor path patterns has no reason to be selected. The practical conclusion: after editing a configuration you verify not that the file was saved but that the mechanism saw the change - through the list of what is loaded, or through an attempt that used to pass and must now be blocked.
A simple practical check of the map: take any requirement from your policy and name the file it lives in. If there is no such file, or there are several, the requirement exists only in people's heads. That exercise takes half an hour and usually finds two or three requirements everyone believed were configured.
The engineering conclusion is simple: a map of files matters more than a list of fields. Fields change while the structure of responsibility remains: boundaries in one place, procedures in another, executable content in a third and under review. Holding that map in your head, you stop hunting for a key at random and start looking where it should be.
The typical failures are predictable. Writing the right key into the wrong file. Inferring priority by analogy with another mechanism. Reading a network policy from the allow list instead of the deny list. Taking a file with executable content for an ordinary setting. And having a requirement with no file it lives in.