# 3.7.0

**Release Date:** June 5, 2026

---

## ✨ New Features

### NuGet Packages

#### Startup ActivitySource Tracing and EF Environment Handling 🔭

**Packages:** `SAIF.Platform`, `SAIF.Platform.Authentication`, `SAIF.Platform.Azure`, `SAIF.Platform.EntityFramework`, `SAIF.Platform.Kiota.HttpClientLibrary`

**Commit:** [`4f29a31d`](https://github.com/saif-corp/forge/commit/4f29a31d)

Adds startup `ActivitySource` tracing with XML documentation and environment handling updates for Entity Framework integration. Startup activities now carry configuration context visible in local trace tooling and OTLP-based APM dashboards. The `entityframework.is_development` tag has been replaced with `entityframework.environment` to report the exact environment value.

**Key Features:**

- ✅ **Startup ActivitySource** - Structured tracing for application startup phases
- ✅ **XML Documentation** - Comprehensive XML docs for public tracing APIs
- ✅ **EF Environment Tagging** - Reports exact environment value instead of boolean is_development flag

**Benefits:**

- 🔍 Better visibility into startup behavior via distributed tracing
- 📊 Accurate environment identification in Entity Framework telemetry
- 📖 Improved developer experience with IntelliSense documentation

---

### Project Templates

#### Mosaic Design System Integration 🎨

**Template:** `saif-api-exp`

**Commit:** [`0e813051`](https://github.com/saif-corp/forge/commit/0e813051)

Integrates the Mosaic design system into the Forge frontend React template, replacing the previous basic layout with Mosaic's navigation, theming, and component patterns. This brings the Golden Path frontend template in line with the organization's design system standards.

**Key Features:**

- ✅ **AppLayout with Mosaic** - Sidenav, header, breadcrumbs, and theming out of the box
- ✅ **Localization Infrastructure** - i18next with translation sync support
- ✅ **Error Handling** - Error page and route error handling built-in
- ✅ **Zero-Dependency Git Hooks** - Replaced husky with `.hooks/` directory
- ✅ **PowerShell Core Prepare Script** - Converted from vite-node to cross-platform PowerShell

**Usage:**

```bash
dotnet new saif-api-exp
```

**Benefits:**

- 🎨 Consistent look and feel with Mosaic design system across all new apps
- 🌐 Localization-ready from day one
- 🚀 Faster project bootstrap with pre-configured navigation and theming
- 🔧 Simplified Git hooks with no external dependencies

---

## 🔧 Enhancements

### NuGet Packages

#### Structured Token Error Telemetry in Kiota Providers 📊

**Package:** `SAIF.Platform.Kiota.HttpClientLibrary`

**Commit:** [`c61fb7df`](https://github.com/saif-corp/forge/commit/c61fb7df)

Replaces raw `SetStatus` calls with a structured `AddTokenError` Activity extension in both Kiota token providers. Token failures now emit filterable telemetry tags and structured events for improved APM observability in Dynatrace and other OTLP-compatible backends.

**Changes:**

- Added `ActivityExtensions.AddTokenError` shared extension method
- Records `ActivityEvent("authentication.token_error")` with structured tags
- Always emits `http.response.status_code` (including `0` for non-HTTP paths)
- Both providers now use null-safe `span?.AddTokenError(token, projectId)` invocation

**Example:**

```csharp
// Before — opaque free-text only
span?.SetStatus(ActivityStatusCode.Error, $"{token.ErrorType}: {token.ErrorDescription}");

// After — structured, filterable event + exception when present
if (token.IsError)
{
    span?.AddTokenError(token, projectId);
}
```

**Benefits:**

- 🔍 `error.type` separates protocol failures from exception-based failures
- 🏷️ `error.code` is filterable in Dynatrace (`invalid_client`, `access_denied`, etc.)
- 📊 `http.response.status_code` is always present for consistent querying
- 🎯 `authentication.project_id` enables per-project failure aggregation
- 🐛 Stack traces surfaced for exception-based errors

---

## 🐛 Bug Fixes

### Terraform Modules

#### Sanitize Deployed-By Tag for Dependabot Builds 🏷️

**Commit:** [`2bdd3ed3`](https://github.com/saif-corp/forge/commit/2bdd3ed3)

Sanitizes the `deployed_by` tag value to strip parentheses that appear in Dependabot build identities. Azure resource tags do not allow parentheses, causing deployment failures when Dependabot triggers infrastructure pipelines.

---

#### Remove Duplicate `<base />` from APIM Operation Policies 🔌

**Module:** `saif-apim`

**Commit:** [`fbc98e7c`](https://github.com/saif-corp/forge/commit/fbc98e7c)

Removes duplicate `<base />` elements from operation-level API Management policies. The duplication caused policy evaluation to run base policies twice, potentially leading to unexpected behavior in request/response processing.

---

#### Grant OTEL Header KV Secret Access to UAMI Instead of SP 🔒

**Module:** `saif-identity`

**Commit:** [`74d6a2b3`](https://github.com/saif-corp/forge/commit/74d6a2b3)

Fixes the Key Vault secret access role assignment for OTEL header configuration to target the User-Assigned Managed Identity (UAMI) instead of the Service Principal. This ensures the application runtime identity has proper access to retrieve OpenTelemetry ingestion headers.

---

## 📝 Documentation

### Auth Documentation Overhaul 📋

**Commit:** [`6d7135b7`](https://github.com/saif-corp/forge/commit/6d7135b7)

Audited and clarified authentication documentation to distinguish Entra ID and Okta scope and app role differences. Ensures teams understand which identity provider patterns apply to their deployment scenarios.

---

### Golden Path Homepage Elevation 🏠

**Commit:** [`f1253505`](https://github.com/saif-corp/forge/commit/f1253505)

Elevated the Golden Path on the Forge documentation homepage and reorganised contributing docs under the "About" section. Makes the recommended application development path more discoverable for new developers.

---

### Technology Vision North Star 🌟

**Commit:** [`aaf07199`](https://github.com/saif-corp/forge/commit/aaf07199)

Added a technology vision north star document outlining the platform's strategic direction and long-term architectural goals.

---

### Internal Documentation Link Migration 🔗

**Commit:** [`b7081f5a`](https://github.com/saif-corp/forge/commit/b7081f5a)

Replaced Azure DevOps wiki links with internal Forge documentation references, consolidating documentation discoverability within the Forge docs site.

---

### Guided "Build on Your App" Path 🛤️

**Commit:** [`692a0b3b`](https://github.com/saif-corp/forge/commit/692a0b3b)

Added a guided "Build on Your App" tutorial path after the first application tutorial, helping developers transition from the initial Golden Path walkthrough to customising their own applications.

---

## 🔄 Breaking Changes

None in this release ✅

---

## 📋 Additional Notes

- Total commits: 26
- Files changed: 1,320
- Contributors: Emmitt Johnson, Gabe Higginbotham, Copilot

---

### Support

- 📧 Teams Support Channel: [Support](https://teams.microsoft.com/l/channel/19%3Acb611810fb0b42b080cfff5590bdd51c%40thread.tacv2/Support?groupId=514d2dac-2d62-48ce-bf99-0fa0ce39469c&tenantId=a86cb8ed-369b-4df5-ace5-43811f6e08cf)

---