# Nexamas UI Documentation Policy

## Purpose

Nexamas UI documentation is a product and adoption asset. It must be trustworthy for three audiences:

1. customers evaluating a subscription or commercial use,
2. companies evaluating platform adoption,
3. developers consuming the official SDK surface.

## Non-negotiable rules

- No documented feature without Nexamas UI source-code or package evidence.
- No Showcase-derived claims. Showcase pages may demonstrate a feature, but they do not define the feature.
- No internal or `Friend` type is documented as public consumer API.
- No commercial claim is stronger than the evidence in `_inventory/claim-ledger.md`.
- If a feature is present but not public, document it as internal platform infrastructure, not as a consumer API.
- If a capability exists but is intentionally unavailable, document it honestly as unavailable or guarded.
- Public examples must use official entry points only.

## Status labels

- `Verified` — the claim has direct source/package evidence.
- `Public Consumer Surface` — public API intended for external consumer use.
- `Application-Owned Facade` — public use is routed through `Nexamas.UI.Application` rather than direct subsystem construction.
- `Friend/Internal` — exists in Nexamas UI but is not consumer-facing.
- `Preview/Needs Review` — visible in source but not yet safe to document as stable.
- `Not Documented` — intentionally excluded from consumer/product docs.

## Update rule

When code changes, update inventories first, then update prose. Product pages must never drift ahead of the evidence ledger.

## Closure gate

The final user-documentation closure gate is:

```text
tools/docs/Verify-NexamasUIDocumentationClosure.py
```

It fails on public API hash/count drift, project/source misalignment, unresolved mismatch or coverage rows, invalid durable Windows proof, non-Build-verified governed recipes, broken links/anchors, or failed documentation source validators.

A public API change is not complete until the assembly inventory, contextual documentation, recipe proof where applicable, and closure report all agree.


## Binary drift rule

A release build must pass `tools/docs/Invoke-NexamasUIPublicApiDrift.ps1`. The checked-in documentation inventory and baseline never replace inspection of the newly built `Nexamas.UI.dll`. An unexplained API hash, type/member count, source-alignment, or assembly-freshness change blocks documentation closure.