# Copy And Terminology Rules

Verification level: derived from existing implementation using existing repo vocabulary, constitution provider-boundary rules, and Spec 368 findings.

## Default Voice

- Lead with what the state means.
- Use action-oriented copy.
- Prefer stable platform nouns.
- Avoid implementation-first language in primary UI copy.
- Use technical words only where the audience and surface type require them.

## Preferred Platform Terms

- Workspace
- Managed Environment
- Provider Connection
- Governed Subject
- Operation
- Evidence
- Review
- Finding
- Governance
- Diagnostics

## Provider-Specific Terms

Provider-specific terms are allowed when the surface is provider-owned or diagnostic, or when the term names an external product reality the operator must understand.

Provider-specific terms should not become platform-core labels for generic surfaces.

Examples to demote on non-diagnostic surfaces:

- raw Graph payload
- tenant ID
- workspace ID
- managed environment ID
- API object ID
- normalization lineage
- provider response body

## Status / Reason / Impact / Action Copy

Good structure:

- Status: current state.
- Reason: why this is the state.
- Impact: why it matters.
- Primary action: what the user should do next.

Avoid:

- "Healthy" without explaining why that matters.
- "Pending" without owner or next action.
- "Failed" without likely cause or next check.
- "View details" as the only action when a clearer action exists.

## Customer-Safe Copy

Customer/auditor surfaces should use:

- outcome
- evidence basis
- limitation
- accepted risk
- review pack
- exported report
- next review or handoff action

They should avoid by default:

- internal run IDs
- raw provider IDs
- fingerprints
- debug labels
- internal reason families
- stack traces
- raw JSON

## Action Labels

Use `Verb + Object` where possible.

Examples:

- Review findings
- Open evidence
- Download review pack
- Start restore preview
- Open diagnostics
- Check permissions

Avoid primary labels that are only scope terms:

- Workspace
- Tenant
- Environment

Use scope words as secondary context unless the object being acted on is truly the scope.