> ## 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.

# Settings

> How configuration works — the scope chain, definitions and overrides, and where each kind of setting lives.

**Settings → `/settings`** (organisation) · **Config Settings → `/config-settings`** (engine)

Nyumba Zetu keeps configuration in one engine with one resolution rule, rather than scattering
switches across modules. Understanding the rule explains most "I changed it and nothing happened"
questions.

## The scope chain

A setting is resolved by walking from the most specific scope to the least, and taking the first
value found:

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

The most specific scope wins. This is how one scheme runs a stricter collections ladder, a
different billing day, or a different late-fee policy without duplicating everything else.

<Warning>
  If a change at organisation level has no effect, something more specific is overriding it. Check
  branch, block, unit and lease before assuming the setting is broken.
</Warning>

## Definitions and overrides

The settings engine has two halves:

| Surface                  | What it holds                                                                                                                       |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Settings Definitions** | The catalogue: key, display name, module, category, subcategory, type, default value, and the scopes at which it may be overridden. |
| **Settings Overrides**   | The actual values set at a scope, with what they apply to.                                                                          |

A definition without an override uses its default. An override without a definition cannot exist.

### Reading the definitions list

| Column                              | Meaning                                                |
| ----------------------------------- | ------------------------------------------------------ |
| **Key**                             | The stable identifier modules read.                    |
| **Display name**                    | The human label.                                       |
| **Module / Category / Subcategory** | Where the setting belongs and how it groups in the UI. |
| **Type**                            | The value's data type.                                 |
| **Value**                           | The default.                                           |
| **Sort**                            | Display order within its category.                     |

### Reading the overrides list

| Column                                  | Meaning                            |
| --------------------------------------- | ---------------------------------- |
| **Key**                                 | Which setting is overridden.       |
| **Value**                               | The value at this scope.           |
| **Org / Branch / Block / Unit / Lease** | The scope the override applies to. |

## Changing settings in context

You rarely need the raw engine. Most screens with configurable behaviour carry a **settings gear**
that opens the settings for that area, filtered to its category and set at the scope you are
working in. Changing a collections threshold from the collections console is safer than finding the
key in a list of hundreds.

## Where each kind of configuration lives

| Kind                                  | Where                                                                       |
| ------------------------------------- | --------------------------------------------------------------------------- |
| Organisation identity, branding, plan | **Settings → Account / Property / Plan & billing**                          |
| Users, roles, branch assignment       | **Settings → Team / Roles**. See [Users and roles](/guides/users-and-roles) |
| Notification behaviour                | **Settings → Notifications**                                                |
| Security and sessions                 | **Settings → Security**                                                     |
| Background jobs                       | **Settings → Jobs**, and [Scheduled tasks](/guides/scheduled-tasks)         |
| Organisation notices                  | **Settings → Notice**                                                       |
| Running release                       | **Settings → Version**                                                      |
| Accounts and service types            | [Chart of accounts](/guides/chart-of-accounts)                              |
| Payment matching and allocation order | [Payment rules](/guides/payment-rules)                                      |
| Module availability per scope         | [Feature flags](/guides/feature-flags)                                      |
| Message content                       | [Templates](/guides/message-templates)                                      |
| Collections thresholds and ladders    | [Collection strategies](/guides/collections/strategies)                     |

## Changing a setting safely

<Steps>
  <Step title="Decide the scope first">
    Ask whether this should be true for the organisation, or only for one branch or scheme. Setting
    at too broad a scope is the most common configuration mistake.
  </Step>

  <Step title="Check for existing overrides">
    A more specific override will win regardless of what you set.
  </Step>

  <Step title="Make the change">
    From the contextual settings panel where one exists.
  </Step>

  <Step title="Verify against the behaviour, not the value">
    Open the screen the setting affects and confirm it did what you expected.
  </Step>

  <Step title="Record why">
    Settings changes are audited, but the audit records what changed — the reason is worth noting
    for whoever reads it later.
  </Step>
</Steps>

## A caution on inert settings

A setting only does something if a module reads it. When new configuration is introduced, its
read-site is wired at the same time — a value that exists but is never read is worse than no
setting, because it looks like a control and is not one.

If you set something and behaviour does not change, and there is no more specific override,
raise it rather than assuming the value is wrong.

## Feature flags versus settings

|                         | Setting                            | Feature flag              |
| ----------------------- | ---------------------------------- | ------------------------- |
| **Question it answers** | "How should this behave?"          | "Is this available here?" |
| **Typical value**       | A threshold, a mode, an identifier | On or off                 |
| **Scope chain**         | Yes                                | Yes                       |

The two are converging onto one engine; today, module availability is managed under
[Feature flags](/guides/feature-flags).

## Common problems

| Symptom                                | Cause                                                                             |
| -------------------------------------- | --------------------------------------------------------------------------------- |
| Change had no effect                   | A more specific override wins.                                                    |
| A setting is missing                   | It has no definition for your organisation, or you lack the permission to see it. |
| Behaviour differs between two branches | Branch-level overrides — that is the engine working as designed.                  |
| A module disappeared                   | Feature flag, not a setting.                                                      |