# Operator UX & Surface Standards

> **Status:** Active  
> **Last reviewed:** 2026-04-30  
> **Use for:** Audience, language, disclosure, and operator-surface rules for product UX  
> **Do not use for:** Treating internal implementation structure as product IA or redefining constitution terms locally

This document defines the binding audience-and-surface contract for TenantPilot.

It establishes:

- who each product surface is primarily built for
- what type of language is allowed on that surface
- how technical detail must be progressively disclosed
- how operator-facing pages must communicate status, scope, and actions

This document is normative for new operator-facing UI work and for major UI refactors.

It follows the constitution vocabulary for `Native Surface`, `Custom Surface`,
`Shared Detail Micro-UI`, and shell/page/detail state ownership. This
document complements the constitution and MUST NOT be used as a parallel
rulebook that redefines those terms.

## 1. Purpose

TenantPilot is not a generic admin UI. It is an enterprise operator product for managed Microsoft tenant governance, backup, restore, monitoring, drift detection, and review workflows.

The product must not expose internal implementation structure as if it were product UX.

The default experience must be optimized for the primary working audience.
Technical truth may remain available, but it must be progressively disclosed.

## 2. Product Audience Model

TenantPilot serves four distinct audiences. Every page must have exactly one primary audience.

### 2.1 Primary Persona: Operator / Engineer

Focus:

- day-to-day execution
- monitoring
- triage
- safe action-taking

Typical tasks:

- onboarding tenants
- configuring providers
- running syncs
- reviewing inventory state
- running backup / restore workflows
- baseline capture / compare
- findings triage
- exceptions / risk acceptance
- operations monitoring

UI requirements:

- clear operator language
- strong scanability
- explicit scope
- safe defaults
- actionable next steps
- minimal ambiguity
- no unnecessary internal field leakage

### 2.2 Secondary Persona: Senior Engineer / Troubleshooter

Focus:

- diagnosis
- validation
- escalation handling
- deep technical analysis

Typical needs:

- raw payloads
- provider error details
- UUIDs / external IDs
- technical context
- low-level diagnostic traces

UI requirements:

- access to raw truth
- no removal of diagnostic power
- diagnostics available on-demand, never as default-visible content

### 2.3 Tertiary Persona: Service Manager / CISO / Customer Reviewer

Focus:

- proof
- reporting
- trends
- governance posture
- SLA / audit communication

Typical needs:

- dashboards
- summaries
- evidence-backed reporting
- accepted risks
- review readiness
- exported review packs

UI requirements:

- aggregated, outcome-oriented surfaces
- low operational noise
- no dependence on operator-level detail pages

### 2.4 Platform Persona: Platform Admin / System Operator

Focus:

- platform administration
- internal platform management
- break-glass operations
- platform-wide controls

Typical surface:

- `/system`

UI requirements:

- technically capable
- administratively precise
- still intentionally designed
- not a dumping ground for unresolved `/admin` UX

## 3. Surface Ownership by Persona

### 3.1 `/admin` operator surfaces

`/admin` is operator-first.

This includes:

- onboarding
- integrations used for tenant operations
- tenant management
- inventory
- policy views
- baselines
- findings
- evidence
- monitoring / operations
- backup / restore
- governance actions

Default-visible UX on these surfaces must be optimized for the Operator / Engineer persona.

### 3.2 `/admin` diagnostics surfaces

Diagnostics within `/admin` belong to the Senior Engineer / Troubleshooter persona.

They are:

- available where appropriate
- secondary
- collapsed, tabbed, or otherwise intentionally disclosed
- never the primary content hierarchy

### 3.3 Reporting / review surfaces

Reports, review packs, customer read-only views, and similar proof-oriented surfaces are optimized for the Service Manager / CISO / Customer Reviewer persona.

These surfaces prioritize:

- summary
- evidence-backed conclusions
- trends
- risk posture
- review readiness

### 3.4 `/system` platform surfaces

`/system` is reserved for platform-only administration.

Rules:

- `/system` may expose more technical administrative detail than `/admin`
- `/system` must not be used to avoid fixing weak operator UX in `/admin`
- product operator workflows belong in `/admin`, not `/system`

## 4. Default vs Diagnostics Rule

### Gold rule

**Default = Operator Language**
**Expanded = Diagnostic Truth**

### 4.1 Default-visible content must avoid:

- raw JSON blobs
- raw internal field names
- raw DB timestamps without product meaning
- raw enum / reason codes
- raw provider error bodies unless translated
- UUIDs or IDs as primary visual content
- implementation-specific field semantics

### 4.2 Diagnostics content may include:

- raw JSON
- provider error details
- raw IDs / UUIDs
- internal field values
- stacktrace-adjacent diagnostic summaries
- payload sizes
- created_at / updated_at / internal audit metadata where relevant

### 4.3 Diagnostics placement

Diagnostics must be secondary and intentionally placed, for example:

- collapsed diagnostics section
- dedicated diagnostics tab
- advanced technical panel
- expandable system detail area

Diagnostics must not dominate the primary page hierarchy.

## 5. Operator-Language Glossary

Internal or technical terminology must not appear in operator-facing default surfaces without translation.

| Internal / Technical Term | Operator-Facing UI Term | Notes |
|---|---|---|
| `dry_run`, `is_dry_run` | Simulation Mode / Simulate Only | Indicates no live Microsoft mutation |
| `metadata_only` | Incomplete Capture / Configuration Unavailable | Use based on context |
| `reason_code` | Blocked Reason / Failure Reason | Humanized mapping required |
| `provider_consent_missing` | Missing Admin Consent | Example translated reason |
| `scope_jsonb.policy_types` | Included Policy Types | Never expose DB path syntax |
| `scope_jsonb.foundation_types` | Included Foundation Types | Never expose DB path syntax |
| `evidenceGaps` | Missing Inventory Data / Incomplete Sync Data | Use operator meaning |
| `fidelity` | Match Confidence | Only show if actionable |
| `role_definition_id` | Assigned Role | Prefer display name over raw ID |

This glossary should expand over time and be treated as a product vocabulary source of truth.

## 6. Status Taxonomy

UI surfaces must not collapse all state into one ambiguous status.

TenantPilot must distinguish at least four status dimensions where relevant.

### 6.1 Execution Outcome

Question:

- Did the operation execute successfully?

Examples:

- Queued
- Running
- Succeeded
- Blocked
- Failed
- Cancelled

### 6.2 Data Completeness

Question:

- Do we have the full data required for reliable interpretation?

Examples:

- Complete
- Incomplete
- Stale
- Unavailable

### 6.3 Governance Result

Question:

- Is the tenant or object aligned with expected governance state?

Examples:

- Aligned
- Drift Detected
- Exception Applied
- Risk Accepted
- Review Needed

### 6.4 Lifecycle / Readiness State

Question:

- What lifecycle or publication state is the object in?

Examples:

- Draft
- Active
- Archived
- Review Ready
- Published
- Expired

These dimensions must remain semantically distinct in labels, badges, summaries, and workflows.

## 7. Mutation Scope Rule

Every action that changes state must communicate its mutation scope before execution.

Allowed mutation-scope categories:

- **TenantPilot only**
- **Microsoft tenant**
- **Simulation only**

Examples:

- Archive local record -> TenantPilot only
- Restore configuration to Intune -> Microsoft tenant
- Dry-run / simulation -> Simulation only

This must be understandable from the action label, preview, confirmation step, or surrounding UI copy.

## 8. Canonical Detail-Page Layout

Every operator-facing detail page should follow this hierarchy unless there is a strong documented reason not to.

### 8.1 Header

Must show:

- object identity
- subtle identifier if needed
- 1-2 primary status indicators

### 8.2 Action Bar

Rules:

- maximum 2 primary actions
- destructive or uncommon actions belong in a secondary group
- action labels must reflect real outcome and mutation scope

### 8.3 Summary / Health

Top-of-page summary should answer the primary operator question quickly.

Typical examples:

- last sync / last run
- completeness state
- governance state
- current baseline / current assignment
- current blocked reason
- recommended next step

### 8.4 Primary Content

This is the main working surface:

- related records
- findings
- relations
- scoped data
- actionable tables
- interpreted content

### 8.5 Diagnostics

Diagnostics belong at the bottom or in a secondary surface:

- raw JSON
- raw IDs
- payloads
- internal timestamps
- provider response detail

## 9. Safe Execution Standard

Actions with meaningful blast radius must follow a consistent pattern.

### Required sequence

1. Configuration
2. Safety checks / simulation
3. Preview
4. Hard confirmation where required
5. Execute

### Applies to:

- restore
- baseline enforce
- high-impact bulk actions
- delete actions with tenant impact
- tenant-wide mutation flows

### Rules

- no dangerous one-click actions for high-blast-radius operations
- confirmation language must match actual action semantics
- preview must clearly indicate mutation scope

## 10. Workspace vs Tenant Context Rules

Operators must never have to infer scope from memory.

### 10.1 Tenant-scoped surfaces

If the operator is inside a tenant surface:

- actions must be tenant-safe
- workspace-wide actions must not silently appear
- `show all tenants` or similar context escapes must not behave like normal in-flow actions

### 10.2 Workspace-scoped surfaces

Workspace surfaces may aggregate:

- dashboards
- review views
- multi-tenant monitoring
- fleet-level rollouts
- cross-tenant summaries

But they must still communicate that they are workspace-level, not tenant-level.

### 10.3 Context clarity requirements

Every page must make clear:

- current scope
- object scope
- whether actions are local or cross-scope
- whether current data is tenant-specific or workspace-aggregated

## 11. Page Contract Requirement

Every new or materially refactored page must define the following before implementation:

- primary persona
- surface type
- primary operator question
- default-visible information
- diagnostics-only information
- status dimensions used
- mutation scope
- primary actions
- dangerous actions

A page that cannot answer these questions is not ready for implementation.

## 12. Surface Types

Recommended surface categories:

- operator execution surface
- operator monitoring surface
- diagnostic detail surface
- reporting / review surface
- customer read-only surface
- platform admin surface

These categories help determine hierarchy, language, action model, and diagnostics visibility.

## 13. What Good Looks Like

A strong operator-facing page lets the primary persona understand within a few seconds:

- what this page represents
- what scope they are in
- whether something is healthy, blocked, incomplete, or risky
- what they should do next
- whether any action changes TenantPilot only, Microsoft tenant state, or nothing live

A strong diagnostics surface lets the troubleshooting persona access raw truth quickly without polluting the primary operator experience.

A strong reporting surface avoids operational noise and emphasizes proof, posture, and readiness.

## 14. Adoption Rules

This document applies to:

- new operator-facing resources
- new dashboards and detail pages
- new action-heavy flows
- major refactors of existing surfaces
- new specs that materially affect operator UX

Specs should explicitly reference this document where relevant.
Operational authoring and review workflow lives in `.specify/templates/spec-template.md`,
`.specify/templates/plan-template.md`, `.specify/templates/tasks-template.md`,
`.specify/templates/checklist-template.md`, and `.specify/README.md`.
This document remains the rule and reference layer, not a second checklist
or close-out workflow.

Recommended spec fields:

- primary persona
- surface type
- diagnostics boundary
- status taxonomy used
- mutation scope
- action safety model

## 15. Non-Goals

This document does not define:

- color palette
- visual branding
- CSS-level implementation details
- pixel-level layout choices
- complete component library design

This document is about audience, semantics, surface structure, diagnostics boundaries, and safe operator UX.

## 16. Summary

TenantPilot must behave like a product, not a raw schema browser.

That means:

- operator-first default surfaces
- diagnostics available, but secondary
- distinct status dimensions
- explicit mutation scope
- safe execution for dangerous actions
- explicit workspace / tenant context
- page-level audience and surface contracts
