# Plan: Settings Integrity and Controls Reorganization

## Objective
Create a single coherent configuration model for Security, Commands, and Tasks so UI labels, enforcement behavior, docs, and navigation all match actual runtime behavior.

## Current Integrity Findings

### 1) Scope Registry and Enforcement Are Out of Sync
- Gateway command routes enforce scopes that are not exposed in Fine-Grained Security Scopes:
  - `gateway.contacts`
  - `gateway.help`
  - `gateway.whoami`
- Fine-Grained Security Scopes currently expose only:
  - `gateway.tasks`, `gateway.approval`, `tasks.submit`, `tasks.commands`, `command.bp`, `command.codex`, `command.claude`
- Result: users cannot configure all enforced gateway capabilities from the UI.

### 2) “Require Trusted Fingerprint” Semantics Are Incorrect
- UI and labels imply trust-list based enforcement.
- Runtime policy enforcement checks `UserXmppOmemoState.latest_client_key` equality, not `UserXmppOmemoTrustedKey` trust records.
- Result: behavior is “match latest observed key,” not “require trusted fingerprint.”

### 3) Command Surfaces Are Split Across Inconsistent Places
- Command Routing UI create flow exposes command slugs: `bp`, `codex`.
- Runtime command engine auto-bootstraps `claude` profile and bindings.
- Security scopes include `command.claude`, but Command Routing create UI does not.
- Result: commands are partially configurable depending on entrypoint.

### 4) Task and Command Control Planes Interlock Implicitly, Not Explicitly
- Task settings contain provider approval routing (Codex/Claude approver service/identifier).
- Security permissions contain policy gates (`tasks.*`, `command.*`, `gateway.*`).
- Command Routing controls profile/binding/variant policy.
- These are tightly coupled but not represented as one layered model in UI/docs.

### 5) Settings Shell Coverage Is Incomplete
- Shared settings hierarchy nav is context-processor driven and route-name based.
- Settings routes missing from modules/general/security group coverage include:
  - `codex_settings`
  - `codex_approval`
  - `translation_preview`
- Result: some settings pages can miss expected local tabs/title context.

### 6) Documentation Drift
- Undocumented or under-documented features now in production behavior:
  - Fine-Grained Security Scopes + Global Scope Override
  - OMEMO trust management and per-direction encryption toggles
  - Business Plan Inbox under Settings Modules
- Potentially misleading documentation:
  - Security wording implies trusted-key enforcement that is not implemented.

## Reorganization Principles
1. One capability registry, reused by:
   - Security Permissions UI
   - command/task/gateway dispatch
   - documentation generation
2. One settings-shell contract for every `/settings/*` page:
   - title
   - category tabs
   - breadcrumb
3. Explicit layered model:
   - Layer A: transport encryption/security
   - Layer B: capability permissions (scope policy)
   - Layer C: feature configuration (tasks/commands/providers)
4. No hardcoded duplicated scope lists in multiple files.

## Target Information Architecture

### Security
- `Encryption`: OMEMO transport controls + trust management.
- `Permissions`: Fine-Grained Security Scopes (capability policy only).
- `2FA`: account factor settings.

### Modules
- `Commands`: command profiles, bindings, variant policies.
- `Tasks`: extraction/defaults/overrides/provider pipelines.
- `Translation`: translation bridge settings.
- `Availability`: adapter availability controls.
- `Business Plans`: inbox/editor for generated artifacts.

### General
- `Notifications`
- `System`
- `Accessibility`

### AI
- `Models`
- `Traces`

## Phased Execution Plan

## Phase 1: Canonical Capability Registry
1. Add a central capability registry module (single source of truth):
   - key
   - label
   - description
   - group (`gateway`, `tasks`, `commands`, `agentic`, etc.)
   - owning feature page URL
2. Migrate SecurityPage scope rendering to this registry.
3. Migrate gateway/command/task dispatchers to reference registry keys.
4. Add automated integrity test:
   - every enforced scope key must exist in registry
   - every registry key marked user-configurable must appear in Permissions UI

## Phase 2: Trusted Key Enforcement Correction
1. Define authoritative trust policy behavior:
   - `require_trusted_fingerprint` must validate against `UserXmppOmemoTrustedKey`.
2. Preserve backwards compatibility via migration path:
   - existing latest-key behavior can be temporarily represented as an optional fallback mode.
3. Update labels/help to match exact behavior.
4. Add tests:
   - trusted key allows
   - untrusted key denies
   - unknown key denies

## Phase 3: Commands/Tasks Control Plane Alignment
1. Unify command surface definitions:
   - Command Routing create/edit options include all supported command slugs (`bp`, `codex`, `claude`).
2. Add explicit cross-links:
   - Tasks settings references Command Routing and Permissions scopes directly.
   - Command Routing references Permissions scopes affecting each profile.
3. Introduce capability-impact preview panel:
   - for each command/task action, show effective allow/deny by scope and channel.

## Phase 4: Settings Shell Normalization
1. Replace route-name allowlists in `settings_hierarchy_nav` with category mapping table.
2. Ensure all `/settings/*` pages declare category + tab metadata.
3. Include missing routes (`codex_settings`, `codex_approval`, `translation_preview`) in shell.
4. Add test to fail when a `/settings/*` route lacks shell metadata.

## Phase 5: Documentation Synchronization
1. Add a settings matrix doc generated (or validated) from the capability registry:
   - capability key
   - UI location
   - enforced by code path
2. Update `README.md` and `INSTALL.md` security/modules sections.
3. Add "policy semantics" section clarifying:
   - encryption-required vs per-scope OMEMO requirements
   - trusted key behavior
   - global override precedence

## Acceptance Criteria
- Every enforced scope is user-visible/configurable (or intentionally internal and documented).
- “Require Trusted Fingerprint” enforcement uses trust records, not only latest observed key.
- Command Routing and runtime-supported command slugs are aligned.
- All `/settings/*` pages show consistent settings shell navigation.
- Security/tasks/commands docs reflect real behavior and pass integrity checks.

## Risks and Mitigations
- Risk: policy behavior change blocks existing workflows.
  - Mitigation: add compatibility flag and staged rollout.
- Risk: registry migration introduces missing scope mappings.
  - Mitigation: integrity test that compares runtime-enforced keys vs registry.
- Risk: UI complexity increase.
  - Mitigation: keep layered model with concise, context-aware summaries.

## Implementation Notes
- Keep migration incremental; avoid big-bang rewrite.
- Prioritize Phase 1 + Phase 2 first, because they are correctness and security semantics issues.
- Do not add new transport-specific branches; keep service-agnostic evaluation path in policy engine.