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

# Feature flags

> Turn modules and behaviours on for a scope, and roll new capability out branch by branch.

**Admin → Feature Flags → `/feature-flags`**

A feature flag answers one question: **is this available here?** It is how a new module goes live
for one branch, is watched, and is then extended — rather than appearing for everyone at once.

## How flags resolve

Flags resolve through the same scope chain as [settings](/guides/settings), most specific first:

```
lease → unit → block → branch → organisation → platform default
```

A flag on for the organisation but off for one branch is off in that branch. That is the point.

## Managing a flag

| Element      | Purpose                                |
| ------------ | -------------------------------------- |
| **New flag** | Create a flag definition.              |
| **Module**   | Which part of the platform it governs. |
| **Toggle**   | On or off at the selected scope.       |
| **Filters**  | Narrow the list by module and status.  |
| **Refresh**  | Re-read current state.                 |

<Steps>
  <Step title="Decide the scope">
    Almost always a branch. Organisation-wide is for capability everyone should have.
  </Step>

  <Step title="Turn it on">
    The module or behaviour becomes available to users with the right permission in that scope.
  </Step>

  <Step title="Tell the users">
    A module appearing without warning generates support calls, not adoption.
  </Step>

  <Step title="Watch before extending">
    Give it a full cycle in one branch before enabling it elsewhere.
  </Step>
</Steps>

## Flags, permissions and jobs

Three different things can make a screen or behaviour unavailable. Check them in this order:

| Layer            | Question                                   | Where                                                           |
| ---------------- | ------------------------------------------ | --------------------------------------------------------------- |
| **Feature flag** | Is this capability enabled for this scope? | Feature flags                                                   |
| **Permission**   | Is this user allowed to use it?            | [Roles and permissions](/getting-started/roles-and-permissions) |
| **Job switch**   | Is the background work behind it running?  | [Scheduled tasks](/guides/scheduled-tasks)                      |

A collections module that is flagged on, permitted, but whose sweep job is off will show an empty
worklist forever — and none of the three layers is broken.

## Flags and shadow mode

A flag makes a module *available*. It does not authorise it to act autonomously. Engines that
touch money or reach residents also carry an **enforcement mode** setting that starts in shadow —
staging actions for a human to confirm.

Enabling the flag and switching enforcement to autonomous are two separate decisions, taken at two
different times, on purpose.

## Rollout pattern

<Steps>
  <Step title="Enable in one branch">
    Ideally one with an engaged team who will report problems.
  </Step>

  <Step title="Run in shadow for a full cycle">
    Read what the engine would have done.
  </Step>

  <Step title="Enable action, still supervised">
    Humans confirm each action.
  </Step>

  <Step title="Extend to more branches">
    Once the first branch is boring.
  </Step>

  <Step title="Consider autonomy last">
    And per branch, never globally.
  </Step>
</Steps>

## Convergence with settings

Feature flags and settings are converging onto a single configuration engine — same scope chain,
same definition-and-override model. Behaviour does not change for you; where a flag lives may.
See [Settings](/guides/settings).

## Common problems

| Symptom                            | Cause                                                        |
| ---------------------------------- | ------------------------------------------------------------ |
| Module missing for one branch only | Flag off at that scope.                                      |
| Module visible but empty           | The job behind it is off, or nothing meets its criteria yet. |
| Some users see it, others do not   | Permission, not the flag.                                    |
| Enabled but nothing is sent        | Shadow mode — actions are staged, not executed.              |