# RentalDriveGo Settings Reorganization, Admin Menu Control, and Subscription Entitlements Plan

## Document Status

- **Purpose:** Planning and review only
- **Source code changes:** None
- **Target areas:** Dashboard, API, Admin, Database, shared types, and localization
- **Route:** `/dashboard/settings`
- **Supported plans:** `STARTER`, `GROWTH`, `PRO`
- **Supported languages:** English (`en`), French (`fr`), Arabic (`ar`)
- **Removed from scope:** Domain and Publishing
- **Menu ownership:** Platform Admin application
- **Company-user menu control:** Not permitted

---

## 1. Objective

Reorganize `/dashboard/settings` into focused sections while controlling individual settings capabilities through the company’s active subscription plan.

The target design must:

- Keep Settings available as a baseline route for every subscription plan.
- Show one focused settings section at a time.
- Grant or restrict individual capabilities through explicit subscription entitlements.
- Preserve unavailable configuration during upgrades, downgrades, suspension, or cancellation.
- Enforce the same rules in the Dashboard and API.
- Support English, French, and Arabic, including true RTL behavior.
- Avoid hard-coding authorization decisions in the frontend.
- Keep company role permissions separate from subscription permissions.
- Make the platform Admin application the sole authority for settings menu configuration.
- Prevent company owners, managers, and agents from enabling, disabling, reordering, or reassigning settings menu items.

---

## 2. Initial Settings Menu Items

The system will seed seven settings menu items:

1. Company Profile
2. Branding and Storefront
3. Payment Methods
4. Rental Policies
5. Insurance Policies
6. Pricing Rules
7. Accounting and Reports

These are the initial menu items, not frontend hard-coded subscription decisions.

The platform Admin may:

- Enable or disable a menu item globally.
- Assign a menu item to one or more subscription plans.
- Choose whether an unavailable item is hidden or displayed as locked.
- Change its display order.
- Change its icon from an approved icon list.
- Edit its English, French, and Arabic label and description.
- Mark a menu item as required so it cannot be disabled for protected plans.
- Preview the resulting menu for a plan, company role, and subscription status.

The platform Admin may not:

- Change protected route keys or component keys.
- Point an item to an arbitrary URL.
- create a working settings capability merely by entering a new label.
- Bypass backend entitlement enforcement.
- Delete a protected core item while companies depend on it.

Company owners, managers, and agents cannot modify the menu structure or plan assignments.

Domain and Publishing is removed from this plan and must not appear in the seeded menu, components, entitlement matrix, tests, or acceptance criteria.

Protected section routes:

```text
/dashboard/settings?section=company
/dashboard/settings?section=storefront
/dashboard/settings?section=payments
/dashboard/settings?section=rental-policies
/dashboard/settings?section=insurance
/dashboard/settings?section=pricing
/dashboard/settings?section=accounting
```

The base route `/dashboard/settings` opens the first enabled item the current user may access. Company Profile is the required fallback.

---

## 3. Admin-Owned Menu and Subscription Design Principle

The platform Admin controls the settings menu configuration and its subscription-plan assignments.

The subscription plan controls **capabilities**, not merely page visibility.

The Settings route remains available to all plans because it contains required company and recovery settings. Individual sections or controls may be:

- **Enabled:** The user may view and edit the capability.
- **Read-only:** The user may view saved configuration but cannot change or use it.
- **Locked:** The capability is unavailable and displays its required plan.
- **Hidden for security:** Sensitive fields are not rendered when the user is not entitled.
- **Recovery-only:** The page displays account status and a route to subscription recovery.

The frontend must never decide access by checking whether the plan name is “higher” than another plan. It must consume the resolved menu and entitlement results from the API.

The Admin configuration is the source of truth for:

- Which settings menu items exist in the published menu.
- Which plans receive each item.
- Whether unavailable items are hidden or locked.
- The order, icon, labels, and descriptions.
- Whether an item is globally enabled.

The Dashboard only renders the resolved result. It does not provide menu customization controls to company users.

---

## 4. Recommended Plan Positioning

### STARTER

Essential company setup and basic rental operations.

### GROWTH

Online commerce, customer-facing customization, and operational automation.

### PRO

Advanced reporting, scheduled delivery, governance, and the complete settings feature set.

This positioning gives each upgrade a concrete operational reason. Randomly scattering premium locks across basic fields would create irritation, not a pricing strategy.

---

## 5. Initial Admin-Configured Feature Entitlement Matrix

This matrix is the recommended initial seed. The platform Admin may modify plan assignments through the Admin application after deployment, subject to protected-core rules.

Legend:

- **Edit:** View and modify
- **Basic:** Limited version of the capability
- **Read:** View existing configuration only
- **Locked:** Unavailable; show required plan
- **Full:** Complete capability

| Settings capability | STARTER | GROWTH | PRO |
|---|:---:|:---:|:---:|
| Company profile | Edit | Edit | Edit |
| Public contact information | Edit | Edit | Edit |
| Default language and currency | Edit | Edit | Edit |
| Storefront listing toggle | Edit | Edit | Edit |
| Basic logo and public identity | Edit | Edit | Edit |
| Custom brand colors | Locked | Edit | Edit |
| Hero image and advanced storefront branding | Locked | Edit | Edit |
| Renter payment providers | Locked | Edit | Edit |
| Basic fuel and damage policies | Edit | Edit | Edit |
| Automated additional-driver fees | Locked | Edit | Edit |
| Insurance policy management | Locked | Full | Full |
| Pricing rules | Locked | Full | Full |
| Basic accounting defaults | Locked | Edit | Edit |
| Scheduled accountant report delivery | Locked | Locked | Edit |
| Advanced report formats and delivery controls | Locked | Locked | Full |

### Important boundary

“Payment Methods” in this settings page means payment providers used by rental customers. It does not mean the company’s SaaS subscription payment provider.

---

## 6. Machine-Readable Entitlement Keys

Each capability must use an immutable feature key.

Recommended keys:

```text
settings.company_profile
settings.public_contact
settings.locale_currency
settings.storefront_listing
settings.branding_basic
settings.branding_custom
settings.branding_hero
settings.renter_payments
settings.rental_policies_basic
settings.additional_driver_fees
settings.insurance_policies
settings.pricing_rules
settings.accounting_defaults
settings.accounting_scheduled_delivery
settings.accounting_advanced_formats
```

Rules:

- UI labels must never be used as entitlement identifiers.
- Translations must never control access.
- Plan access must be stored as explicit assignments.
- Missing assignments mean unavailable.
- Company overrides may disable an entitled feature.
- Company overrides must not unlock a feature outside the active subscription plan.

---

## 7. Section-Level Behavior

## 7.1 Company Profile

### Availability

- STARTER: Full
- GROWTH: Full
- PRO: Full

### Fields

- Display name
- Tagline
- Public email
- Public phone
- WhatsApp number
- City
- Country
- Website URL
- Default language
- Default currency

### Requirements

- This section must never be locked by plan.
- It remains available during subscription recovery.
- Use the shared Moroccan city selector where applicable.
- Validate email, phone, website, locale, and currency.
- Explain whether the selected language affects the storefront, contracts, or both.

---

## 7.2 Branding and Storefront

### STARTER

Available:

- Storefront listing
- Company logo
- Public identity preview
- Basic storefront information

Locked:

- Custom primary and accent colors
- Hero image
- Advanced storefront appearance controls

### GROWTH and PRO

Available:

- All STARTER branding capabilities
- Custom brand colors
- Hero image
- Full storefront branding controls

### UX behavior

- Keep the section visible for all plans.
- Group locked controls under an “Available on GROWTH” panel.
- Do not mix enabled and locked inputs without clear boundaries.
- Show image previews, accepted formats, dimensions, and upload limits.
- Preserve existing premium branding assets after downgrade.
- Do not display a retained premium asset publicly after the entitlement ends unless product policy explicitly allows a grace period.

---

## 7.3 Payment Methods

### Availability

- STARTER: Locked
- GROWTH: Full
- PRO: Full

### Providers

- AmanPay
- PayPal
- Future approved renter payment providers

### Requirements

- Show a concise locked-state explanation to STARTER.
- Show an upgrade action without rendering credential fields.
- Mask secret values.
- Never return saved secrets to the browser.
- Leaving a secret field blank must preserve the existing secret.
- Store credentials encrypted.
- Do not include credentials in logs, analytics, errors, or browser storage.
- Provider configuration must also require the relevant online-reservation entitlement when that dependency exists.

---

## 7.4 Rental Policies

### Basic policy availability

- STARTER: Full
- GROWTH: Full
- PRO: Full

Included:

- Fuel policy
- Customer-facing fuel note
- Damage policy

### Additional-driver fee automation

- STARTER: Locked
- GROWTH: Full
- PRO: Full

Included:

- Free
- Per-day fee
- Flat fee
- Conditional rate fields

### Requirements

- Hide irrelevant price fields based on charge type.
- Reject negative values.
- Display currency units.
- Preserve existing additional-driver fee configuration after downgrade.
- Stop applying premium fee automation to future reservations after entitlement loss.
- Keep historical reservation calculations unchanged.

---

## 7.5 Insurance Policies

### Availability

- STARTER: Locked
- GROWTH: Full
- PRO: Full

### Capabilities

- List policies
- Add policy
- Edit policy
- Activate or deactivate policy
- Mark required or optional
- Configure charge type and amount
- Delete when safe

### UX behavior

- Existing policies appear as a list.
- Creation and editing use a modal or side panel.
- Raw enum values are replaced with translated labels.
- STARTER sees a locked summary, not an empty form.
- After downgrade, saved policies remain stored and become read-only.
- Policies must not be offered on future reservations without entitlement.
- Historical reservations and contracts retain their applied insurance records.

---

## 7.6 Pricing Rules

### Availability

- STARTER: Locked
- GROWTH: Full
- PRO: Full

### Capabilities

- List rules
- Create rule
- Edit rule
- Duplicate rule
- Activate or deactivate rule
- Delete when safe
- Display a readable rule summary

Example:

```text
Add a 10% surcharge when the driver is younger than 25.
```

### Requirements

- Define whether matching rules stack.
- Detect conflicting rules where possible.
- Validate percentage and monetary ranges.
- Replace backend enum names with translated labels.
- After downgrade, rules remain stored and become read-only.
- Premium rules must stop applying to future pricing calculations.
- Historical calculations remain immutable.

---

## 7.7 Accounting and Reports

### STARTER

Locked.

### GROWTH

Available:

- Reporting period
- Basic report format
- Accountant name
- Accountant email
- Manual report defaults

Locked:

- Automatic scheduled delivery
- Advanced formats
- Multiple recipients
- Delivery history

### PRO

Available:

- All GROWTH accounting settings
- Automatic scheduled delivery
- Advanced report formats
- Delivery timing
- Delivery status and history, when supported

### Requirements

- Accountant email becomes required when automatic delivery is enabled.
- Display the company timezone used for scheduling.
- Do not promise delivery history unless the backend records it.
- After downgrade from PRO to GROWTH, disable future scheduled deliveries but preserve configuration.
- After downgrade to STARTER, accounting settings become read-only and no future automated delivery runs.

---

## 8. Settings Navigation Behavior

### Desktop

Use a persistent vertical navigation.

Each item contains:

- Icon
- Section title
- Optional status
- Optional plan badge
- Lock icon when unavailable

### Mobile

Use a compact selector or horizontally scrollable section navigation.

### Locked sections

Locked sections remain discoverable but must not dominate the interface.

Selecting a locked section shows:

- What the feature does
- Which plan includes it
- The company’s current plan
- A route to manage the subscription
- No sensitive or editable fields

### Current plan indicator

The page header displays:

- Current plan
- Subscription status
- Renewal or trial information
- A manage-subscription action

The header must not turn the settings page into a pricing advertisement. Its purpose is context.

---

## 9. Authorization Rule

A settings capability is available only when all required conditions are true:

```text
Feature is globally enabled
AND feature is assigned to the company’s active subscription plan
AND the company has not disabled the feature
AND the employee role permits the action
AND the subscription status permits the action
```

Subscription access and role access are separate checks.

Examples:

- A PRO plan does not grant an AGENT access to owner-only payment credentials.
- An OWNER role does not unlock a PRO feature on STARTER.
- Hiding a section in React does not authorize or secure the API.

---

## 10. Subscription-Status Behavior

| Status | Settings behavior |
|---|---|
| `ACTIVE` | Full entitled access |
| `TRIALING` | Access follows the trial’s assigned plan |
| `PAST_DUE` | Core settings editable; premium settings read-only; show recovery notice |
| `SUSPENDED` | Recovery mode; Company Profile read-only and subscription recovery available |
| `EXPIRED` | Recovery mode |
| `CANCELLED` | Recovery mode after the paid period ends |
| Missing subscription | Onboarding or recovery mode |

The effective access date must follow the subscription billing period. A scheduled cancellation must not remove paid access before `currentPeriodEnd`.

---

## 11. Upgrade and Downgrade Rules

## Upgrade

After a successful plan upgrade:

- Refresh entitlements immediately.
- Unlock newly available settings without requiring a new login.
- Preserve current page and section where possible.
- Do not auto-enable optional features without user action.
- Existing retained configuration may become editable again.

## Downgrade

At the effective downgrade date:

- Preserve all configuration.
- Make unavailable configuration read-only.
- Stop premium automation for future operations.
- Preserve historical reservation, pricing, insurance, and report records.
- Do not silently delete provider credentials or rules.
- Clearly display which capabilities are no longer active.
- Prevent API mutations for unavailable features.

## Failed payment or suspension

- Do not delete configuration.
- Stop restricted operational behavior according to subscription policy.
- Preserve access required to recover the account.

---

## 12. API Contract

The Dashboard must receive an Admin-resolved menu response and one authoritative settings-entitlement response.

Recommended menu endpoint:

```http
GET /companies/me/settings-menu
```

Example response:

```json
{
  "version": 12,
  "items": [
    {
      "menuKey": "company",
      "sectionKey": "company",
      "label": "Company Profile",
      "description": "Manage public company details.",
      "iconKey": "building",
      "sortOrder": 10,
      "state": "ENABLED",
      "requiredPlan": null
    },
    {
      "menuKey": "payments",
      "sectionKey": "payments",
      "label": "Payment Methods",
      "description": "Configure renter payment providers.",
      "iconKey": "credit-card",
      "sortOrder": 30,
      "state": "LOCKED",
      "requiredPlan": "GROWTH"
    }
  ]
}
```

The response must already reflect:

- The published Admin menu configuration.
- Active subscription plan.
- Subscription status.
- Company role.
- Global feature status.
- Hidden-versus-locked behavior.
- Current locale.

Recommended entitlement endpoint:

```http
GET /companies/me/settings-entitlements
```

Example response:

```json
{
  "plan": "GROWTH",
  "subscriptionStatus": "ACTIVE",
  "accessLevel": "full",
  "features": {
    "settings.company_profile": {
      "available": true,
      "editable": true,
      "reason": null
    },
    "settings.branding_custom": {
      "available": true,
      "editable": true,
      "reason": null
    },
    "settings.accounting_scheduled_delivery": {
      "available": false,
      "editable": false,
      "requiredPlan": "PRO",
      "reason": "This feature requires the PRO plan."
    }
  }
}
```

Requirements:

- The response is machine-readable.
- The reason is localized by key or mapped through shared translations.
- Entitlement data is not derived from marketing feature labels.
- API mutation endpoints independently enforce the same entitlement.
- Cached entitlement data is invalidated after plan, status, or admin assignment changes.

---

## 13. Backend Enforcement

Apply feature guards to every gated mutation and operational evaluation.

Examples:

```text
requireFeature("settings.branding_custom")
requireFeature("settings.renter_payments")
requireFeature("settings.additional_driver_fees")
requireFeature("settings.insurance_policies")
requireFeature("settings.pricing_rules")
requireFeature("settings.accounting_scheduled_delivery")
```

Enforcement must cover:

- Settings create, update, and delete endpoints
- Reservation price calculation
- Insurance selection
- Additional-driver fee calculation
- Storefront branding response
- Online payment processing
- Scheduled report jobs

Protecting only settings forms would leave the actual business behavior unlocked, which is a paywall made of decorative cardboard.

---

## 14. Data Model

Recommended menu item catalog:

```text
SettingsMenuItem
- id
- menuKey
- sectionKey
- protectedRoute
- componentKey
- iconKey
- labelKey
- descriptionKey
- sortOrder
- unavailableBehavior        // HIDDEN or LOCKED
- isGloballyEnabled
- isRequired
- createdAt
- updatedAt
```

Plan assignment:

```text
SettingsMenuItemPlanAssignment
- menuItemId
- plan
- enabled
```

Translation values may use the existing localization system or a protected translation table:

```text
SettingsMenuItemTranslation
- menuItemId
- locale                     // en, fr, ar
- label
- description
```

Menu-model rules:

- `menuKey`, `sectionKey`, `protectedRoute`, and `componentKey` are immutable outside migrations.
- Admin-editable icons must come from an allowlist.
- Admin changes to labels must require all three supported languages or preserve the previous value.
- Disabling a menu item does not remove its data or bypass API protection.
- A disabled core recovery item must always have a safe fallback.
- Menu order is controlled by `sortOrder`, not frontend array order.
- Menu plan assignment and feature capability assignment must remain consistent.
- The menu API must exclude arbitrary HTML and unsafe URLs.

Recommended feature catalog:

```text
SettingsFeature
- id
- featureKey
- sectionKey
- labelKey
- descriptionKey
- isGloballyEnabled
- isRequired
- createdAt
- updatedAt
```

Plan assignment:

```text
SettingsFeaturePlanAssignment
- featureId
- plan
- enabled
```

Optional company override:

```text
CompanySettingsFeatureOverride
- companyId
- featureId
- enabled
- reason
- expiresAt
```

Rules:

- A company override may disable access.
- A normal company override must not grant access above the active plan.
- Exceptional support overrides require audit records and expiration.
- Feature keys are unique and immutable.
- Migrations and seeds must be idempotent.

---

## 15. Admin Management

The platform Admin application is the only interface allowed to modify settings menu items and their plan availability.

### Admin menu-management screen

Recommended matrix:

```text
Order | Menu item | Icon | STARTER | GROWTH | PRO | Unavailable behavior | Global status
```

Supported Admin actions:

- Reorder items.
- Enable or disable items globally.
- Assign or remove an item from STARTER, GROWTH, or PRO.
- Choose `HIDDEN` or `LOCKED` behavior when a plan does not include it.
- Edit English, French, and Arabic labels and descriptions.
- Select an icon from an approved allowlist.
- Preview the menu for a selected plan.
- Preview the menu for a selected company role.
- Preview past-due, suspended, trial, and recovery states.
- View affected-company counts before publishing changes.
- Publish or discard menu configuration changes.
- View audit history and restore a previous published configuration.

### Protected controls

The Admin interface must not permit normal form editing of:

- `menuKey`
- `sectionKey`
- `protectedRoute`
- `componentKey`
- Feature entitlement keys
- Required recovery behavior

These values change only through reviewed code and database migrations.

### Company-user restrictions

Company owners, managers, and agents may:

- Open menu items granted by their plan and role.
- Edit the business settings inside permitted sections.
- View a locked item when Admin configured it as discoverable.

They may not:

- Add or remove settings menu items.
- Reorder settings menu items.
- Rename menu items.
- Change icons.
- Assign items to plans.
- Unlock a premium item.
- Change hidden-versus-locked behavior.

### Publishing and audit

Every Admin menu change must record:

- Administrator identity
- Timestamp
- Previous value
- New value
- Affected menu item
- Affected plans
- Optional reason
- Publish version

Changes should be staged and published atomically so companies do not receive a partially updated menu.

The Admin interface must warn before:

- Removing an item from a plan used by active companies.
- Globally disabling an item with saved configuration.
- Hiding a required recovery item.
- Publishing incomplete translations.
- Creating menu-to-feature assignment conflicts.

---

## 16. Component Architecture

Recommended Dashboard structure:

```text
src/app/(dashboard)/settings/
  page.tsx
  components/
    SettingsLayout.tsx
    SettingsNavigation.tsx
    SettingsSectionHeader.tsx
    SettingsSaveBar.tsx
    SettingsStatusBadge.tsx
    SettingsPlanGate.tsx
    SettingsLockedState.tsx

    CompanyProfileSection.tsx
    BrandingSection.tsx
    PaymentMethodsSection.tsx
    RentalPoliciesSection.tsx
    InsurancePoliciesSection.tsx
    PricingRulesSection.tsx
    AccountingSection.tsx

    InsurancePolicyForm.tsx
    PricingRuleForm.tsx

  settings.types.ts
  settings.constants.ts
  settings.validation.ts
  settings.entitlements.ts
  settings.i18n.ts
```

Responsibilities:

### `page.tsx`

- Load the Admin-resolved settings menu.
- Resolve the active section only from returned protected section keys.
- Load entitlement context.
- Render menu items in the Admin-defined order.
- Render the settings shell.
- Enforce route-level role access.
- Avoid individual form markup.

### `SettingsPlanGate`

- Receive a feature key.
- Render enabled, read-only, locked, or recovery states.
- Never contain plan-specific business rules.

### Section components

- Own section form state.
- Own validation.
- Own save and error states.
- Request only the data allowed by entitlements.
- Avoid changing unrelated settings.

---

## 17. Loading and Save Strategy

- Load subscription entitlements before sensitive section data.
- Load detailed section data when its section becomes active.
- Do not request payment credentials or premium configuration for a user who cannot access them.
- Cache already loaded section data during the session.
- Invalidate affected caches after a successful mutation.
- Use independent section save states.
- Disable save when no changes exist.
- Warn before leaving a section with unsaved changes.
- Keep errors local to the affected section.
- Preserve entered values after failed saves.

---

## 18. Translation and RTL

All new strings must exist in:

- English
- French
- Arabic

This includes:

- Section names
- Feature descriptions
- Plan names
- Lock messages
- Upgrade messages
- Subscription statuses
- Validation errors
- Read-only notices
- Downgrade notices
- Success messages

Requirements:

- Use immutable translation keys.
- Do not display raw enum names.
- Do not use translated labels in access checks.
- Use logical CSS properties.
- Support RTL modals, forms, navigation, icons, and status badges.
- Keep email addresses, domains, numbers, and currencies readable in Arabic.
- Locale switching must not change entitlements or section identifiers.

---

## 19. Accessibility

- Section navigation supports keyboard operation.
- The active section uses `aria-current`.
- Locked controls are not misleadingly focusable.
- Lock messages explain the reason in text.
- Status is not communicated through color alone.
- Save and validation results use appropriate live regions.
- Modals trap focus and return it to the trigger.
- Focus moves to the first invalid field after failed validation.
- Upgrade actions have descriptive accessible labels.

---

## 20. Testing Plan

## Entitlement unit tests

- Every feature has explicit plan assignments.
- Missing assignments deny access.
- Company overrides cannot grant a higher-plan feature.
- Role and subscription checks are both required.
- Trial access follows its assigned plan.
- Scheduled cancellation preserves access until period end.
- Downgrade preserves configuration but disables future premium behavior.

## API tests

- STARTER cannot mutate Growth or Pro features.
- GROWTH cannot enable Pro scheduled report delivery.
- PRO may use all approved features.
- Direct API calls cannot bypass the Dashboard lock.
- Premium pricing and insurance rules do not apply after entitlement loss.
- Historical reservation calculations remain unchanged.
- Secret payment values are never returned.

## Dashboard tests

- Settings remains visible for STARTER, GROWTH, and PRO.
- Company Profile works for every plan.
- Locked sections show the correct required plan.
- Sensitive forms are not rendered for unauthorized plans.
- Plan changes refresh feature access without a new login.
- One section saves without disabling unrelated sections.
- Mobile navigation remains usable.
- English, French, and Arabic render correctly.
- Arabic remains true RTL.

## Admin tests

- Plan assignments save correctly.
- Protected keys cannot be changed.
- Preview matches the Dashboard result.
- Global disable overrides plan assignment.
- Unauthorized administrators cannot modify entitlements.
- Changes create audit records.

---

## 21. Implementation Phases

## Phase 1: Freeze Menu Governance and Initial Assignments

- Approve the seven seeded settings items.
- Approve which menu fields the platform Admin may modify.
- Approve protected menu fields.
- Approve the initial entitlement matrix.
- Approve feature keys.
- Approve hidden-versus-locked behavior.
- Approve downgrade behavior.
- Approve subscription-status behavior.
- Approve owner and manager role behavior.

### Exit criteria

No unresolved menu ownership, protected-field, feature, downgrade, or plan-assignment decisions.

## Phase 2: Add Menu and Entitlement Data Models

- Create the protected settings menu catalog.
- Create menu-to-plan assignments.
- Create the feature catalog.
- Create explicit feature-to-plan assignments.
- Seed STARTER, GROWTH, and PRO access.
- Add translation records or localization bindings.
- Add publishing versions and audit support.
- Make migrations and seeds idempotent.

### Exit criteria

Every gated capability has an explicit assignment.

## Phase 3: Centralize Menu and Entitlement Resolution

- Extend the canonical entitlement resolver to support settings feature keys.
- Add the Admin-resolved settings-menu endpoint.
- Add the settings-entitlements endpoint.
- Resolve hidden, locked, read-only, and enabled states server-side.
- Add cache invalidation after Admin publish.
- Add subscription-status handling.

### Exit criteria

The API returns one authoritative feature-access result.

## Phase 4: Enforce Gated Operations

- Protect settings mutations.
- Protect pricing, insurance, payments, branding, and reporting behavior.
- Add consistent forbidden and upgrade-required errors.

### Exit criteria

No direct API call can use an unavailable capability.

## Phase 5: Reorganize the Dashboard Page

- Add section navigation.
- Split the monolithic page into section components.
- Add plan gates and locked states.
- Preserve existing API behavior for entitled features.
- Remove Domain and Publishing.

### Exit criteria

Only one focused section displays at a time, with correct plan behavior.

## Phase 6: Improve Section Workflows

- Add local save states.
- Add validation.
- Add image previews.
- Add insurance and pricing modals or side panels.
- Add readable summaries.
- Add downgrade and read-only notices.

### Exit criteria

Each section is understandable and independently usable.

## Phase 7: Admin Menu and Feature Controls

- Add the settings menu-management matrix.
- Add menu ordering, plan assignment, lock behavior, icon, and translation controls.
- Add the settings feature matrix.
- Add staged publishing and rollback.
- Add plan, role, and status previews.
- Add affected-company counts.
- Add audit history and protected controls.

### Exit criteria

Platform administrators can safely manage assignments.

## Phase 8: Localization, RTL, and Accessibility

- Complete EN, FR, and AR strings.
- Verify true RTL.
- Complete keyboard and screen-reader testing.

### Exit criteria

No missing translations or accessibility blockers.

## Phase 9: Automated Tests and Regression

- Run unit, integration, component, boundary, and E2E tests.
- Confirm existing settings data remains intact.
- Confirm downgrade and upgrade behavior.
- Confirm secret-handling requirements.

### Exit criteria

All entitlement and settings regression tests pass.

---

## 22. Acceptance Criteria

The plan is successfully implemented when:

1. Settings remains available to STARTER, GROWTH, and PRO through at least one required core item.
2. Domain and Publishing no longer appears.
3. Seven protected settings items are seeded initially.
4. The platform Admin can enable, disable, reorder, rename, describe, and assign those items to plans within approved limits.
5. Company owners, managers, and agents cannot modify the menu configuration.
6. Protected route keys and component keys cannot be changed through the Admin UI.
7. The Dashboard renders menu order and visibility from the published Admin configuration.
8. Only one main section displays at a time.
9. The active section is represented in the URL.
10. The URL accepts only protected section keys returned by the API.
11. Every gated capability uses an immutable feature key.
12. Plan assignments come from the API, not frontend plan-name checks.
13. Company Profile remains the required recovery fallback.
14. Locked items identify the required plan when Admin selected `LOCKED`.
15. Hidden items are absent when Admin selected `HIDDEN`.
16. Sensitive fields are not rendered for unavailable plans.
17. Direct API calls enforce the same entitlement rules.
18. Menu changes are staged and published atomically.
19. Every Admin menu change creates an audit record.
20. Admin previews match the resulting Dashboard menu.
21. Downgrades preserve data but stop future premium behavior.
22. Historical reservation and financial records remain unchanged.
23. Upgrades unlock retained configuration without a new login.
24. Subscription status affects editing consistently.
25. Role permissions remain separate from plan access.
26. Each section saves independently.
27. English, French, and Arabic menu content is complete.
28. Arabic uses true RTL.
29. Automated tests pass across Dashboard, API, Admin, and Database.
30. No code implementation begins until menu governance, the initial matrix, and downgrade rules are approved.

---

## 23. Out of Scope

This plan does not add:

- Domain or DNS management
- New payment providers
- New insurance calculation types
- New pricing conditions
- New accounting integrations
- New subscription plans
- Runtime machine translation
- Company-controlled menu customization
- Company-controlled entitlement upgrades
- Automatic deletion of downgraded configuration
- A redesign of the global dashboard sidebar

---

## 24. Execution Gate

Implementation must not begin until these are approved:

1. Admin menu ownership and editable-field policy
2. Initial menu-to-plan matrix
3. Feature entitlement matrix
4. Protected menu keys and feature keys
5. STARTER branding limits
6. GROWTH accounting limits
7. PRO scheduled-report behavior
8. Hidden-versus-locked policy
9. Downgrade effective date
10. Historical-record preservation rules
11. Subscription-status behavior
12. Role-access policy
13. Admin override policy
14. Admin publishing and rollback policy
