@evolith/smart-cli 1.1.0 → 1.1.1

package/README.md

@@ -1,191 +1,840 @@
-# Evolith CLI
+# @evolith/smart-cli
 
-Command-line interface for Evolith governance, standards validation, and AI agent integration.
+Command-line interface for Evolith — governance, standards validation, architecture scaffolding, SDLC lifecycle management, and AI agent integration.
 
-## Features
+## Overview
 
-- **Governance**: ADR management, standards tracking, agent installation
-- **Validation**: Repository compliance against Evolith standards
-- **AI Integration**: MCP server for AI agent tool calling
-- **Observability**: Structured logging, metrics, error reporting
+SmartCLI is the primary entry point to the Evolith ecosystem. It connects three layers:
 
-## Installation
+```
+satellite repository
+       │
+       ▼
+  smart-cli  ──────── evolith.yaml (configuration)
+       │
+       ├── Evolith Core (rulesets, ADRs, standards, gate evidence)
+       │
+       └── MCP Server ──── AI Agents (Cursor, Claude Desktop, custom)
+```
+
+## Supported Architectures
+
+SmartCLI operates on three progressive architecture topologies. All commands that accept a `--topology` or `--phase` flag reference these levels:
+
+| Level | Name | Description |
+|-------|------|-------------|
+| F1 | Monolithic Modular | Single deployable with clean hexagonal layers |
+| F2 | Microfrontend | Module Federation with a host app and remote modules |
+| F3 | Distributed Microfrontend | Independent deployment of each remote with its own CI/CD |
 
-### npm (Recommended)
+Progression is linear: F1 → F2 → F3. The `upgrade` command manages topology transitions.
+
+## Installation
 
 ```bash
 npm install -g @evolith/smart-cli
 ```
 
-### Manual
+```bash
+pnpm add -g @evolith/smart-cli
+```
 
-Download the latest binary from [GitHub Releases](https://github.com/beyondnetcode/evolith_arch32/releases) and add to your PATH.
+```bash
+yarn global add @evolith/smart-cli
+```
 
-### Verify Installation
+Or download the binary from [GitHub Releases](https://github.com/beyondnetcode/evolith_arch32/releases) and add it to your PATH.
+
+### Verify
 
 ```bash
 smart-cli --version
-# smart-cli version 0.0.3-beta
+# smart-cli version 1.1.0
 ```
 
-## Quickstart
+### Troubleshooting
 
-### 1. Initialize a Repository
+**EACCES on macOS/Linux:**
+```bash
+sudo npm install -g @evolith/smart-cli --unsafe-perm
+```
 
+**nvm — binary not found after install:**
 ```bash
-cd your-project
+export PATH=$(npm config get prefix)/bin:$PATH
+```
+
+## Quickstart
+
+```bash
+# 1. Seed a demo project to explore the CLI
+smart-cli fixtures --type demo
+
+# 2. Initialize a real repository
 smart-cli init
+
+# 3. Scaffold base documentation
+smart-cli docs
+
+# 4. Validate compliance
+smart-cli validate
+
+# 5. Scaffold architecture (F1)
+smart-cli scaffold --phase 1
+
+# 6. Connect an AI agent
+smart-cli mcp serve
 ```
 
-This creates an `evolith.yaml` file with default configuration.
+---
 
-### 2. Run First Validation
+## Commands
+
+### init
+
+Initializes a satellite repository with interactive tool selection. Creates `evolith.yaml` and the project structure.
 
 ```bash
-smart-cli validate
+smart-cli init [options]
+
+Options:
+  -d, --dry-run          Run without writing files
+  -c, --config <path>    Path to evolith.setup.json for batch mode
+  -r, --runtime <id>     Runtime: nodejs, dotnet, python
+  -m, --monorepo <id>    Monorepo strategy: none, nx, npm-workspaces, rush
+  -a, --arch <id>        Architecture pattern: clean, hexagonal, ddd
+      --db <id>          Database: postgresql, mongodb, sqlserver
 ```
 
-Output:
+**Examples:**
+
+```bash
+# Interactive wizard
+smart-cli init
+
+# Batch mode (non-interactive)
+smart-cli init --config evolith.setup.json
+
+# Preview without writing
+smart-cli init --dry-run
 ```
-✓ Validating repository...
-✓ Repository is compliant with Evolith standards
+
+After `init` completes, the CLI prints suggested next steps including `validate`, `agents --install`, and `sdlc handoff`.
+
+---
+
+### docs
+
+Scaffolds the base documentation files required by Evolith in the current directory.
+
+Files created by default:
+- `README.md` — project overview template
+- `AGENTS.md` — AI agent configuration and rules
+- `MASTER_INDEX.md` — documentation index
+- `.evolith/evolith.yaml` — Evolith configuration
+
+```bash
+smart-cli docs [options]
+
+Options:
+  -d, --dry-run          Preview files without writing
+  -f, --force            Overwrite existing files
+  -t, --template <type>  Template type: default (all 4 files), minimal (README + AGENTS only)
+      --format <format>  Output format: json (ADR-0073 envelope) or human (default)
 ```
 
-### 3. Install an Agent
+**Examples:**
 
 ```bash
-smart-cli agents install
-# Select "standard" template when prompted
+# Scaffold all documentation
+smart-cli docs
+
+# Preview what would be created
+smart-cli docs --dry-run
+
+# Minimal scaffold
+smart-cli docs --template minimal
+
+# Force overwrite and emit JSON envelope
+smart-cli docs --force --format json
 ```
 
-## Commands
+---
 
 ### validate
 
-Validate repository compliance against Evolith standards.
+Validates repository compliance against Evolith standards. Supports multiple engines, rulesets, topologies, and SDLC phases.
 
 ```bash
 smart-cli validate [options]
 
 Options:
-  --satellite <path>    Path to satellite repository (default: cwd)
-  --core <path>         Path to Evolith Core
-  --format <format>     Output format: json, table, yaml, markdown
-  --output <file>       Write output to file
-  --ruleset <id>        Validate specific ruleset (acl, open-core, inheritance)
-  --engine <engine>     Policy evaluation engine: native or opa (default: native)
+  -s, --satellite <path>   Satellite repository path (default: cwd)
+  -c, --core <path>        Evolith Core path (default: auto-detect)
+  -f, --format <format>    Output format: json, table, yaml, markdown (default: markdown)
+  -o, --output <file>      Write output to file
+  -r, --ruleset <id>       Validate a specific ruleset (see table below)
+  -e, --engine <engine>    Validation engine: native (default) or opa
+  -t, --topology <id>      Topology to validate: F1, F2, F3, ALL (repeatable)
+  -m, --manifest <path>    SatelliteManifest JSON for end-to-end evaluation (GT-281 pipeline)
+  -p, --phase <phase>      SDLC phase to evaluate: f1, f2, f3, f4, f5 (activates GT-281 pipeline)
+      --adr <id>           Validate against a specific ADR rule set
+      --file <path>        Validate a single file (ad-hoc mode)
+      --composable         Use the composable GT-312 engine with intelligent mode resolution
 ```
 
-**Dual-Engine Policy Evaluation:**
-The CLI supports evaluating policies using either the built-in TypeScript engine (`native`) or Open Policy Agent WebAssembly modules (`opa`). See [Core ADR-0041](../../reference/architecture/adrs/core/0041-dual-engine-policy-evaluation.md) for details.
+**Available rulesets (`--ruleset`):**
+
+| ID | Validates |
+|----|-----------|
+| `acl` | Access control layer rules |
+| `open-core` | Open-core module boundaries |
+| `inheritance` | Inheritance and extension contracts |
+| `cli-release` | CLI release readiness |
+| `cli-parity` | CLI command parity between versions |
+| `evidence` | Gate evidence artifact completeness |
+| `mcp` | MCP server contract compliance |
+| `observability` | Logging, metrics, and tracing coverage |
+| `adr-0002` | ADR-0002 specific rules |
+
+**Available ADR rules (`--adr`):** `adr-0002`, `adr-0005`, `adr-0010`, `adr-0018`, `adr-0032`, `adr-0040`, `adr-0050`
+
+**Validation engines:**
+- `native` — built-in TypeScript engine (default, no external dependencies)
+- `opa` — Open Policy Agent WebAssembly modules
+
+**Composable engine (GT-312):**  
+When `--composable` is set, the CLI auto-resolves which validation modes to activate based on the provided context:
+- `SdlcValidationMode` — activated when `--phase` is present
+- `ArchitectureValidationMode` — activated when `--topology` is present
+- `RulesetValidationMode` — activated when `--ruleset` is present
+- `AdrValidationMode` — activated when `--adr` is present
+- `AdhocValidationMode` — activated when `--file` is present
 
 **Examples:**
 
 ```bash
-# Basic validation
+# Basic compliance check
 smart-cli validate
 
-# JSON output for automation
-smart-cli validate --format json
+# JSON output for CI
+smart-cli validate --format json --output report.json
 
-# Table output for humans
-smart-cli validate --format table
+# Validate F2 topology
+smart-cli validate --topology F2
+
+# Validate multiple topologies
+smart-cli validate --topology F1 --topology F2
 
-# Validate specific ruleset
-smart-cli validate --ruleset acl
+# Validate a specific ruleset
+smart-cli validate --ruleset evidence
+
+# Full SDLC phase evaluation (GT-281 pipeline)
+smart-cli validate --phase f1
+
+# Validate with a SatelliteManifest
+smart-cli validate --manifest ./satellite-manifest.json --phase f2
+
+# Ad-hoc file validation
+smart-cli validate --file src/domain/user.entity.ts --composable
+
+# OPA engine
+smart-cli validate --engine opa --ruleset acl
 ```
 
+---
+
 ### adr
 
-Manage Architecture Decision Records.
+Manages Architecture Decision Records.
 
 ```bash
-smart-cli adr <command>
+smart-cli adr [options]
 
-Commands:
-  create     Create new ADR
-  list       List all ADRs
-  get        Show ADR details
-  update     Update existing ADR
-  matrix     Show ADR matrix
+Options:
+  -c, --create           Create a new ADR (interactive)
+  -l, --list             List all ADRs
+  -g, --get <id>         Show a specific ADR
+  -u, --update <id>      Update ADR status
+  -s, --status <status>  New status: Accepted, Deprecated, Superseded, Amended
+  -r, --reason <text>    Reason for status change
+  -m, --matrix           Show ADR matrix summary
+  -d, --dry-run          Preview without writing files
 ```
 
 **Examples:**
 
 ```bash
-# Create new ADR
-smart-cli adr create
+# Interactive creation
+smart-cli adr --create
 
-# List all ADRs
-smart-cli adr list
+# List all
+smart-cli adr --list
 
-# Get specific ADR
-smart-cli adr get ADR-0002
+# Show specific ADR
+smart-cli adr --get ADR-0002
+
+# Update status
+smart-cli adr --update ADR-0005 --status Accepted --reason "Approved in design review"
+
+# Show matrix
+smart-cli adr --matrix
 ```
 
+---
+
 ### standards
 
-Manage governance standards.
+Manages Evolith governance standards (architecture, governance, operations).
 
 ```bash
-smart-cli standards <command>
+smart-cli standards [options]
 
-Commands:
-  init       Initialize standards directory
-  list       List all standards
-  get        Show standard details
-  validate   Validate against standards
-  export     Export standard to markdown/json
+Options:
+      --init             Initialize standards directory structure
+  -l, --list             List all standards
+  -g, --get <id>         Show a specific standard
+  -v, --validate <code>  Validate code against standards
+  -e, --export <id>      Export a standard
+  -f, --format <format>  Export format: markdown, json
+  -c, --category <id>    Filter by category
 ```
 
 **Examples:**
 
 ```bash
-# Initialize standards
-smart-cli standards init
+# Initialize
+smart-cli standards --init
+
+# List all standards
+smart-cli standards --list
 
-# List standards
-smart-cli standards list
+# Filter by category
+smart-cli standards --list --category governance
+
+# Export as markdown
+smart-cli standards --export STD-001 --format markdown
 ```
 
+---
+
 ### agents
 
-Install and manage Evolith agents.
+Manages Evolith BMAD agents — installs, lists, and removes governance agents in the satellite repository.
 
 ```bash
-smart-cli agents <command>
+smart-cli agents [options]
 
-Commands:
-  install    Install new agent
-  list       List installed agents
-  remove     Remove agent
-  validate   Validate agent ruleset
-  upgrade    Upgrade agent
+Options:
+  -l, --list             List installed agents
+  -i, --install [name]   Install a named agent (interactive if name omitted)
+  -r, --remove [name]    Remove an installed agent
+  -d, --dry-run          Preview without making changes
 ```
 
+**Available agent templates:**
+
+| Template | Description |
+|---|---|
+| `standard` | Default agent with basic governance rules (ACL-01 through ACL-06) |
+| `minimal` | Lightweight agent with essential rules only |
+| `full-compliance` | Full compliance agent with audit trail and approval chains |
+
 **Examples:**
 
 ```bash
+# List installed agents
+smart-cli agents --list
+
 # Interactive install
-smart-cli agents install
+smart-cli agents --install
+
+# Install a specific template
+smart-cli agents --install standard
+smart-cli agents --install full-compliance
+
+# Preview install without writing
+smart-cli agents --install standard --dry-run
+
+# Remove an agent
+smart-cli agents --remove minimal
+```
+
+---
+
+### scaffold
+
+Scaffolds the Evolith architecture in the current workspace. Supports all three topology phases (F1, F2, F3) with configurable frontend frameworks, ORMs, and domain names.
+
+```bash
+smart-cli scaffold [options]
+
+Options:
+      --frontend <framework>   Frontend framework: react, angular
+      --orm <orm>              ORM: prisma, typeorm
+  -d, --dry-run                Preview without writing files
+  -f, --format <format>        Output format: json (ADR-0073 envelope) or human (default)
+      --phase <phase>          Architecture phase: 1 (F1), 2 (F2), 3 (F3) — required with --format json
+      --api-name <name>        Backend API app name (default: tracker-api)
+      --web-app-name <name>    Web app name for phase 1 (default: tracker-web)
+      --host-name <name>       Host app name for phase 2/3 (default: tracker-host)
+      --remotes <names>        Comma-separated remote names for phase 2/3
+      --domains <names>        Comma-separated domain names to generate
+```
+
+**Examples:**
+
+```bash
+# Scaffold F1 (Monolithic Modular) interactively
+smart-cli scaffold
+
+# Scaffold F1 with React + Prisma, dry run
+smart-cli scaffold --phase 1 --frontend react --orm prisma --dry-run
+
+# Scaffold F2 (Microfrontend) with custom names
+smart-cli scaffold --phase 2 --host-name shell-app --remotes catalog,checkout
+
+# Scaffold F3 with custom domains and JSON output
+smart-cli scaffold --phase 3 --domains orders,payments,users --format json
+
+# Generate specific domains only
+smart-cli scaffold --domains auth,notifications
+```
+
+---
+
+### drift
+
+Detects architecture drift between the declared topology level and the actual codebase structure. Stores history for trend analysis.
+
+```bash
+smart-cli drift [options]
+
+Options:
+  -p, --path <path>    Project path to analyze (default: cwd)
+  -l, --level <level>  Declared architecture level: F1, F2, F3
+      --json           Output as raw JSON
+      --history        Show drift scan history (last 10 scans)
+      --trend          Show drift trend analysis (improving / stable / degrading)
+  -f, --format <fmt>   Output format: json (ADR-0073 envelope) or human (default)
+```
+
+The drift report includes:
+- **Declared level** vs **detected level**
+- **Overall score** (0–100%)
+- **Drift severity**: critical, high, medium, low, none
+- **New violations** — introduced since last scan
+- **Persistent violations** — unresolved across multiple scans
+- **Resolved violations** — fixed since last scan
+
+**Examples:**
+
+```bash
+# Detect drift (auto-detects declared level from evolith.yaml)
+smart-cli drift
+
+# Specify declared level explicitly
+smart-cli drift --level F2
+
+# Analyze a different project path
+smart-cli drift --path ../my-satellite
+
+# Show historical scans
+smart-cli drift --history
+
+# Show trend (requires at least 2 prior scans)
+smart-cli drift --trend
+
+# JSON output for CI
+smart-cli drift --format json
+```
+
+---
+
+### gate
+
+Evaluates SDLC phase gates and emits ADR-0073 `GateEvidence` artifacts. Supports webhook delivery and multi-actor contexts.
+
+```bash
+smart-cli gate <action> [options]
+
+Actions:
+  evaluate    Evaluate gates for the specified phase
+
+Options:
+  -p, --phase <phase>         SDLC phase: discovery, design, construction, qa, release
+      --project <path>        Satellite project path (default: cwd)
+  -c, --core <path>           Evolith Core path (default: auto-detect)
+  -f, --format <format>       Output format: json (ADR-0073 envelope) or human (default)
+      --evaluated-by <actor>  Actor class: human (default), agent, ci
+      --initiative <id>       Initiative context — echoed in meta.context
+      --tenant <id>           Tenant context — echoed in meta.context
+      --webhook-url <url>     POST gate evidence to this URL upon completion
+```
+
+**Examples:**
+
+```bash
+# Evaluate design phase gates
+smart-cli gate evaluate --phase design
+
+# CI evaluation with JSON output
+smart-cli gate evaluate --phase construction --evaluated-by ci --format json
+
+# Agent-driven evaluation with webhook delivery
+smart-cli gate evaluate --phase qa --evaluated-by agent --webhook-url https://ci.example.com/hooks/evolith
+
+# Multi-tenant context
+smart-cli gate evaluate --phase release --tenant acme --initiative Q3-launch
+```
+
+---
+
+### phase
+
+Proposes a phase transition between SDLC phases. Emits a transition proposal artifact.
+
+```bash
+smart-cli phase advance [options]
+
+Options:
+      --from <phase>          Current SDLC phase
+      --to <phase>            Target SDLC phase
+      --project <path>        Satellite project path (default: cwd)
+  -c, --core <path>           Evolith Core path (default: auto-detect)
+  -f, --format <format>       Output format: json (ADR-0073 envelope) or human (default)
+      --evaluated-by <actor>  Actor class: human, agent (default), ci
+      --initiative <id>       Initiative context — echoed in meta.context
+      --tenant <id>           Tenant context — echoed in meta.context
+      --webhook-url <url>     POST the transition proposal to this URL
+```
+
+**Examples:**
+
+```bash
+# Propose advancing from design to construction
+smart-cli phase advance --from design --to construction
+
+# Agent-driven with JSON output
+smart-cli phase advance --from construction --to qa --evaluated-by agent --format json
+
+# With webhook and tenant context
+smart-cli phase advance --from qa --to release --webhook-url https://ci.example.com/hooks/evolith --tenant acme
+```
+
+---
+
+### sdlc
+
+Parent command that orchestrates SDLC artifacts and lifecycle transitions. Run without a subcommand to see available subcommands.
+
+```bash
+smart-cli sdlc <subcommand>
+
+Subcommands:
+  handoff       Transition artifacts between phases with interactive guided flow
+  generate      Generate Hexagonal Architecture scaffold from a DDD model file
+  gate-status   Display phase gate validation status and DORA metrics
+```
+
+#### sdlc handoff
+
+Guides an interactive phase transition, validates gates, and generates evidence artifacts.
+
+```bash
+smart-cli sdlc handoff [options]
+
+Options:
+  -f, --from <phase>   Source phase (phase-0, phase-1, etc.)
+  -t, --to <phase>     Target phase (phase-0, phase-1, etc.)
+  -a, --artifacts      Generate evidence artifacts
+      --validate       Validate phase gates before handoff
+      --force          Force handoff even if gates fail
+```
+
+**Examples:**
+
+```bash
+# Interactive handoff wizard
+smart-cli sdlc handoff
+
+# Handoff from phase-0 to phase-1 with gate validation
+smart-cli sdlc handoff --from phase-0 --to phase-1 --validate
+
+# Generate artifacts and force even if gates fail
+smart-cli sdlc handoff --from phase-1 --to phase-2 --artifacts --force
+```
+
+#### sdlc generate
+
+Generates a complete Hexagonal Architecture scaffold by reading a Mermaid `classDiagram` from a Markdown DDD model file.
+
+```bash
+smart-cli sdlc generate [options]
+
+Options:
+  -f, --from <path>   Path to the Markdown file containing the Mermaid classDiagram
+  -o, --output <dir>  Target directory for generated files (default: cwd)
+      --dry-run       Print what would be generated without writing files
+```
+
+**Examples:**
+
+```bash
+# Generate from a DDD model file
+smart-cli sdlc generate --from docs/domain-model.md
+
+# Preview without writing
+smart-cli sdlc generate --from docs/domain-model.md --dry-run
+
+# Output to a specific directory
+smart-cli sdlc generate --from docs/domain-model.md --output src/domain
+```
+
+The input file must contain a fenced Mermaid block with a `classDiagram`. The generator creates entities, value objects, repositories, use cases, and ports following hexagonal architecture conventions.
+
+#### sdlc gate-status
+
+Displays the current SDLC phase gate validation status along with DORA metrics calculated from git history.
+
+```bash
+smart-cli sdlc gate-status [options]
+
+Options:
+  --since <days>   Days of git history to analyze for DORA metrics (default: 90)
+```
+
+DORA metrics reported:
+- **Deployment Frequency** — how often the team deploys to production
+- **Lead Time for Changes** — time from commit to production
+- **Change Failure Rate** — percentage of deployments causing failures
+- **Time to Restore** — time to recover from a production failure
+
+**Examples:**
+
+```bash
+# Current gate status with 90-day DORA window
+smart-cli sdlc gate-status
+
+# Analyze last 30 days only
+smart-cli sdlc gate-status --since 30
+```
+
+---
+
+### profile
+
+Manages named CLI profiles. Each profile stores a set of defaults (satellite path, core path, tenant, initiative) that are applied automatically to subsequent commands.
+
+```bash
+smart-cli profile <action> [options]
+
+Actions:
+  current   Show the active profile
+  list      List all profiles
+  create    Create a new profile
+  switch    Switch to a named profile
+  delete    Delete a profile
+
+Options:
+  -n, --name <name>   Profile name (used with create and switch)
+```
+
+**Examples:**
+
+```bash
+# Show current profile
+smart-cli profile current
+
+# List all profiles
+smart-cli profile list
+
+# Create a profile interactively
+smart-cli profile create
+
+# Create with a name
+smart-cli profile create --name staging
+
+# Switch profile
+smart-cli profile switch --name staging
+
+# Delete a profile
+smart-cli profile delete --name staging
+```
+
+---
+
+### fixtures
+
+Seeds reproducible fixture files for demos, tests, and onboarding. The first step recommended in any new environment.
+
+```bash
+smart-cli fixtures [type] [options]
+
+Arguments:
+  type   Fixture type (default: demo)
+
+Options:
+  -d, --dir <directory>   Target directory (default: cwd)
+  -n, --dry-run           Preview files without writing
+  -t, --type <type>       Fixture type: demo, adr, ruleset, evolith, full
+```
+
+**Fixture types:**
+
+| Type | Contents |
+|------|----------|
+| `demo` | Sample project with evolith.yaml and demo structure |
+| `adr` | Pre-populated ADR entries |
+| `ruleset` | Example rulesets (domain, naming, file conventions) |
+| `evolith` | Full Evolith configuration files |
+| `full` | All of the above combined |
+
+**Examples:**
+
+```bash
+# Seed a demo project (fastest way to explore the CLI)
+smart-cli fixtures --type demo
+
+# Preview what would be created
+smart-cli fixtures --type full --dry-run
+
+# Seed ADR fixtures into a specific directory
+smart-cli fixtures --type adr --dir ./reference/architecture/adrs
+```
+
+---
+
+### api
+
+Browses and inspects the Evolith API surface: MCP tools, resources, schemas, and CLI commands.
+
+```bash
+smart-cli api [options]
+
+Options:
+  -l, --list                  List all available API operations
+  -i, --inspect <name>        Inspect a specific operation, resource, or command
+  -c, --category <category>   Filter by category: tools, resources, schemas, commands
+```
+
+**Examples:**
+
+```bash
+# List everything
+smart-cli api --list
+
+# Filter MCP tools only
+smart-cli api --list --category tools
+
+# Inspect a specific tool
+smart-cli api --inspect evolith-validate
+
+# Inspect a CLI command schema
+smart-cli api --inspect validate --category commands
+```
+
+---
+
+### update
+
+Checks for and applies CLI updates.
+
+```bash
+smart-cli update [options]
+
+Options:
+  -c, --current   Show the current installed CLI version
+      --check     Check for available updates without installing
+  -i, --install   Install the latest available version
+```
+
+**Examples:**
+
+```bash
+# Show current version
+smart-cli update --current
+
+# Check for updates
+smart-cli update --check
+
+# Install latest
+smart-cli update --install
+```
+
+---
+
+### upgrade
+
+Upgrades a satellite repository to the next progressive-axis topology or governance version.
+
+```bash
+smart-cli upgrade [options]
+
+Options:
+      --dry-run          Simulate the upgrade without making changes
+      --target <target>  Target governance version or topology (e.g., F2, 1.1.0)
+      --force            Skip eligibility checks
+```
+
+**Examples:**
+
+```bash
+# Preview upgrade to the next topology
+smart-cli upgrade --dry-run
 
-# List agents
-smart-cli agents list
+# Upgrade to F2
+smart-cli upgrade --target F2
+
+# Force upgrade ignoring eligibility checks
+smart-cli upgrade --target F3 --force
 ```
 
+---
+
+### alias
+
+Manages shorthand aliases for CLI commands.
+
+```bash
+smart-cli alias [options]
+
+Options:
+  --add <alias=command>   Add a new alias (format: name=command)
+  --remove <alias>        Remove an alias
+  --list                  List all aliases
+```
+
+**Examples:**
+
+```bash
+# Add an alias
+smart-cli alias --add "v=validate --format table"
+
+# List aliases
+smart-cli alias --list
+
+# Remove an alias
+smart-cli alias --remove v
+```
+
+---
+
 ### history
 
-View and manage command history.
+Views and manages CLI command execution history.
 
 ```bash
 smart-cli history [options]
 
 Options:
-  --list              List recent commands
-  --get <id>          Show command details
-  --search <query>    Search commands
-  --stats             Show statistics
-  --clear             Clear history
+  -l, --list             List recent commands
+  -g, --get <id>         Show command details by ID
+  -s, --search <query>   Search history
+      --stats            Show history statistics
+      --clear            Clear all history
+  -n, --limit <number>   Number of entries to show (default: 20)
+      --replay <id>      Show the command string for a given history entry
 ```
 
 **Examples:**
@@ -194,61 +843,103 @@ Options:
 # Show last 20 commands
 smart-cli history
 
+# Show last 50
+smart-cli history --limit 50
+
+# Search for validate runs
+smart-cli history --search validate
+
 # Show statistics
 smart-cli history --stats
 
-# Search commands
-smart-cli history --search validate
+# Clear history
+smart-cli history --clear
 ```
 
+---
+
 ### completion
 
-Generate shell completion scripts.
+Generates and installs shell completion scripts. Also provides shell hook functions for context and status display.
 
 ```bash
-smart-cli completion --install <shell>
+smart-cli completion [options]
 
-Supported shells: bash, zsh, fish
+Options:
+  --install <shell>   Install completion for specified shell: bash, zsh, fish
+  --shell <shell>     Generate completion script for specified shell (prints to stdout)
+  --hooks             Generate shell hook functions for context/status display
 ```
 
 **Examples:**
 
 ```bash
+# Install zsh completion
+smart-cli completion --install zsh
+
 # Install bash completion
 smart-cli completion --install bash
 
-# Install zsh completion
-smart-cli completion --install zsh
+# Install fish completion
+smart-cli completion --install fish
+
+# Print completion script to stdout (for manual setup)
+smart-cli completion --shell zsh
+
+# Generate hook functions
+smart-cli completion --hooks
 ```
 
-## MCP Server (AI Agent Integration)
+Pre-built scripts are also included in the package under `shell/`:
+- `shell/completion.bash`
+- `shell/completion.zsh`
+- `shell/completion.fish`
+- `shell/hooks.bash`
+- `shell/hooks.zsh`
+
+---
 
-The Evolith CLI includes an MCP server for AI agent integration.
+## MCP Server
 
-### Starting the MCP Server
+The Evolith CLI includes a production-ready MCP server for AI agent integration.
+
+### Starting the Server
 
 ```bash
+# stdio transport (default — for Cursor, Claude Desktop)
 smart-cli mcp serve
+
+# HTTP transport (for remote or containerized deployments)
+smart-cli mcp serve --transport http --port 3000
+
+# HTTP with API key authentication
+smart-cli mcp serve --transport http --port 3000 --api-key <secret>
 ```
 
-The server communicates via stdio JSON-RPC.
+```bash
+smart-cli mcp serve [options]
 
-### MCP Smoke Test
+Options:
+  -t, --transport <type>   Transport: stdio (default) or http
+  -p, --port <number>      HTTP server port (default: 3000)
+      --api-key <key>      API key for HTTP transport authentication
+      --no-confirm         Skip confirmation prompts
+```
 
-Use the smoke test before releases or MCP protocol changes:
+### Smoke Test
 
 ```bash
 npm run mcp:smoke
 ```
 
-The smoke verifies `initialize`, `tools/list`, `resources/list`, `prompts/list`, and a real `tools/call` through the built CLI.
+Verifies `initialize`, `tools/list`, `resources/list`, `prompts/list`, and a real `tools/call` end-to-end through the built CLI.
 
 ### Available MCP Tools
 
 | Tool | Description |
 |------|-------------|
 | `evolith-validate` | Validate repository compliance |
-| `evolith-agent-install` | Install new agent |
+| `evolith-agent-install` | Install a new BMAD agent |
 | `evolith-agent-list` | List installed agents |
 | `evolith-agent-validate` | Validate agent ruleset |
 | `evolith-agent-upgrade` | Upgrade an existing agent |
@@ -256,8 +947,8 @@ The smoke verifies `initialize`, `tools/list`, `resources/list`, `prompts/list`,
 | `evolith-architecture-validate` | Validate architecture (F1/F2/F3) with optional deep analysis |
 | `evolith-sdlc-handoff` | Generate phase handoff artifact manifest |
 | `evolith-sdlc-status` | Show SDLC phase gate status |
-| `evolith-config-get` | Get configuration value from `evolith.yaml` |
-| `evolith-config-set` | Set configuration value in `evolith.yaml` |
+| `evolith-config-get` | Get a configuration value from `evolith.yaml` |
+| `evolith-config-set` | Set a configuration value in `evolith.yaml` |
 | `evolith-metrics` | Get MCP server metrics |
 | `evolith-moscow-create` | Create a new MoSCoW prioritization analysis |
 | `evolith-moscow-load` | Load an existing MoSCoW analysis |
@@ -297,37 +988,63 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-## AI Agent Workflow Example
-
-When integrated with an AI agent, you can have conversations like:
+### HTTP Transport (remote deployment)
 
+```json
+{
+  "mcpServers": {
+    "evolith": {
+      "url": "http://localhost:3000",
+      "headers": { "x-api-key": "<secret>" }
+    }
+  }
+}
 ```
-You: Validate my repository
-Agent: Let me run the validation...
 
-      await mcp.callTool('evolith-validate', {
-        path: '/user/project',
-        format: 'summary'
-      })
+---
 
-Result: ✓ Repository is compliant with Evolith standards
-        Rules checked: 12
-        All gates passed
+## CI/CD Integration
 
-You: Show me the SDLC status
-Agent: Let me check the phase gate status...
+### SDLC Phase Validation (GT-281 Pipeline)
 
-      await mcp.callTool('evolith-sdlc-status', {
-        path: '/user/project'
-      })
+```bash
+# Validate a specific SDLC phase with full gate evaluation
+smart-cli validate --phase f2 --format json --output gate-evidence.json
+
+# With explicit SatelliteManifest
+smart-cli validate --manifest ./satellite-manifest.json --phase f3 --format json
+```
 
-Result: Phase 1 — 3 gates passed, 0 failed
-        All evidence artifacts present
+### Gate Evaluation in CI
+
+```bash
+# Evaluate construction gates from CI
+smart-cli gate evaluate \
+  --phase construction \
+  --evaluated-by ci \
+  --format json \
+  --webhook-url $WEBHOOK_URL
 ```
 
+### GitHub Actions Example
+
+```yaml
+- name: Evolith Gate Evaluation
+  run: |
+    smart-cli gate evaluate \
+      --phase ${{ env.SDLC_PHASE }} \
+      --evaluated-by ci \
+      --format json \
+      --output gate-evidence.json
+  env:
+    SDLC_PHASE: construction
+```
+
+---
+
 ## Configuration
 
-Evolith uses an `evolith.yaml` file in the repository root:
+Evolith uses `evolith.yaml` in `.evolith/` or the repository root:
 
 ```yaml
 coreRef:
@@ -346,96 +1063,113 @@ product:
   runtime: "typescript"
 ```
 
+### Multi-Environment Profiles
+
+```bash
+# Create a profile per environment
+smart-cli profile create --name local
+smart-cli profile create --name staging
+smart-cli profile create --name ci
+
+# Switch before running commands
+smart-cli profile switch --name staging
+smart-cli validate
+```
+
+---
+
 ## Output Formats
 
-All commands support multiple output formats:
+Most commands accept `--format`:
 
 ```bash
-# JSON (default for automation)
-smart-cli validate --format json
+# Human-readable (default for most commands)
+smart-cli validate
+
+# Markdown
+smart-cli validate --format markdown
 
-# Table (human-readable)
+# Table
 smart-cli validate --format table
 
-# YAML (pipeline integration)
+# YAML
 smart-cli validate --format yaml
 
-# Markdown (documentation)
-smart-cli validate --format markdown
+# JSON (ADR-0073 envelope — for automation and CI)
+smart-cli validate --format json
 ```
 
-## Troubleshooting
-
-### Command not found
+---
 
-If `evolith` is not found after installation, ensure npm's global bin is in your PATH:
+## Troubleshooting
 
+**Command not found after install:**
 ```bash
-# Add to ~/.bashrc or ~/.zshrc
 export PATH="$(npm config get prefix)/bin:$PATH"
 ```
 
-### MCP server not responding
-
-Ensure the MCP server is running:
-
+**Validation fails with no evolith.yaml:**
 ```bash
-smart-cli mcp serve &
+smart-cli docs         # scaffold evolith.yaml and base docs
+smart-cli validate
 ```
 
-### Validation fails
-
-Check your `evolith.yaml` exists and is valid:
-
+**MCP server not responding:**
 ```bash
-cat evolith.yaml
-smart-cli validate --verbose
+smart-cli mcp serve --no-confirm
 ```
 
+**Unknown topology in scaffold or drift:**
+Ensure your `evolith.yaml` has a valid `product.topology` field: `F1`, `F2`, or `F3`.
+
+---
+
 ## Development
 
-### Building from Source
+### Build from Source
 
 ```bash
 cd sdk/cli
 npm install
 npm run build
-npm link  # Link globally for testing
+npm link
 ```
 
-### Running Tests
+### Tests
 
 ```bash
-# Run all tests
-npm test
-
-# Run with coverage report
-npm run test:cov
+npm test               # unit + e2e
+npm run test:unit      # unit only
+npm run test:e2e       # e2e only
+npm run test:cov       # coverage report
+npm run mcp:smoke      # MCP protocol smoke test
 ```
 
-**Coverage (as of v0.0.3-beta):** 88.7% statements · 89.8% lines · 77.0% branches · 83.6% functions · 1 369 tests
-
 ### Project Structure
 
 ```
 sdk/cli/
 ├── src/
-│   ├── commands/      # CLI commands (adr, validate, agents, etc.)
-│   ├── application/   # Use cases
-│   ├── domain/        # Business logic (services, entities)
-│   ├── infrastructure/# External integrations (catalog, CLI)
-│   └── core/          # Shared (DI, observability, errors, MCP)
-├── shell/             # Shell completion scripts
-├── templates/         # Configuration templates
-└── docs/              # Documentation
+│   ├── commands/       # CLI commands (one directory per command)
+│   ├── config/         # Runtimes catalog, CLI commands matrix, aliases
+│   ├── contributions/  # Contribution validation
+│   ├── infrastructure/ # Config, filesystem, formatters, prompts, plugins
+│   └── plugins/        # Plugin registry and module
+├── shell/              # Bash, Zsh, Fish completion and hooks
+├── templates/          # Configuration templates
+├── test/               # E2E test suite
+└── docs/               # Extended documentation
 ```
 
-## Documentation
+### Extended Documentation
+
+- [Demo Guide](docs/SMART-CLI-DEMO.md) — end-to-end walkthrough of all commands and SDLC flows
+- [Vision](docs/VISION.md) — CLI vision and roadmap
+- [Data Models](docs/data-models.md) — domain data model reference
+- [MCP Integration](docs/MCP-INTEGRATION.md) — MCP server protocol details
+- [Handoff Protocol](docs/HANDOFF-PROTOCOL.md) — SDLC handoff artifact specification
 
-- [SMART CLI Demo Guide](docs/SMART-CLI-DEMO.md) - Comprehensive guide covering all commands, SDLC flow, product types, MCP integration, and architecture validation
-- [Vision](docs/VISION.md) - CLI vision and roadmap
-- [Data Models](docs/data-models.md) - Domain data models
-- [MCP Integration](docs/MCP-INTEGRATION.md) - MCP server integration details
+---
 
 ## Contributing
 
@@ -444,12 +1178,14 @@ sdk/cli/
 3. Make changes with tests
 4. Submit a pull request
 
+---
+
 ## License
 
-ISC
+MIT
 
 ## Support
 
-- [Documentation](https://github.com/beyondnetcode/evolith_arch32#readme)
 - [Issue Tracker](https://github.com/beyondnetcode/evolith_arch32/issues)
 - [Discussions](https://github.com/beyondnetcode/evolith_arch32/discussions)
+- [Documentation](https://github.com/beyondnetcode/evolith_arch32#readme)