Example: API client package packaging¶

package.md records how a client package is built, what it contains, and where it is published. Doc gen produces one per client at docs/clients/<client-slug>/package.md.

What reviewers should check¶

The nuspec named in ## Identity is a real packaging manifest with a literal <id>, not a Visual Studio project template full of $id$ / $version$ tokens and an empty <files/>. The manifest often lives under scripts\, not beside the project.
## Manifest selection states which candidate was chosen and why. When a token template exists alongside the real manifest, both are listed; when only a token template exists, the page says the package id is an assembly-name fallback and raises it as tech debt.
No MSBuild token survives into a value cell. $version$ printed as the version is the defect this section exists to catch.
## Dependencies leads with SAIF.Framework.Common and SAIF.Web.API.Clients, then names any package-specific dependency — a third dependency is a real finding, not filler.
## Shipped content reproduces the nuspec <files> element exactly. Rows for symbols or a contracts assembly appear only when that nuspec declares them, and a package that ships src\**\*.cs carries the source-shipping callout.
## Feed and the publish trigger are either evidenced by a pipeline, script, or config, or recorded as "Not determined from source". An inferred feed name is a defect.

Example¶

The document below is a complete, correct client-package.md for a fictional API client package.

View rendered example — the same document as a real page, so you can compare rendering as well as source.

---
title: Package
summary: nuspec identity, version, dependencies, shipped content, feed, and build pipeline.
status: draft
owner: Agency Systems Team
last_reviewed: 2026-09-10
---

# Package

`SAIF.Agency.Api.Client` is packed by the `agency-client-build` pipeline from
the packaging manifest under `scripts\`, versioned 3.2.0, and published to the
internal `SAIF-Packages` Azure Artifacts feed on merge to `main`. The package
targets `lib\net48` and ships the compiled client, its debug symbols, the shared
`SAIF.Agency.Api.Core` contracts assembly, and the complete C# source of both
projects.

## Identity

| Field | Value |
| --- | --- |
| Package id | `SAIF.Agency.Api.Client` |
| Version | `3.2.0` |
| Authors | `SAIF Corporation` |
| Owners | `Agency Systems Team` |
| Description | Strongly typed .NET Framework 4.8 client for the SAIF Agency API (`v1/agencies`), including the shared `SAIF.Agency.Api.Core` contracts. |
| Requires license acceptance | false |
| nuspec file | `scripts\SAIF.Agency.Api.Client\SAIF.Agency.Api.Client.nuspec` |
| Project file | `src\SAIF.Agency.Api.Client\SAIF.Agency.Api.Client.csproj` |

## Manifest selection

| Candidate nuspec | Kind | Selected | Reason |
| --- | --- | --- | --- |
| `scripts\SAIF.Agency.Api.Client\SAIF.Agency.Api.Client.nuspec` | Packaging manifest | Yes | Literal `<id>SAIF.Agency.Api.Client</id>` and a populated `<files>` element |
| `src\SAIF.Agency.Api.Client\SAIF.Agency.Api.Client.nuspec` | Token template | No | MSBuild tokens (`$id$`, `$version$`, `$author$`, `$description$`) with an empty `<files/>` |

Two nuspec files exist in this repository. The one beside the project is the
Visual Studio project template that `nuget spec` generates; it is not referenced
by any pipeline and its tokens are never substituted. The manifest that ships is
the one under `scripts\`, which the `build-steps-nuget.yml` template packs with
`-Version $(PackageVersion)`. The identity values above are read from that file,
not from the template and not from the assembly name.

## Dependencies

Every surveyed client nuspec declares `SAIF.Framework.Common` and `SAIF.Web.API.Clients`. List them first, then any package-specific dependency.

| Dependency | Version | Purpose |
| --- | --- | --- |
| `SAIF.Framework.Common` | 5.4.0 | Shared framework types |
| `SAIF.Web.API.Clients` | 4.1.2 | `JsonHttpClient` and `ClientInfo` transport surface |
| `Newtonsoft.Json` | 13.0.3 | JSON serialization of `AgencyContactUpdate` request bodies and deserialization of `SAIF.Agency.Api.Core` DTOs |

`Newtonsoft.Json` is declared directly rather than inherited transitively, which
pins every consumer of this package to 13.0.3 or higher. Two consumers
(`SAIF.Claims.Intake` and `SAIF.Policy.RenewalNotice`) already reference
`Newtonsoft.Json` themselves, so the pin is a real constraint on their upgrade
path and not merely a transitive detail.

See [Dependencies](dependencies.md) for the full dependency landscape including transitive and build-time references.

## Shipped content

> **This package ships source alongside the compiled assembly.** In addition to
> `lib\net48\*.dll`, the nuspec `<files>` element maps `src\**\*.cs` targets, so the complete
> C# source of the client and its contracts assembly is installed into every consuming project.
> This is unusual and has consequences: consumers can read and copy internal implementation,
> the shipped source can drift from the shipped binary, and any credential, internal URL, or
> comment in the source is distributed with the package. Do not describe this as routine
> packaging — record it here and evaluate it as a finding in [Tech debt](tech-debt.md).

| Source | Target | Content |
| --- | --- | --- |
| `..\..\src\SAIF.Agency.Api.Client\bin\release\SAIF.Agency.Api.Client.dll` | `lib\net48\SAIF.Agency.Api.Client.dll` | Compiled client |
| `..\..\src\SAIF.Agency.Api.Client\bin\release\SAIF.Agency.Api.Client.pdb` | `lib\net48\SAIF.Agency.Api.Client.pdb` | Debug symbols |
| `..\..\src\SAIF.Agency.Api.Core\bin\release\SAIF.Agency.Api.Core.dll` | `lib\net48\SAIF.Agency.Api.Core.dll` | Shared contracts assembly |
| `..\..\src\SAIF.Agency.Api.Client\**\*.cs` | `src\SAIF.Agency.Api.Client` | **Client source code** |
| `..\..\src\SAIF.Agency.Api.Core\**\*.cs` | `src\SAIF.Agency.Api.Core` | **Contracts source code** |

The `src\**\*.cs` mappings include `AgencyClient.cs`, which contains the default
internal base URL used by the client's integration tests. That constant is
distributed to every consumer as readable source.

## Build and release pipeline

| Attribute | Value |
| --- | --- |
| `AppType` | `nuget` |
| `AppName` | `agency-api-client` |
| `SolutionPath` | `SAIF.Agency.Api.sln` |
| `ProjectPath` | `src\SAIF.Agency.Api.Client\SAIF.Agency.Api.Client.csproj` |
| `BuildConfiguration` | release |
| `IncludeReferencedProjects` | true |
| Build pipeline | `Pipelines/agency-client-build.yml` |
| Build variables | `Pipelines/agency-client-build-vars.yml` |
| Release pipeline | `Pipelines/agency-client-release.yml` |

### Pipeline templates

| Stage | Template | Purpose |
| --- | --- | --- |
| Build | `Steps/build-steps-nuget.yml@templates` | Restore, build, and pack the package |
| Build | `Steps/build-version-dat.yml@templates` | Version stamping for `AppType: nuget` |
| Release | `/Stages/deploy-stages-nuget.yml@templates` | Publishes the package to the SAIF NuGet feed |

`IncludeReferencedProjects: true` is why `SAIF.Agency.Api.Core.dll` appears in
`lib\net48` without a separate package: the contracts assembly is a project
reference, so pack folds it into this package instead of declaring a dependency
on it.

### Artifacts

| Artifact | Variable | Notes |
| --- | --- | --- |
| Pre-release | `ArtifactNamePreRelease` = `alpha` | Branch builds pack `3.2.0-alpha.<build>` |
| Release | `ArtifactNameRelease` = `release` | — |

## Feed

| Field | Value |
| --- | --- |
| Feed | `SAIF-Packages` (Azure Artifacts), named in `Pipelines/agency-client-release.yml` |
| Publish trigger | On merge to `main`; the release stage has no manual approval gate |

## Related documentation
- [Client index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Client reference](reference.md)
- [Endpoint map](endpoint-map.md)
- [Consumption](consumption.md)
- [Contracts](contracts.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Tech debt](tech-debt.md)

## Sources
- `scripts/SAIF.Agency.Api.Client/SAIF.Agency.Api.Client.nuspec`
- `src/SAIF.Agency.Api.Client/SAIF.Agency.Api.Client.nuspec`
- `src/SAIF.Agency.Api.Client/SAIF.Agency.Api.Client.csproj`
- `Pipelines/agency-client-build.yml`
- `Pipelines/agency-client-build-vars.yml`
- `Pipelines/agency-client-release.yml`