Docs

Profiles

AvailableReviewed 29 October 2026

A profile is a named permission set for a population, written in YAML. Occlude resolves it, with a grant, into a signed manifest for one session.

An example

The profile our fixture repository runs under: a frontend contractor on a payments monorepo.

profile: frontend-contractor
repo: acme/payments-platform
rules:
  - { path: "src/web/**",               state: visible }
  - { path: "src/components/**",        state: visible }
  - { path: "src/components/vault/**",  state: occluded }
  - { path: "package.json",             state: read-only }
  - { path: "tsconfig*.json",           state: read-only }
  - { path: "vite.config.ts",           state: read-only }
  - { path: "node_modules/**",          state: read-only }
absent:
  - ".env*"
  - "db/seeds/**"
  - "infra/secrets/**"
# everything unlisted resolves to occluded
broker: { scripts: [dev, build, test], submit: true }
ttl: 8h

Read it as: the web app and the shared components are Visible, except one folder of card-handling components that stays Occluded. The build configuration is Read-only. Dependencies are Read-only. Environment files, data seeds and infrastructure secrets are Absent. Everything else in the repository, including the billing engine, is Occluded: it builds, and the contractor cannot read it. The build may run three scripts, the contractor may open a pull request, and a session lasts eight hours.

Fields

Field	Content
`profile`	The profile's name
`repo`	The repository it applies to
`rules[]`	Each rule: `path`, a glob; `state`, one of `visible`, `read-only`, `occluded`, `absent`; optional `on_attempt`, `silent` or `held`
`absent[]`	Globs excluded from the workspace entirely, on both sides. Never mounted, never in memory
`broker`	`scripts`: the script names from the project's manifest the person may run. `submit`: whether `occlude submit` may open a pull request
`ttl`	How long a session under this profile lasts before it ends on its own

How rules resolve

The most specific matching rule decides: the longest matching path prefix.
When two rules of equal specificity disagree, the lower state wins. From highest to lowest: Visible, Read-only, Occluded, Absent.
A path no rule matches is Occluded. Nothing becomes Visible by omission.
absent[] caps every rule: a path it lists is Absent, whatever a rule says.

Rule order in the file does not matter, so a profile can be audited from the file alone. In the example, src/components/vault/** is more specific than src/components/**, so the card components stay Occluded inside a Visible tree.

Where profiles come from

Hand-written path lists per ticket are the overhead that sinks tools like this, so profiles are derived. Observation Mode records which files each build, test and ticket touches and writes profile templates from it; an admin reviews and names them. Its secret-pattern detectors propose Absent for every credential and data seed they find, so the absent list starts from evidence, not memory.

Profiles by population

Population	Default	Example
Contractor	Occluded everywhere, Visible on the task's files, Absent on secrets and seeds	The frontend contractor above
Agent	As a contractor, bound to the files its plan declares, with a session time box	An agent fixing one ticket: Visible on its declared files, `infra/` Occluded, `.env` Absent*
Employee	Visible everywhere, Occluded only on named compartments	A mixed-nationality team: `guidance/*` Occluded* for some people, everything else Visible