Docs
Concepts
One idea runs through every page. A session has two sides. The person's side shows the files their task needs. The build's side has the whole repository.
The occlusion layer
The occlusion layer is a property of the runtime, not of a client. Inside one session's workspace it presents a filtered tree to one channel and the full tree to the other.
No client is trusted to filter anything. A client asking for an Occluded path gets the same answer as a client asking for a path that does not exist: ENOENT, never "permission denied", because "permission denied" confirms the file exists.
Two channels
| Channel | Runs as | Sees | Runs |
|---|---|---|---|
| System channel, the build's side | Its own user, on the real mount | The full tree minus Absent paths | The compiler, test runner, dev server, stub generation and git |
| User channel, the person's side | A second user, isolated from the build | Visible and Read-only files, plus declaration stubs where their code imports an Occluded module | The person's shell, editor server, language server, and anything they start |
Between them: ptrace is denied across the two users, nothing attaches interactively to the build's side, and build output is sanitised before it crosses. The person starts work on the build's side only by name, through the job runner: a script from the project's manifest, such as npm run dev or npm test, or a fixed verb such as occlude submit.
Profiles
An occlusion profile is a reusable, named permission set: rules that map paths to states. Profiles are derived from observation rather than written by hand per ticket. Observation Mode watches what builds, tests and tickets touch, and proposes them. See Profiles for the format.
Task grants
A grant binds one unit of work to a profile: a purpose (the ticket, the pull request, the agent's plan), a scope, and a time box. A grant whose scope touches an Absent path waits for a named approver. Expiry revokes everything, so there is no standing access to clean up. See Grants and sessions.
Sessions
The session, not the user, is the unit: one person's task, or one agent run. Each session gets its own workspace, started from a signed manifest and closed when its grant ends. A session's scope is the grant intersected with the granting admin's own access, so nobody grants what they do not hold.
Doors
A door is any client attached to the user channel. The browser workspace, VS Code over SSH, an agent over MCP and the agent inside Occlude all speak one protocol to the same workspace, so a file refused through one door is refused through every door. See Doors.
The record
Every decision emits one event: the rule that fired, the evidence (session, person or agent, channel, path, operation, time), and the profile change that would have allowed it. See The ledger.