<!--
  Explanation — Marula PSA documentation
  Source: /docs/psa/next/explanation
  License: CC BY 4.0 — https://creativecommons.org/licenses/by/4.0/
  Source file: https://github.com/marulahq/marula-core/tree/main/docs/site/explanation/index.md
-->
---
description: "These pages explain why Marula works the way it does: why renaming a board column never breaks an SLA timer, why billing corrections create credit notes…"
---

# Explanation

These pages explain **why** Marula works the way it does: why renaming a board column never breaks an SLA timer, why billing corrections create credit notes instead of editing sent invoices, and why AI features ship turned off by default.

If you want a step-by-step lesson, start in [Tutorials](https://getmarula.com/docs/psa/next/tutorials). If you want a quick checklist for a daily job, go to [How-to guides](https://getmarula.com/docs/psa/next/how-to). For schemas and endpoints, see [Reference](https://getmarula.com/docs/psa/next/reference). When something is broken rather than unexplained, [Troubleshooting](https://getmarula.com/docs/psa/next/troubleshooting) starts from the symptom.

- [Why we're building Marula](https://getmarula.com/docs/psa/next/explanation/why-marula) — Our product manifesto, quoted word for word from `MANIFESTO.md`. Audience: both.
- [Instant-first interaction](https://getmarula.com/docs/psa/next/explanation/instant-first) — Why there is no Save button to chase, how optimistic updates and `Ctrl/Cmd+Z` undo work, and why assistant suggestions wait for human approval. Audience: both.
- [Customizations are data](https://getmarula.com/docs/psa/next/explanation/customizations-are-data) — Why custom fields, board workflows, and automation rules are stored as structured data rows so software updates never break your setup. Audience: both.
- [Contract relationship types](https://getmarula.com/docs/psa/next/explanation/contract-relationship-types) — How Marula models the six MSP agreement types (recurring, retainer, time & materials, fixed fee, per unit, and per incident), plus prepaid blocks, caps, minimums, escalators, change orders, and SLA credits. Audience: both.
- [Billing corrections](https://getmarula.com/docs/psa/next/explanation/billing-corrections) — Why issued invoices lock permanently, how credit notes and pre-bill verification adjustments work, and why sales tax is calculated in your accounting software. Audience: both.
- [FX additivity](https://getmarula.com/docs/psa/next/explanation/fx-additivity) — How multi-currency billing anchors to one base currency, why the exchange-rate book is append-only, and why reconciliation totals are grouped by financial document type. Audience: both.
- [Provenance vs audit](https://getmarula.com/docs/psa/next/explanation/provenance-vs-audit) — The difference between **Provenance** (who changed a specific field on a record, from what value to what value) and **Audit** (security and administrative events across your organization). Audience: both.
- [Knowledge-base categories and the secret vault](https://getmarula.com/docs/psa/next/explanation/kb-class-categories) — How folder permissions work for help articles and passwords, why restricted items are completely hidden rather than shown as locked rows, and how every password reveal is logged. Audience: both.
- [The portal isolation model](https://getmarula.com/docs/psa/next/explanation/portal-isolation) — How client portal accounts, ticket boards, and Knowledge Base searches are fenced off per client company. Audience: both.
- [AI: deny-by-default and the decision harness](https://getmarula.com/docs/psa/next/explanation/ai-deny-by-default) — Why the master AI switch ships **OFF**, how per-role surface grants work, and how triage/routing models record their probability scores for inspection. Audience: both.
- [The upgrade compatibility policy](https://getmarula.com/docs/psa/next/explanation/upgrade-policy) — How the N-2 upgrade guarantee and expand-then-contract database migrations keep self-hosted upgrades predictable. Audience: admin.