doctor enhancements, setup, enhancements, ui functionality and design consolidation and , test projects fixes , product advisory attestation/rekor and delta verfications enhancements

docs/modules/cli/architecture.md

@@ -41,7 +41,72 @@ src/
 
 **Plug-in verbs.** Non-core verbs (Excititor, runtime helpers, future integrations) ship as restart-time plug-ins under `plugins/cli/**` with manifest descriptors. The launcher loads plug-ins on startup; hot reloading is intentionally unsupported. The inaugural bundle, `StellaOps.Cli.Plugins.NonCore`, packages the Excititor, runtime, and offline-kit command groups and publishes its manifest at `plugins/cli/StellaOps.Cli.Plugins.NonCore/`.
 
-**OS targets**: linux‑x64/arm64, windows‑x64/arm64, macOS‑x64/arm64.
+**OS targets**: linuxâ€'x64/arm64, windowsâ€'x64/arm64, macOSâ€'x64/arm64.
+
+---
+
+## 1.1) Command Routing Infrastructure (v2.x→v3.0 Migration)
+
+> Sprint: SPRINT_20260118_010_CLI_consolidation_foundation
+
+The CLI includes a **command routing infrastructure** to support backward-compatible command migration. This enables consolidating 81+ top-level commands into ~18 organized command groups while maintaining backward compatibility.
+
+### Routing Components
+
+```
+src/Cli/StellaOps.Cli/Infrastructure/
+├── ICommandRouter.cs           # Router interface
+├── CommandRouter.cs            # Route registration and lookup
+├── CommandRoute.cs             # Route model (old→new path mapping)
+├── CommandGroupBuilder.cs      # Fluent builder for command groups
+├── DeprecationWarningService.cs # Warning display on stderr
+├── RouteMappingConfiguration.cs # JSON config model + loader
+
+src/Cli/StellaOps.Cli/
+└── cli-routes.json             # Embedded route mappings (60+ entries)
+```
+
+### How Routing Works
+
+1. **At startup**, `CommandFactory.RegisterDeprecatedAliases()` loads `cli-routes.json` (embedded resource)
+2. **For each deprecated route**, creates a hidden alias command that:
+   - Delegates to the canonical command
+   - Shows a deprecation warning on stderr (once per session)
+3. **Warnings** include the old path, new path, removal version, and suppression instructions
+
+### Route Configuration Schema
+
+```json
+{
+  "version": "1.0",
+  "mappings": [
+    {
+      "old": "scangraph",
+      "new": "scan graph",
+      "type": "deprecated",
+      "removeIn": "3.0",
+      "reason": "Consolidated under scan command"
+    }
+  ]
+}
+```
+
+### Deprecation Warning Format
+
+```
+WARNING: 'stella scangraph' is deprecated and will be removed in v3.0.
+         Use 'stella scan graph' instead.
+         Set STELLA_SUPPRESS_DEPRECATION_WARNINGS=1 to hide this message.
+```
+
+### Timeline
+
+- **v2.x**: Both old and new command paths work; old paths show deprecation warnings
+- **v3.0**: Old command paths removed
+
+### Migration Guide
+
+See [migration-v3.md](./guides/migration-v3.md) for user-facing migration instructions and command mappings.
 
 ---
 
@@ -174,12 +239,12 @@ Both subcommands honour offline-first expectations (no network access) and norma
   * Uses `STELLAOPS_ADVISORYAI_URL` when configured; otherwise it reuses the backend base address and adds `X-StellaOps-Scopes` (`advisory:run` + task scope) per request.
   * `--timeout 0` performs a single cache lookup (for CI flows that only want cached artefacts).
 
-* `advise ask "<question>" [--evidence] [--no-action] [--conversation-id <id>] [--context <cve|scan|image>]`
-
-  * Calls advisory chat endpoints, returns a cited answer with evidence refs.
-  * `--no-action` disables action proposals; `--evidence` forces evidence chips in output.
-
-### 2.12 Decision evidence (new)
+* `advise ask "<question>" [--evidence] [--no-action] [--conversation-id <id>] [--context <cve|scan|image>]`
+
+  * Calls advisory chat endpoints, returns a cited answer with evidence refs.
+  * `--no-action` disables action proposals; `--evidence` forces evidence chips in output.
+
+### 2.12 Decision evidence (new)
 
 - `decision export`