feat: add report-audit-token-usage MCP tool

.nvmrc

@@ -1 +1 @@
-22.14.0
+24.14.1

docs/architecture-internal-design.md

@@ -110,7 +110,7 @@ These options control how design tokens are discovered, organised, and categoris
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `ds.tokens.filePattern` | string | `**/semantic.css` | Glob pattern to discover token files inside `generatedStylesRoot`. |
-| `ds.tokens.propertyPrefix` | string \| null | `null` | When set, only properties starting with this prefix are loaded. |
+| `ds.tokens.propertyPrefix` | string \| null | `null` | When set, only properties starting with this prefix are loaded into the token dataset. **Note**: setting this to a single prefix (e.g. `--semantic-`) means the `report-audit-token-usage` tool will only validate and detect overrides for tokens matching that prefix. Leave as `null` to load all tokens and let the tool derive all prefixes automatically (e.g. `--semantic-` and `--ds-`). |
 | `ds.tokens.scopeStrategy` | enum | `flat` | `flat` or `brand-theme`. Controls how directory structure maps to token scope metadata. `flat`: no scope. `brand-theme`: path segments → brand/theme scope keys. |
 | `ds.tokens.categoryInference` | enum | `by-prefix` | `by-prefix`, `by-value`, or `none`. Controls how tokens are assigned categories. |
 | `ds.tokens.categoryPrefixMap` | Record | `{ color: '--semantic-color', ... }` | Category → prefix mapping (used with `by-prefix`). |

docs/tools.md

@@ -33,6 +33,26 @@ This document provides comprehensive guidance for AI agents working with Angular
 - With `saveAsFile: true`: File path and statistics (components, files, lines)
 **Best Practice**: Use `saveAsFile: true` to persist results for grouping workflows or large-scale migration planning. The saved file can be used as input for work distribution grouping tools.
 
+#### `report-audit-token-usage`
+**Purpose**: Audits design token usage in style files — validates `var()` references for typos and detects token overrides
+**AI Usage**: Use to identify invalid token references (with suggestions) and find places where tokens are being overridden instead of consumed
+**Key Parameters**:
+- `directory`: Target directory to scan
+- `modes`: `"all"` (default), `["validate"]`, or `["overrides"]`
+- `brandName`: Optional — primary brand context for brand-specific token warnings
+- `tokenPrefix`: Optional — overrides the prefix derived from the token dataset
+- `excludePatterns`: Optional glob pattern(s) to exclude files/directories
+- `saveAsFile`: Optional boolean — persists results to `tmp/.angular-toolkit-mcp/audit-token-usage/`
+**Output**:
+- `validate`: Invalid token references with typo suggestions (Levenshtein distance ≤ 3) and valid references
+- `overrides`: Token re-declarations grouped by mechanism (`host`, `ng-deep`, `class-selector`, `root-theme`, `important`, `unknown`) with optional classification (`legitimate`, `component-override`, `deep-override`, `important-override`, `inline-override`, `scope-violation`)
+- `summary`: Total issue count broken down by mode
+- `diagnostics`: Warnings when modes are skipped or running in degraded state
+**Modes**:
+- `validate` — requires `generatedStylesRoot` to be configured; skipped with diagnostic if unavailable
+- `overrides` — works without token data (detection-only); classification requires `generatedStylesRoot`
+**Best Practice**: Leave `ds.tokens.propertyPrefix` as `null` in config so the tool loads all token prefixes (e.g. both `--semantic-` and `--ds-`) and validates references across all of them. Setting a single prefix limits both validation and override detection to that prefix only.
+
 #### `get-project-dependencies`
 **Purpose**: Analyzes project structure, dependencies, and buildability
 **AI Usage**: Validate project architecture before suggesting refactoring strategies