Add concept docs for all Care domains, with real permission model

versioned_docs/version-3.0/concepts/access/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "Access & Identity",
+  "position": 8,
+  "key": "access-concepts",
+  "link": {
+    "type": "generated-index",
+    "title": "Access & Identity",
+    "description": "Who can do what in Care — users, roles, and the permission model that governs access."
+  }
+}

versioned_docs/version-3.0/concepts/access/access-control.mdx

@@ -0,0 +1,110 @@
+---
+sidebar_position: 1
+---
+
+# Roles & Permissions
+
+Care decides what each person can see and do using **role-based access control (RBAC)**. A **permission** is the right to perform one action (for example, "Can Create Patient"); a **role** is a named bundle of permissions; and a role is granted to a user *within a boundary* — a facility, an organization, or a single patient. Access is never assigned to a user directly: it always flows permission → role → membership.
+
+## What it represents
+
+The access-control model captures three things working together:
+
+- **Permissions** — the smallest unit of access, one per action, each tagged with a **context** (the kind of resource it governs). Permissions are defined in code, not edited by users.
+- **Roles** — flat, named collections of permissions (for example, *Doctor* or *Nurse*). A role is not a job title or a type; it is just "this set of permissions." Built-in roles ship with Care; deployments can add their own.
+- **Memberships** — the link that grants a role to a user inside a specific boundary. The same user can hold *Nurse* in one facility and *Administrator* in an organization at the same time.
+
+A user's effective access in any context is the **union** of all permissions from every role they hold that reaches that context.
+
+## Standard roles
+
+Care seeds a set of built-in (system) roles. These cannot be edited or deleted, and they apply within the boundaries shown below.
+
+| Role | Applies in | What it is for |
+| --- | --- | --- |
+| Doctor | Facility, Government org | Clinicians who create encounters and read/write clinical data |
+| Nurse | Facility, Government org | Bedside care staff with clinical read/write access |
+| Staff | Facility, Government org | Front-desk and operational staff: registration, scheduling, non-clinical work |
+| Pharmacist | Facility | Medication and pharmacy workflows |
+| Volunteer | Facility, Government org | Limited helpers — can list patients and view responses, but not full clinical data |
+| Administrator | Facility, Government org | Operational admin within a boundary: manages users, facilities, and organizations |
+| Facility Admin | Facility | Full administrator of a single facility (assigned to whoever creates it) |
+| Admin | Facility, Government org | The broadest administrative role, including creating and deleting organizations |
+| Admin (role org) | Role organization | Administers a user-group ("role") organization and its connected groups |
+| Manager (role org) | Role organization | Manages members within a role organization |
+| Member (role org) | Role organization | Plain membership in a role organization |
+
+Deployments can also define **custom roles** with any chosen set of permissions — for example "Doctor (Read Only)" or "Scheduler." A custom role is just a different bundle; the system treats it exactly like a built-in one.
+
+## Boundaries and the organization tree
+
+A role is always granted *inside a boundary*, and the boundary type is one of three **role contexts**:
+
+```
+FACILITY → role applies within a facility
+GOVT_ORG → role applies within a government organization
+ROLE_ORG → role applies within a role (user-group) organization
+```
+
+Memberships are recorded by boundary type:
+
+- **OrganizationUser** — a user holds a role in a government or role organization.
+- **FacilityOrganizationUser** — a user holds a role in a facility (or one of its sub-departments).
+- **PatientUser** — a user holds a role scoped to a single patient.
+
+Organizations form a **tree**: a government organization can contain sub-organizations, and a facility can contain departments. A role granted at a parent **cascades to every descendant** — if you are an Administrator of a district, you hold that access in all facilities and units beneath it, without a membership at each one. When Care checks access, it looks at the target plus all of its ancestors and collects every permission you hold along that chain.
+
+## How a permission is decided
+
+Each permission carries a **permission context** describing the resource it governs. When Care serializes a resource for a user, it only counts permissions in the relevant contexts:
+
+| Context | Governs |
+| --- | --- |
+| `GENERIC` | Not tied to a specific resource type |
+| `FACILITY` | Facility-level actions |
+| `PATIENT` | A patient record and its data |
+| `ENCOUNTER` | A single encounter |
+| `ORGANIZATION` | A government or role organization |
+| `FACILITY_ORGANIZATION` | A facility organization (department) |
+| `QUESTIONNAIRE` | Questionnaires |
+
+So a request to read a patient resolves to "which roles do I hold that reach this patient, and do any of them carry a `PATIENT`/`FACILITY` permission for this action?" The answer is computed live from the user's memberships and the organization tree.
+
+## Permissions
+
+Permissions are declared in code with a display name, a context, and the default roles that hold them. The complete set of organization- and user-related permissions follows.
+
+### Organization permissions
+
+| Permission | Description | System Roles |
+| --- | --- | --- |
+| Can View Organizations | View organizations the user can reach | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org), Member (role org) |
+| Can Create Organizations | Create new organizations in the tree | Admin |
+| Can Delete Organizations | Delete existing organizations | Admin |
+| Can Manage Organizations | Change an organization's name, description, metadata, etc. | Admin, Admin (role org) |
+| Can Manage Users in an Organization | Add, remove, and assign roles to users in an organization | Admin, Administrator, Facility Admin, Admin (role org) |
+| Can Manage Connected Role Organizations | Add, remove, and assign roles to users in connected role organizations | Admin (role org), Manager (role org) |
+| Can List Users in an Organizations | List the users who belong to an organization | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org) |
+| Is Geo Admin | Geo Admins can manage facilities in their organization | (no default roles) |
+
+### User permissions
+
+| Permission | Description | System Roles |
+| --- | --- | --- |
+| Can create User in care | Create new user accounts in Care | Admin, Facility Admin, Administrator |
+| Can list Users in Care | List user accounts in Care | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist |
+
+Roles are granted to users through organization, facility-organization, or patient memberships, and access is scoped by the organization tree: a permission held at a parent organization cascades to its descendants, and a user's effective permissions in any context are the union of all roles that reach it. Permissions themselves are platform-maintained reference data — administrators assign roles, not individual permissions.
+
+## Related
+
+- Reference: [Role (technical)](../../references/access/role.mdx)
+- Reference: [Permission (technical)](../../references/access/permission.mdx)
+- Reference: [Permission association (technical)](../../references/access/permission-association.mdx)
+- Concept: [User](./user.mdx)
+- Concept: [Organization](../facility/organization.mdx)
+- Concept: [Facility](../facility/facility.mdx)
+
+## FHIR reference
+
+Care's roles and permissions are an internal authorization model rather than a clinical resource, so they do not map to a single FHIR resource. They align in spirit with FHIR's access-control concepts (such as the `Permission` and `Role`/`PractitionerRole` resources), but enforcement is Care-specific.

versioned_docs/version-3.0/concepts/access/user.mdx

@@ -0,0 +1,64 @@
+---
+sidebar_position: 2
+---
+
+# Users
+
+A **user** in Care is an account that a person — or a machine integration — uses to sign in and act in the system. Users are the *who* behind every record: a user creates a patient, documents an encounter, or places an order, and the system tracks what each account is allowed to do through roles and organizations.
+
+## What it represents
+
+A user account captures:
+
+- **Identity & profile** — name (with prefix and suffix), username, gender, date of birth, and profile picture
+- **Contact** — phone number, alternate phone, and email
+- **Clinician credentials** — qualification, medical council registration, experience, and weekly working hours (for staff who deliver care)
+- **Authentication & security** — password, multi-factor authentication (TOTP and backup codes), and web-push notification keys
+- **Placement** — the geographic organization and facility a user belongs to, plus the roles they hold in each
+- **Account type** — whether the account is a real person or a service account used by an integration
+
+A user is *not* the same as a role. The account is the identity; the roles attached to it (in one or more organizations) decide what that identity can do.
+
+## Types of accounts
+
+| Type | Purpose |
+| --- | --- |
+| Human user | A person who signs in — clinicians, nurses, registration staff, administrators |
+| Service account | A non-human account used by an integration or automation to talk to Care's API |
+
+Clinician fields such as qualification and council registration are only meaningful for staff who provide care; administrative and service accounts leave them blank.
+
+## Relationships
+
+- **Organizations & facilities** — a user is placed in a geographic organization and can be assigned roles across many organizations and facilities. This placement is what grants access.
+- **Patients & encounters** — when a user creates or updates a clinical record, the account is recorded as the actor; clinical history stays auditable to the user who entered it.
+- **Skills** — users can be tagged with skills (competencies) for scheduling and discovery.
+
+## Identifiers
+
+Each user has a stable public identifier (surfaced as `id` in the API) that is separate from the username. Usernames, phone numbers, and emails must each be unique across the system, so they can also locate an account during sign-in and administration.
+
+## Permissions
+
+User administration is governed by the user permission set. The complete set of user permissions, what each allows, and the system roles that hold it by default:
+
+| Permission | Description | System Roles |
+| --- | --- | --- |
+| Can create User in care | Create new user accounts within a facility | Admin, Facility Admin, Administrator |
+| Can list Users in Care | List and view user accounts in the facility | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist |
+
+Creating users is reserved for administrators, while most clinical and support roles can list and view other users in their facility. Roles are granted to a user through organization, facility-organization, and patient memberships, and access is scoped by the organization tree — a permission held at a parent organization cascades to its descendants. A superuser bypasses these checks entirely.
+
+For the broader model of how roles, permissions, and organizations combine to decide access, see [Access control](./access-control.mdx).
+
+## Related
+
+- Reference: [User & Skills (technical)](../../references/access/user.mdx)
+- Concept: [Access control](./access-control.mdx)
+- Concept: [Organization](../facility/organization.mdx)
+- Concept: [Facility](../facility/facility.mdx)
+- Concept: [Patient](../clinical/patient)
+
+## FHIR reference
+
+A care-providing user aligns with FHIR's **Practitioner** resource, and a user's role within an organization aligns with **PractitionerRole**. Care keeps the account identity and its organization-scoped roles as related but distinct ideas, mirroring that separation.

versioned_docs/version-3.0/concepts/billing/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "Billing",
+  "position": 4,
+  "key": "billing-concepts",
+  "link": {
+    "type": "generated-index",
+    "title": "Billing",
+    "description": "How charges, accounts, invoices, and payments come together to bill for care."
+  }
+}