# Maintaining Nexamas UI Documentation

Nexamas UI documentation is code-first. When changing source, package contracts, public APIs, or quality assets, update the documentation evidence before updating product/commercial prose.

## Required workflow

Use this order:

```text
1. Read the source/package/quality asset.
2. Update or add an inventory entry.
3. Update `_inventory/claim-ledger.md` when the change affects a customer-facing claim.
4. Update product/adoption/reference/developer/commercial pages.
5. Run the static documentation gate.
6. Run the six-stage closure gate.
7. When recipes or public usage change, rebuild the recipe hosts on Windows.
```

## Adding a new feature claim

Do not add a sentence such as:

```text
Nexamas UI supports X.
```

unless `X` is backed by one of:

- source code evidence;
- project/package evidence;
- public API evidence;
- quality/proof asset evidence;
- an explicit inventory page created from source inspection.

Then add a claim row in:

```text
docs/_inventory/claim-ledger.md
```

## Stable, Preview, Internal, NotAvailable

Use these terms carefully:

- `Stable` — public/consumer-facing and intended to be depended on.
- `Preview` — present but still subject to change.
- `Internal` — present in source but not a consumer contract.
- `NotAvailable` — explicitly not available in this snapshot.

Do not document `Friend` implementation details as customer APIs.

## Documentation files and `.vbproj`

Documentation files must not be compiled. They should not appear as `<Compile>` entries.

Acceptable options:

- leave them only in source control;
- include selected docs as `<None>` items if Visual Studio visibility is desired;
- include selected release docs through `.nuspec` if the package should carry them.

The documentation gate checks that documentation files are not compiled as VB source.

## Running the documentation gate

From the repository root:

```powershell
pwsh -File .\tools\docs\Invoke-NexamasUIDocumentationGate.ps1
```

For release checks:

```powershell
pwsh -File .\tools\docs\Invoke-NexamasUIDocumentationGate.ps1 -Strict
```

## Running the final closure gate

Cross-platform static closure:

```powershell
python .\tools\docs\Verify-NexamasUIDocumentationClosure.py --write
```

Windows orchestration with recipe compilation:

```powershell
.\tools\docs\Invoke-NexamasUIDocumentationClosure.ps1 -BuildRecipes
```

Full Windows runtime and snapshot reproduction:

```powershell
.\tools\docs\Invoke-NexamasUIDocumentationClosure.ps1 -RunRecipeSmokes -RunSnapshotSmoke
```


## Recheck the freshly built assembly

A documentation-only check cannot detect a new binary surface by itself. After building `Release|x64`, run:

```powershell
.\tools\docs\Invoke-NexamasUIPublicApiDrift.ps1 -Configuration Release -Platform x64
```

Do not update `eng/tests/Nexamas.UI.DocumentationClosureBaseline.json` merely to make this gate pass. An intentional API change first requires regenerated API inventories, updated user documentation and recipes, review of the changed surface, and a fresh Windows proof.