diff --git a/docs/core-cli/modes.md b/docs/core-cli/modes.md
index 77da5257..963433ef 100644
--- a/docs/core-cli/modes.md
+++ b/docs/core-cli/modes.md
@@ -179,7 +179,7 @@ The `import from-code` command now uses mode-aware routing. You should see mode
 
 ```bash
 # Test with CI/CD mode (bundle name as positional argument)
-hatch run specfact --mode cicd import from-code test-project --repo . --confidence 0.5 --shadow-only
+hatch run specfact --mode cicd code import from-code test-project --repo . --confidence 0.5 --shadow-only
 
 # Expected output:
 # Mode: CI/CD (direct execution)
@@ -189,7 +189,7 @@ hatch run specfact --mode cicd import from-code test-project --repo . --confiden
 
 ```bash
 # Test with CoPilot mode (bundle name as positional argument)
-hatch run specfact --mode copilot import from-code test-project --repo . --confidence 0.5 --shadow-only
+hatch run specfact --mode copilot code import from-code test-project --repo . --confidence 0.5 --shadow-only
 
 # Expected output:
 # Mode: CoPilot (agent routing)
@@ -249,7 +249,7 @@ hatch run specfact code import my-project --repo . --confidence 0.7
 
 ```bash
 # Developer wants CI/CD mode even though CoPilot is available (bundle name as positional argument)
-hatch run specfact --mode cicd import from-code my-project --repo . --confidence 0.7
+hatch run specfact --mode cicd code import from-code my-project --repo . --confidence 0.7
 
 # Expected: Mode: CI/CD (direct execution) - flag overrides auto-detection
 ```
diff --git a/docs/examples/integration-showcases/integration-showcases-quick-reference.md b/docs/examples/integration-showcases/integration-showcases-quick-reference.md
index 79871720..103ad013 100644
--- a/docs/examples/integration-showcases/integration-showcases-quick-reference.md
+++ b/docs/examples/integration-showcases/integration-showcases-quick-reference.md
@@ -77,7 +77,7 @@ cd /tmp/specfact-integration-tests/example1_vscode
 # The AI will prompt for a plan name - suggest: "Payment Processing"
 
 # Alternative: CLI-only mode (bundle name as positional argument)
-specfact --no-banner import from-code payment-processing --repo . --output-format yaml
+specfact --no-banner code import from-code payment-processing --repo . --output-format yaml
 
 # Step 2: Run enforcement
 specfact --no-banner enforce stage --preset balanced
@@ -95,7 +95,7 @@ specfact --no-banner enforce stage --preset balanced
 cd /tmp/specfact-integration-tests/example2_cursor
 
 # Step 1: Import code (bundle name as positional argument)
-specfact --no-banner import from-code data-pipeline --repo . --output-format yaml
+specfact --no-banner code import from-code data-pipeline --repo . --output-format yaml
 
 # Step 2: Test original (should pass)
 specfact --no-banner enforce stage --preset balanced
@@ -117,7 +117,7 @@ specfact --no-banner plan compare src/pipeline.py src/pipeline_broken.py --fail-
 cd /tmp/specfact-integration-tests/example3_github_actions
 
 # Step 1: Import code (bundle name as positional argument)
-specfact --no-banner import from-code user-api --repo . --output-format yaml
+specfact --no-banner code import from-code user-api --repo . --output-format yaml
 
 # Step 2: Run enforcement
 specfact --no-banner enforce stage --preset balanced
@@ -135,7 +135,7 @@ specfact --no-banner enforce stage --preset balanced
 cd /tmp/specfact-integration-tests/example4_precommit
 
 # Step 1: Initial commit (bundle name as positional argument)
-specfact --no-banner import from-code order-processor --repo . --output-format yaml
+specfact --no-banner code import from-code order-processor --repo . --output-format yaml
 git add .
 git commit -m "Initial code"
 
@@ -220,7 +220,7 @@ for dir in example1_vscode example2_cursor example3_github_actions example4_prec
   echo "Testing $dir..."
   cd /tmp/specfact-integration-tests/$dir
   bundle_name=$(echo "$dir" | sed 's/example[0-9]_//')
-  specfact --no-banner import from-code "$bundle_name" --repo . --output-format yaml 2>&1
+  specfact --no-banner code import from-code "$bundle_name" --repo . --output-format yaml 2>&1
   specfact --no-banner enforce stage --preset balanced 2>&1
   echo "---"
 done
diff --git a/docs/examples/integration-showcases/integration-showcases-testing-guide.md b/docs/examples/integration-showcases/integration-showcases-testing-guide.md
index 5b5e58b2..2f5cef77 100644
--- a/docs/examples/integration-showcases/integration-showcases-testing-guide.md
+++ b/docs/examples/integration-showcases/integration-showcases-testing-guide.md
@@ -223,7 +223,7 @@ def process_payment(request):
 ### Option B: CLI-only (For Integration Testing)
 
 ```bash
-uvx specfact-cli@latest --no-banner import from-code --repo . --output-format yaml
+uvx specfact-cli@latest --no-banner code import from-code --repo . --output-format yaml
 ```
 
 **Note**: CLI-only mode uses AST-based analysis and may show "0 features" for minimal test cases. This is expected and the plan bundle is still created for manual contract addition.
@@ -234,17 +234,17 @@ uvx specfact-cli@latest --no-banner import from-code --repo . --output-format ya
 - **Repeated runs**: Use `--no-banner` **before** the command to suppress banner output
 - **Important**: `--no-banner` is a global parameter and must come **before** the subcommand, not after
   - ✅ Correct: `specfact --no-banner enforce stage --preset balanced`
-  - ✅ Correct: `uvx specfact-cli@latest --no-banner import from-code --repo . --output-format yaml`
+  - ✅ Correct: `uvx specfact-cli@latest --no-banner code import from-code --repo . --output-format yaml`
   - ❌ Wrong: `specfact govern enforce stage --preset balanced --no-banner`
-  - ❌ Wrong: `uvx specfact-cli@latest import from-code --repo . --output-format yaml --no-banner`
+  - ❌ Wrong: `uvx specfact-cli@latest code import from-code --repo . --output-format yaml --no-banner`
 
-**Note**: The `import from-code` command analyzes the entire repository/directory, not individual files. It will automatically detect and analyze all Python files in the current directory.
+**Note**: The `code import from-code` command analyzes the entire repository/directory, not individual files. It will automatically detect and analyze all Python files in the current directory.
 
 **Important**: These examples are designed for **interactive AI assistant usage** (slash commands in Cursor, VS Code, etc.), not CLI-only execution.
 
 **CLI vs Interactive Mode**:
 
-- **CLI-only** (`uvx specfact-cli@latest import from-code` or `specfact code import`): Uses AST-based analyzer (CI/CD mode)
+- **CLI-only** (`uvx specfact-cli@latest code import from-code` or `specfact code import`): Uses AST-based analyzer (CI/CD mode)
   - May show "0 features" for minimal test cases
   - Limited to AST pattern matching
   - Works but may not detect all features in simple examples
@@ -368,7 +368,7 @@ specfact --no-banner plan review django-example \
 - ✅ Stories are present in the plan bundle
 - ✅ Acceptance criteria are complete and testable
 
-**Note**: Contracts are **automatically extracted** during `import from-code` by the AST analyzer, but only if function signatures have type hints. For the async bug detection example, detecting "blocking I/O in async context" requires additional analysis (Semgrep async patterns, not just AST contracts).
+**Note**: Contracts are **automatically extracted** during `code import from-code` by the AST analyzer, but only if function signatures have type hints. For the async bug detection example, detecting "blocking I/O in async context" requires additional analysis (Semgrep async patterns, not just AST contracts).
 
 #### Step 3.4: Set Up Enforcement Configuration
 
@@ -511,7 +511,7 @@ Fix the blocking deviations or adjust enforcement config
 
 **What We've Accomplished**:
 
-1. ✅ Created plan bundle from code (`import from-code`)
+1. ✅ Created plan bundle from code (`code import from-code`)
 2. ✅ Enriched plan with semantic understanding (added feature and stories)
 3. ✅ Reviewed plan and added missing stories via CLI
 4. ✅ Configured enforcement (balanced preset)
@@ -637,7 +637,7 @@ Stories added (4 total):
 **Alternative**: CLI-only mode:
 
 ```bash
-uvx specfact-cli@latest --no-banner import from-code --repo . --output-format yaml
+uvx specfact-cli@latest --no-banner code import from-code --repo . --output-format yaml
 ```
 
 **Note**: Interactive mode creates valid plan bundles with features. CLI-only may show 0 features for minimal test cases. Use `--no-banner` before the command to suppress banner output: `specfact --no-banner <command>`.
@@ -877,7 +877,7 @@ mv src/pipeline.py src/pipeline_original.py
 mv src/pipeline_broken.py src/pipeline.py
 
 # 3. Import broken code to create new plan
-specfact --no-banner import from-code pipeline-broken --repo . --output-format yaml
+specfact --no-banner code import from-code pipeline-broken --repo . --output-format yaml
 
 # 4. Compare new plan (from broken code) against enriched plan
 specfact --no-banner plan compare \
@@ -902,7 +902,7 @@ mv src/pipeline_original.py src/pipeline.py
 
 **What We've Accomplished**:
 
-1. ✅ Created plan bundle from code (`import from-code`)
+1. ✅ Created plan bundle from code (`code import from-code`)
 2. ✅ Enriched plan with semantic understanding (added FEATURE-DATAPROCESSOR and 4 stories)
 3. ✅ Reviewed plan and improved quality (added target users, value hypothesis, feature acceptance criteria, enhanced story acceptance criteria with Given/When/Then format)
 4. ✅ Configured enforcement (balanced preset with HIGH → BLOCK, MEDIUM → WARN, LOW → LOG)
@@ -973,7 +973,7 @@ def get_user_stats(user_id: str) -> dict:
 **Alternative**: CLI-only mode:
 
 ```bash
-specfact --no-banner import from-code --repo . --output-format yaml
+specfact --no-banner code import from-code --repo . --output-format yaml
 ```
 
 **Note**: Interactive mode creates valid plan bundles with features. CLI-only may show 0 features for minimal test cases. Use `--no-banner` before the command to suppress banner output: `specfact --no-banner <command>`.
@@ -1064,7 +1064,7 @@ This automatically generates `[tool.crosshair]` configuration in `pyproject.toml
 
 **What We've Accomplished**:
 
-1. ✅ Created plan bundle from code (`import from-code`)
+1. ✅ Created plan bundle from code (`code import from-code`)
 2. ✅ Enriched plan with semantic understanding (if using interactive mode)
 3. ✅ Configured enforcement (balanced preset)
 4. ✅ Ran validation suite (`specfact code repro`)
@@ -1143,7 +1143,7 @@ result = process_order(order_id="123")
 **Alternative**: CLI-only mode:
 
 ```bash
-specfact --no-banner import from-code --repo . --output-format yaml
+specfact --no-banner code import from-code --repo . --output-format yaml
 ```
 
 **Important**: After creating the initial plan, we need to make it the default plan so `plan compare --code-vs-plan` can find it. Use `plan select` to set it as the active plan:
@@ -1225,7 +1225,7 @@ Create `.git/hooks/pre-commit`:
 #!/bin/sh
 # First, import current code to create a new plan for comparison
 # Use default name "auto-derived" so plan compare --code-vs-plan can find it
-specfact --no-banner import from-code --repo . --output-format yaml > /dev/null 2>&1
+specfact --no-banner code import from-code --repo . --output-format yaml > /dev/null 2>&1
 
 # Then compare: uses active plan (set via plan select) as manual, latest code-derived plan as auto
 specfact --no-banner plan compare --code-vs-plan
@@ -1243,7 +1243,7 @@ specfact --no-banner plan compare --code-vs-plan
 **Note**: The `--code-vs-plan` flag automatically uses:
 
 - **Manual plan**: The active plan (set via `plan select`) or `main.bundle.yaml` as fallback
-- **Auto plan**: The latest `auto-derived` project bundle (from `import from-code auto-derived` or default bundle name)
+- **Auto plan**: The latest `auto-derived` project bundle (from `code import from-code auto-derived` or default bundle name)
 
 Make it executable:
 
@@ -1320,7 +1320,7 @@ Fix the blocking deviations or adjust enforcement config
 
 **What We've Accomplished**:
 
-1. ✅ Created initial plan bundle from original code (`import from-code`)
+1. ✅ Created initial plan bundle from original code (`code import from-code`)
 2. ✅ Committed the original plan (baseline)
 3. ✅ Modified code to introduce breaking change (added required `user_id` parameter)
 4. ✅ Configured enforcement (balanced preset with HIGH → BLOCK)
@@ -1578,7 +1578,7 @@ rm -rf specfact-integration-tests
 
 **What's Validated**:
 
-- ✅ Plan bundle creation (`import from-code`)
+- ✅ Plan bundle creation (`code import from-code`)
 - ✅ Plan enrichment (LLM adds features and stories)
 - ✅ Plan review (identifies missing items)
 - ✅ Story addition via CLI (`plan add-story`)
@@ -1605,7 +1605,7 @@ rm -rf specfact-integration-tests
 
 **What's Validated**:
 
-- ✅ Plan bundle creation (`import from-code`)
+- ✅ Plan bundle creation (`code import from-code`)
 - ✅ Plan enrichment (LLM adds FEATURE-DATAPROCESSOR and 4 stories)
 - ✅ Plan review (auto-enrichment adds target users, value hypothesis, feature acceptance criteria, enhanced story acceptance criteria)
 - ✅ Enforcement configuration (`enforce stage` with BALANCED preset)
@@ -1627,7 +1627,7 @@ rm -rf specfact-integration-tests
 
 **What's Validated**:
 
-- ✅ Plan bundle creation (`import from-code`)
+- ✅ Plan bundle creation (`code import from-code`)
 - ✅ Plan selection (`plan select` sets active plan)
 - ✅ Enforcement configuration (`enforce stage` with BALANCED preset)
 - ✅ Pre-commit hook setup (imports code, then compares)
@@ -1636,7 +1636,7 @@ rm -rf specfact-integration-tests
 
 **Test Results**:
 
-- Plan creation: ✅ `import from-code <bundle-name>` creates project bundle at `.specfact/projects/<bundle-name>/` (modular structure)
+- Plan creation: ✅ `code import from-code <bundle-name>` creates project bundle at `.specfact/projects/<bundle-name>/` (modular structure)
 - Plan selection: ✅ `plan select` sets active plan correctly
 - Plan comparison: ✅ `plan compare --code-vs-plan` finds:
   - Manual plan: Active plan (set via `plan select`)
@@ -1647,9 +1647,9 @@ rm -rf specfact-integration-tests
 
 **Key Findings**:
 
-- ✅ `import from-code` should use bundle name "auto-derived" so `plan compare --code-vs-plan` can find it
+- ✅ `code import from-code` should use bundle name "auto-derived" so `plan compare --code-vs-plan` can find it
 - ✅ `plan select` is the recommended way to set the baseline plan (cleaner than copying to `main.bundle.yaml`)
-- ✅ Pre-commit hook workflow: `import from-code` → `plan compare --code-vs-plan` works correctly
+- ✅ Pre-commit hook workflow: `code import from-code` → `plan compare --code-vs-plan` works correctly
 - ✅ Enforcement configuration is respected (HIGH → BLOCK based on preset)
 
 **Conclusion**: Example 4 is **fully validated**. The pre-commit hook integration works end-to-end. The hook successfully imports current code, compares it against the active plan, and blocks commits when HIGH severity deviations are detected. The workflow demonstrates how SpecFact prevents breaking changes from being committed locally, before they reach CI/CD.
@@ -1687,7 +1687,7 @@ rm -rf specfact-integration-tests
 Example 5 follows a similar workflow and should be validated using the same approach:
 
 1. Create test files
-2. Create plan bundle (`import from-code`)
+2. Create plan bundle (`code import from-code`)
 3. Enrich plan (if needed)
 4. Review plan and add missing items
 5. Configure enforcement
diff --git a/docs/examples/integration-showcases/integration-showcases.md b/docs/examples/integration-showcases/integration-showcases.md
index 84c3fb9e..cd90b06e 100644
--- a/docs/examples/integration-showcases/integration-showcases.md
+++ b/docs/examples/integration-showcases/integration-showcases.md
@@ -338,7 +338,7 @@ result = process_order(order_id="123")  # ⚠️ Missing user_id
 #!/bin/sh
 # Import current code to create a new plan for comparison
 # Use bundle name "auto-derived" so plan compare --code-vs-plan can find it
-specfact --no-banner import from-code auto-derived --repo . --output-format yaml > /dev/null 2>&1
+specfact --no-banner code import from-code auto-derived --repo . --output-format yaml > /dev/null 2>&1
 
 # Compare: uses active plan (set via plan select) as manual, latest auto-derived plan as auto
 specfact --no-banner plan compare --code-vs-plan
diff --git a/docs/examples/quick-examples.md b/docs/examples/quick-examples.md
index 632816b3..c3ec6c09 100644
--- a/docs/examples/quick-examples.md
+++ b/docs/examples/quick-examples.md
@@ -66,7 +66,7 @@ specfact code import my-project --repo . --confidence 0.7
 specfact code import my-project --repo . --shadow-only
 
 # CoPilot mode (enhanced prompts)
-specfact --mode copilot import from-code my-project --repo . --confidence 0.7
+specfact --mode copilot code import from-code my-project --repo . --confidence 0.7
 
 # Re-validate existing features (force re-analysis)
 specfact code import my-project --repo . --revalidate-features
@@ -200,10 +200,10 @@ specfact init ide --ide cursor --force
 specfact code import my-project --repo .
 
 # Force CI/CD mode
-specfact --mode cicd import from-code my-project --repo .
+specfact --mode cicd code import from-code my-project --repo .
 
 # Force CoPilot mode
-specfact --mode copilot import from-code my-project --repo .
+specfact --mode copilot code import from-code my-project --repo .
 
 # Set via environment variable
 export SPECFACT_MODE=copilot
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index fd7fd47a..ada8d40a 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -353,7 +353,7 @@ specfact code import my-project \
   --report analysis.md
 
 # Analyze with CoPilot mode (enhanced prompts - CLI only, not for IDE)
-specfact --mode copilot import from-code my-project \
+specfact --mode copilot code import from-code my-project \
   --repo ./my-project \
   --confidence 0.7 \
   --report analysis.md
diff --git a/docs/guides/copilot-mode.md b/docs/guides/copilot-mode.md
index d2a40def..ffc3c769 100644
--- a/docs/guides/copilot-mode.md
+++ b/docs/guides/copilot-mode.md
@@ -30,7 +30,7 @@ Mode is auto-detected based on environment, or you can explicitly set it with `-
 
 ```bash
 # Explicitly enable CoPilot mode
-specfact --mode copilot import from-code legacy-api --repo . --confidence 0.7
+specfact --mode copilot code import from-code legacy-api --repo . --confidence 0.7
 
 # Mode is auto-detected based on environment (IDE integration, CoPilot API availability)
 specfact code import legacy-api --repo . --confidence 0.7  # Auto-detects CoPilot if available
@@ -98,10 +98,10 @@ This context is used to generate enhanced prompts that instruct the AI IDE to:
 
 ```bash
 # CI/CD mode (fast, deterministic, Python-only)
-specfact --mode cicd import from-code --repo . --confidence 0.7
+specfact --mode cicd code import from-code --repo . --confidence 0.7
 
 # CoPilot mode (AI-first, semantic understanding, multi-language)
-specfact --mode copilot import from-code --repo . --confidence 0.7
+specfact --mode copilot code import from-code --repo . --confidence 0.7
 
 # Output (CoPilot mode):
 # Mode: CoPilot (AI-first analysis)
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index b25d45de..3998b421 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -135,7 +135,7 @@ specfact project health-check
 4. **Use CoPilot mode** (recommended for brownfield - better semantic understanding):
 
    ```bash
-   specfact --mode copilot import from-code legacy-api --repo . --confidence 0.7
+   specfact --mode copilot code import from-code legacy-api --repo . --confidence 0.7
    ```
 
 5. **For legacy codebases**, start with minimal confidence and review extracted features:
@@ -445,7 +445,7 @@ specfact project health-check
 1. **Use explicit mode**:
 
    ```bash
-   specfact --mode copilot import from-code my-project --repo .
+   specfact --mode copilot code import from-code my-project --repo .
    ```
 
 2. **Check environment variables**:
@@ -477,7 +477,7 @@ specfact project health-check
 1. **Use CI/CD mode** (faster):
 
    ```bash
-   specfact --mode cicd import from-code my-project --repo .
+   specfact --mode cicd code import from-code my-project --repo .
    ```
 
 2. **Increase confidence threshold** (fewer features):
diff --git a/docs/guides/use-cases.md b/docs/guides/use-cases.md
index 193b3289..13f32e2d 100644
--- a/docs/guides/use-cases.md
+++ b/docs/guides/use-cases.md
@@ -46,7 +46,7 @@ specfact code import \
   --report analysis-core.md
 
 # CoPilot mode (enhanced prompts, interactive)
-specfact --mode copilot import from-code \
+specfact --mode copilot code import from-code \
   --repo . \
   --confidence 0.7 \
   --report analysis.md
diff --git a/openspec/changes/docs-new-user-onboarding/specs/module-installation/spec.md b/openspec/changes/docs-new-user-onboarding/specs/module-installation/spec.md
index be57402f..d3e1e002 100644
--- a/openspec/changes/docs-new-user-onboarding/specs/module-installation/spec.md
+++ b/openspec/changes/docs-new-user-onboarding/specs/module-installation/spec.md
@@ -11,10 +11,25 @@ The upgrade output SHALL distinguish between modules that were actually upgraded
 and modules that were already at the latest version. Showing `0.41.16 -> 0.41.16` when no version
 change occurred is incorrect and SHALL NOT happen.
 
+While the registry index is being fetched or a module is being installed, the CLI SHALL show visible
+progress (for example a Rich status spinner) so the user knows work is ongoing. Rich progress MAY
+be suppressed in automated test environments.
+
 Before upgrading any module where the latest registry version has a higher major version than the
 installed version, the CLI SHALL warn the user and require confirmation, because major version
 bumps may contain breaking changes.
 
+#### Scenario: Upgrade shows progress during registry fetch and install
+
+- **WHEN** user runs `specfact module upgrade` and the registry fetch or an install takes noticeable time
+- **THEN** the CLI SHALL show visible progress during fetch and during each module install
+
+#### Scenario: Upgrade warns when registry index is unavailable
+
+- **WHEN** the registry index cannot be fetched (offline or network error)
+- **THEN** the CLI SHALL print a clear warning that the registry is unavailable
+- **AND** SHALL continue using installed metadata where possible for the upgrade decision
+
 #### Scenario: Upgrade a single named module to a newer minor/patch version
 
 - **WHEN** user runs `specfact module upgrade backlog` and `0.42.0` is available (current `0.41.16`)
diff --git a/pyproject.toml b/pyproject.toml
index 9527bb9b..3665ae77 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -64,7 +64,8 @@ dependencies = [
     # PEP 440 / markers for module installer and registry (do not rely on transitive pins only)
 
     # CLI framework
-    "typer>=0.20.0",
+    # Typer 0.24+ requires click>=8.2.1 (generic Choice[...]); dev semgrep pins click~=8.1.8 — cap Typer.
+    "typer>=0.20.0,<0.24",
     "rich>=13.5.2,<13.6.0",  # Compatible with semgrep (requires rich~=13.5.2)
     "questionary>=2.0.1",  # Interactive prompts with arrow key navigation
     
@@ -103,6 +104,7 @@ contracts = [
 ]
 
 dev = [
+    "setuptools>=69.0.0",
     "pytest>=8.4.2",
     "pytest-cov>=7.0.0",
     "pytest-mock>=3.15.1",
@@ -170,6 +172,8 @@ specfact-cli = "specfact_cli.cli:cli_main"  # Alias for uvx compatibility
 [tool.hatch.envs.default]
 python = "3.12"
 dependencies = [
+    # Semgrep pulls opentelemetry; some versions import pkg_resources (setuptools)
+    "setuptools>=69.0.0",
     "pip-tools",
     "pytest",
     "pytest-cov",
@@ -208,6 +212,9 @@ governance = "pylint src tests tools --reports=y --output-format=parseable"
 format = "ruff check . --fix && ruff format ."
 
 # Code scanning (Semgrep)
+# Semgrep 1.38+ deprecated implicit .semgrep.yml discovery; always pass --config explicitly.
+# Script must not be named `semgrep` (Hatch treats that as circular expansion with the semgrep CLI).
+semgrep-full = "semgrep --config tools/semgrep {args}"
 scan = "semgrep --config tools/semgrep/async.yml {args}"
 scan-all = "semgrep --config tools/semgrep/async.yml ."
 scan-json = "semgrep --config tools/semgrep/async.yml --json . > logs/semgrep-results.json"
diff --git a/setup.py b/setup.py
index 974b79a0..8a34c4ed 100644
--- a/setup.py
+++ b/setup.py
@@ -22,7 +22,7 @@
             "azure-identity>=1.17.1",
             "cryptography>=43.0.0",
             "packaging>=24.0",
-            "typer>=0.20.0",
+            "typer>=0.20.0,<0.24",
             "rich>=13.5.2,<13.6.0",
             "questionary>=2.0.1",
             "jinja2>=3.1.6",
diff --git a/src/specfact_cli/cli.py b/src/specfact_cli/cli.py
index e8a99444..15a9b2de 100644
--- a/src/specfact_cli/cli.py
+++ b/src/specfact_cli/cli.py
@@ -6,12 +6,15 @@
 
 from __future__ import annotations
 
+import importlib
+import inspect
 import os
 import sys
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
-from typing import Annotated, cast
+from typing import Annotated, Any, cast
 
 
 _DetectShellFn = Callable[..., tuple[str | None, str | None]]
@@ -88,12 +91,12 @@ def _normalized_detect_shell(pid: int | None = None, max_depth: int = 10) -> tup
         "drift",
         "analyze",
         "policy",
-        "import",
         "sync",
     }
 )
 
 # First token -> official marketplace module that provides it (not the VS Code `code` CLI).
+# Codebase import is `specfact code import`; persona Markdown import is `specfact project import` (not flat).
 _INVOKED_TO_MARKETPLACE_MODULE: dict[str, str] = {
     "backlog": "nold-ai/specfact-backlog",
     "policy": "nold-ai/specfact-backlog",
@@ -102,7 +105,6 @@ def _normalized_detect_shell(pid: int | None = None, max_depth: int = 10) -> tup
     "drift": "nold-ai/specfact-codebase",
     "validate": "nold-ai/specfact-codebase",
     "repro": "nold-ai/specfact-codebase",
-    "import": "nold-ai/specfact-codebase",
     "project": "nold-ai/specfact-project",
     "plan": "nold-ai/specfact-project",
     "sync": "nold-ai/specfact-project",
@@ -317,9 +319,101 @@ def get_current_mode() -> OperationalMode:
     return _current_mode
 
 
-@app.callback(invoke_without_command=True)
-@require(lambda ctx: ctx is not None, "ctx must not be None")
-def main(
+@dataclass
+class _RootCliFlags:
+    """Bundled root callback options (keeps the Typer callback body small for radon-kiss)."""
+
+    version: bool | None
+    banner: bool
+    mode: str | None
+    debug: bool
+    skip_checks: bool
+    input_format: StructuredFormat
+    output_format: StructuredFormat
+    interaction: bool | None
+
+
+_ROOT_MAIN_DOC = """
+SpecFact CLI - Spec→Contract→Sentinel for contract-driven development.
+
+Transform your development workflow with automated quality gates,
+runtime contract validation, and state machine workflows.
+
+Run **specfact init** or **specfact module install** to add workflow bundles
+(backlog, code, project, spec, govern).
+
+**Backlog Management**: Use `specfact backlog refine` for AI-assisted template-driven
+refinement of backlog items from GitHub Issues, Azure DevOps, and other tools.
+
+Mode Detection:
+- Explicit --mode flag (highest priority)
+- Auto-detect from environment (CoPilot API, IDE integration)
+- Default to CI/CD mode
+
+Interaction Detection:
+- Explicit --interactive/--no-interactive (highest priority)
+- Auto-detect from terminal and CI environment
+"""
+
+
+def _apply_root_app_callback(ctx: typer.Context, flags: _RootCliFlags) -> None:
+    global _show_banner
+    global console
+
+    # Rebind root and loaded module consoles for each invocation to avoid stale
+    # closed capture streams across sequential CliRunner/pytest command runs.
+    console = get_configured_console()
+    runtime.refresh_loaded_module_consoles()
+
+    # Set banner flag based on --banner option
+    _show_banner = flags.banner
+
+    # Set debug mode
+    set_debug_mode(flags.debug)
+    if flags.debug:
+        init_debug_log_file()
+
+    runtime.configure_io_formats(input_format=flags.input_format, output_format=flags.output_format)
+    # Invert logic: --interactive means not non-interactive, --no-interactive means non-interactive
+    if flags.interaction is not None:
+        runtime.set_non_interactive_override(not flags.interaction)
+    else:
+        runtime.set_non_interactive_override(None)
+
+    # Show welcome message if no command provided
+    if ctx.invoked_subcommand is None:
+        console.print(
+            Panel.fit(
+                "[bold green]✓[/bold green] SpecFact CLI is installed and working!\n\n"
+                f"Version: [cyan]{__version__}[/cyan]\n"
+                "Run [bold]specfact --help[/bold] for available commands.",
+                title="[bold]Welcome to SpecFact CLI[/bold]",
+                border_style="green",
+            )
+        )
+        raise typer.Exit()
+
+    # Store mode in context for commands to access
+    if ctx.obj is None:
+        ctx.obj = {}
+    ctx.obj["mode"] = get_current_mode()
+
+
+def _root_cli_flags_from_kwargs(kwargs: Mapping[str, Any]) -> _RootCliFlags:
+    """Build flags from Typer callback kwargs (param names match merged root CLI signature)."""
+    return _RootCliFlags(
+        version=kwargs.get("version"),
+        banner=kwargs.get("banner", False),
+        mode=kwargs.get("mode"),
+        debug=kwargs.get("debug", False),
+        skip_checks=kwargs.get("skip_checks", False),
+        input_format=kwargs.get("input_format", StructuredFormat.YAML),
+        output_format=kwargs.get("output_format", StructuredFormat.YAML),
+        interaction=kwargs.get("interaction"),
+    )
+
+
+def _root_sig_part1(
     ctx: typer.Context,
     version: bool | None = typer.Option(
         None,
@@ -340,6 +434,11 @@ def main(
         callback=mode_callback,
         help="Operational mode: cicd (fast, deterministic) or copilot (enhanced, interactive)",
     ),
+) -> None:
+    """Typer param signature fragment (merged for root callback); not invoked at runtime."""
+
+
+def _root_sig_part2(
     debug: bool = typer.Option(
         False,
         "--debug",
@@ -366,6 +465,11 @@ def main(
             case_sensitive=False,
         ),
     ] = StructuredFormat.YAML,
+) -> None:
+    """Typer param signature fragment (merged for root callback); not invoked at runtime."""
+
+
+def _root_sig_part3(
     interaction: Annotated[
         bool | None,
         typer.Option(
@@ -374,67 +478,25 @@ def main(
         ),
     ] = None,
 ) -> None:
-    """
-    SpecFact CLI - Spec→Contract→Sentinel for contract-driven development.
+    """Typer param signature fragment (merged for root callback); not invoked at runtime."""
 
-    Transform your development workflow with automated quality gates,
-    runtime contract validation, and state machine workflows.
 
-    Run **specfact init** or **specfact module install** to add workflow bundles
-    (backlog, code, project, spec, govern).
+def _merge_root_cli_param_specs(orig: Callable[..., Any]) -> dict[str, Any]:
+    merged: dict[str, Any] = {}
+    merged.update(orig(_root_sig_part1))
+    merged.update(orig(_root_sig_part2))
+    merged.update(orig(_root_sig_part3))
+    return merged
 
-    **Backlog Management**: Use `specfact backlog refine` for AI-assisted template-driven
-    refinement of backlog items from GitHub Issues, Azure DevOps, and other tools.
-
-    Mode Detection:
-    - Explicit --mode flag (highest priority)
-    - Auto-detect from environment (CoPilot API, IDE integration)
-    - Default to CI/CD mode
-
-    Interaction Detection:
-    - Explicit --interactive/--no-interactive (highest priority)
-    - Auto-detect from terminal and CI environment
-    """
-    global _show_banner
-    global console
-
-    # Rebind root and loaded module consoles for each invocation to avoid stale
-    # closed capture streams across sequential CliRunner/pytest command runs.
-    console = get_configured_console()
-    runtime.refresh_loaded_module_consoles()
-
-    # Set banner flag based on --banner option
-    _show_banner = banner
-
-    # Set debug mode
-    set_debug_mode(debug)
-    if debug:
-        init_debug_log_file()
 
-    runtime.configure_io_formats(input_format=input_format, output_format=output_format)
-    # Invert logic: --interactive means not non-interactive, --no-interactive means non-interactive
-    if interaction is not None:
-        runtime.set_non_interactive_override(not interaction)
-    else:
-        runtime.set_non_interactive_override(None)
+@app.callback(invoke_without_command=True)
+@require(lambda ctx: ctx is not None, "ctx must not be None")
+def main(ctx: typer.Context, **kwargs) -> None:
+    """SpecFact CLI root callback (full help text in _ROOT_MAIN_DOC)."""
+    _apply_root_app_callback(ctx, _root_cli_flags_from_kwargs(kwargs))
 
-    # Show welcome message if no command provided
-    if ctx.invoked_subcommand is None:
-        console.print(
-            Panel.fit(
-                "[bold green]✓[/bold green] SpecFact CLI is installed and working!\n\n"
-                f"Version: [cyan]{__version__}[/cyan]\n"
-                "Run [bold]specfact --help[/bold] for available commands.",
-                title="[bold]Welcome to SpecFact CLI[/bold]",
-                border_style="green",
-            )
-        )
-        raise typer.Exit()
 
-    # Store mode in context for commands to access
-    if ctx.obj is None:
-        ctx.obj = {}
-    ctx.obj["mode"] = get_current_mode()
+main.__doc__ = inspect.cleandoc(_ROOT_MAIN_DOC)
 
 
 # Register command groups from CommandRegistry (bootstrap preserves display order).
@@ -636,24 +698,54 @@ def _get_group_from_info_wrapper(
 # Original Typer build functions (set once by _patch_typer_build so re-import of cli doesn't overwrite with our wrapper).
 _typer_get_group_from_info_original: Callable[..., click.Group] | None = None
 _typer_get_command_original: Callable[[typer.Typer], click.Command] | None = None
+_typer_get_params_original: Callable[..., Any] | None = None
+
+
+def _specfact_get_params_from_function(func: Callable[..., Any]) -> Any:
+    """Map thin Typer entrypoints to their option-rich implementations for Click param generation."""
+    orig = _typer_get_params_original
+    if orig is None:
+        import typer.utils as typer_utils
+
+        return typer_utils.get_params_from_function(func)
+    # ``@app.callback()`` / ``@app.command()`` may wrap the function; match by name + module.
+    if getattr(func, "__name__", "") == "main" and getattr(func, "__module__", "") == __name__:
+        return _merge_root_cli_param_specs(orig)
+    if (
+        getattr(func, "__name__", "") == "install"
+        and getattr(func, "__module__", "") == "specfact_cli.modules.module_registry.src.commands"
+    ):
+        module = sys.modules.get("specfact_cli.modules.module_registry.src.commands")
+        if module is not None:
+            merge_install = getattr(module, "_specfact_merge_install_param_specs", None)
+            if merge_install is not None:
+                return merge_install(orig)
+    return orig(func)
 
 
 # Patch so root app build uses our delegate group for lazy typers (built via get_group_from_info).
 def _patch_typer_build() -> None:
-    import typer.main as typer_main
+    import typer.utils as typer_utils
 
-    global _typer_get_group_from_info_original, _typer_get_command_original
+    typer_main = cast(Any, importlib.import_module("typer.main"))
+
+    global _typer_get_group_from_info_original, _typer_get_command_original, _typer_get_params_original
     # Save originals only on first patch; avoid overwriting with our wrapper when cli is re-imported (e.g. by plan module).
     if _typer_get_group_from_info_original is None:
         _typer_get_group_from_info_original = typer_main.get_group_from_info
     if _typer_get_command_original is None:
         _typer_get_command_original = typer_main.get_command
+    if _typer_get_params_original is None:
+        _typer_get_params_original = typer_utils.get_params_from_function
+    typer_utils.get_params_from_function = _specfact_get_params_from_function
+    # typer.main may have bound get_params_from_function at import time; keep in sync.
+    typer_main.get_params_from_function = _specfact_get_params_from_function
     typer_main.get_command = _get_command
     typer_main.get_group_from_info = _get_group_from_info_wrapper
 
 
-register_builtin_commands()
 _patch_typer_build()
+register_builtin_commands()
 
 
 def _grouped_command_order(
diff --git a/src/specfact_cli/modules/init/module-package.yaml b/src/specfact_cli/modules/init/module-package.yaml
index e1bfdb1c..aa9347f6 100644
--- a/src/specfact_cli/modules/init/module-package.yaml
+++ b/src/specfact_cli/modules/init/module-package.yaml
@@ -1,5 +1,5 @@
 name: init
-version: 0.1.23
+version: 0.1.24
 commands:
   - init
 category: core
@@ -17,5 +17,5 @@ publisher:
 description: Initialize SpecFact workspace and bootstrap local configuration.
 license: Apache-2.0
 integrity:
-  checksum: sha256:a0a7a9eac6b7407ee8dd08f151b18ecd8b9ff7a263d3adfce3aaa99dfb369c04
-  signature: +Lr8H1Fo3NbjPlOi9G0/a3v8eCkDcFZ33TbC8l9p6IpzGda9nYA47rbBgyklBAauXDEl2k8TRZcMFrECXg5BDw==
+  checksum: sha256:eec17e6377c9a4a9d0abc4c3da81069d729ff4394b277016f5428d2e798ab1ef
+  signature: FLs/jr95lBtXCawAzBK08xb0LCPl/veYsSZMhq11KU+11ieyIg8j/GosyCOrpUsTKjb3j3xfZv1MmjERHn7mDg==
diff --git a/src/specfact_cli/modules/init/src/first_run_selection.py b/src/specfact_cli/modules/init/src/first_run_selection.py
index 7c72d9d9..7bc7e0e1 100644
--- a/src/specfact_cli/modules/init/src/first_run_selection.py
+++ b/src/specfact_cli/modules/init/src/first_run_selection.py
@@ -3,7 +3,9 @@
 from __future__ import annotations
 
 import os
+from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
 
 from beartype import beartype
 from icontract import ensure, require
@@ -36,7 +38,13 @@
 # Includes marketplace-only bundles referenced by profiles (e.g. specfact-code-review).
 CANONICAL_BUNDLES: tuple[str, ...] = (*_INSTALL_ALL_BUNDLES, "specfact-code-review")
 
+# Workflow bundles are installed from the marketplace (slim wheel has no per-command shims under ~/.specfact/modules).
 MARKETPLACE_ONLY_BUNDLES: dict[str, str] = {
+    "specfact-project": "nold-ai/specfact-project",
+    "specfact-backlog": "nold-ai/specfact-backlog",
+    "specfact-codebase": "nold-ai/specfact-codebase",
+    "specfact-spec": "nold-ai/specfact-spec",
+    "specfact-govern": "nold-ai/specfact-govern",
     "specfact-code-review": "nold-ai/specfact-code-review",
 }
 
@@ -49,12 +57,14 @@
     "govern": "specfact-govern",
 }
 
+# Optional: names of *bundled* module dirs shipped inside this CLI wheel (see module_installer). Workflow
+# bundles use MARKETPLACE_ONLY_BUNDLES only — do not list Typer subcommand names here.
 BUNDLE_TO_MODULE_NAMES: dict[str, list[str]] = {
-    "specfact-project": ["project", "plan", "import_cmd", "sync", "migrate"],
-    "specfact-backlog": ["backlog", "policy_engine"],
-    "specfact-codebase": ["analyze", "drift", "validate", "repro"],
-    "specfact-spec": ["contract", "spec", "sdd", "generate"],
-    "specfact-govern": ["enforce", "patch_mode"],
+    "specfact-project": [],
+    "specfact-backlog": [],
+    "specfact-codebase": [],
+    "specfact-spec": [],
+    "specfact-govern": [],
     "specfact-code-review": [],
 }
 
@@ -78,6 +88,145 @@ def _emit_init_bundle_progress() -> bool:
     return os.environ.get("PYTEST_CURRENT_TEST") is None
 
 
+def _expand_bundle_install_order(bundle_ids: list[str]) -> list[str]:
+    to_install: list[str] = []
+    seen: set[str] = set()
+
+    def _add_bundle(bid: str) -> None:
+        if bid in seen:
+            return
+        for dep in BUNDLE_DEPENDENCIES.get(bid, []):
+            _add_bundle(dep)
+        seen.add(bid)
+        to_install.append(bid)
+
+    for bid in bundle_ids:
+        if bid not in CANONICAL_BUNDLES:
+            continue
+        _add_bundle(bid)
+    return to_install
+
+
+@dataclass
+class _InitBundleInstallDeps:
+    root: Path
+    trust_non_official: bool
+    non_interactive: bool
+    emit: bool
+    console: Any
+    install_bundled_module: Any
+    install_module: Any
+
+
+def _emit_bundle_row_header(
+    bid: str,
+    deps: _InitBundleInstallDeps,
+    *,
+    module_names: list[str],
+    bundle_label: str,
+    marketplace_id: str | None,
+) -> None:
+    if not deps.emit:
+        return
+    if module_names or marketplace_id:
+        deps.console.print(f"[cyan]→[/cyan] Bundle [bold]{bid}[/bold] — {bundle_label}")
+    else:
+        deps.console.print(
+            f"[yellow]→[/yellow] Bundle [bold]{bid}[/bold] has no bundled modules in this CLI; "
+            f"install with [bold]specfact module install nold-ai/{bid}[/bold] when online."
+        )
+
+
+def _install_one_bundled_module_line(bid: str, module_name: str, deps: _InitBundleInstallDeps) -> None:
+    from specfact_cli.common import get_bridge_logger
+
+    if deps.emit:
+        deps.console.print(f"[dim]   ·[/dim] Installing module [bold]{module_name}[/bold] …")
+    try:
+        installed = deps.install_bundled_module(
+            module_name,
+            deps.root,
+            trust_non_official=deps.trust_non_official,
+            non_interactive=deps.non_interactive,
+        )
+    except Exception as e:
+        logger = get_bridge_logger(__name__)
+        logger.warning(
+            "Bundle install failed for %s: %s. Dependency resolver may be unavailable.",
+            module_name,
+            e,
+        )
+        if deps.emit:
+            deps.console.print(
+                f"[red]✗[/red] Failed on module [bold]{module_name}[/bold] from bundle [bold]{bid}[/bold]: {e}"
+            )
+            deps.console.print(
+                "[dim]  Check disk space and permissions under ~/.specfact/modules, "
+                "or retry if a transient I/O error.[/dim]"
+            )
+        raise
+    if installed:
+        if deps.emit:
+            deps.console.print(f"[green]   ✓[/green] {module_name} ready")
+    elif deps.emit:
+        deps.console.print(
+            f"[yellow]   ⚠[/yellow] {module_name} is not bundled in this CLI build; "
+            f"try [bold]specfact module install nold-ai/{bid}[/bold] when online."
+        )
+
+
+def _install_marketplace_for_bundle(bid: str, marketplace_id: str, deps: _InitBundleInstallDeps) -> None:
+    from specfact_cli.common import get_bridge_logger
+
+    if deps.emit:
+        deps.console.print(f"[dim]   ·[/dim] Installing marketplace module [bold]{marketplace_id}[/bold] …")
+    try:
+        deps.install_module(
+            marketplace_id,
+            install_root=deps.root,
+            non_interactive=deps.non_interactive,
+            trust_non_official=deps.trust_non_official,
+        )
+    except Exception as e:
+        logger = get_bridge_logger(__name__)
+        logger.warning(
+            "Marketplace bundle install failed for %s: %s.",
+            marketplace_id,
+            e,
+        )
+        if deps.emit:
+            deps.console.print(
+                f"[red]✗[/red] Failed on marketplace module [bold]{marketplace_id}[/bold] "
+                f"from bundle [bold]{bid}[/bold]: {e}"
+            )
+            deps.console.print(
+                "[dim]  Check network access and permissions under ~/.specfact/modules, "
+                "or retry if a transient error.[/dim]"
+            )
+        raise
+    if deps.emit:
+        deps.console.print(f"[green]   ✓[/green] {marketplace_id.split('/', 1)[1]} ready")
+
+
+def _process_one_bundle_install_row(bid: str, deps: _InitBundleInstallDeps) -> None:
+    """Install bundled and/or marketplace modules for one canonical bundle id."""
+    module_names = BUNDLE_TO_MODULE_NAMES.get(bid, [])
+    bundle_label = BUNDLE_DISPLAY.get(bid, bid)
+    marketplace_id = MARKETPLACE_ONLY_BUNDLES.get(bid)
+    _emit_bundle_row_header(
+        bid,
+        deps,
+        module_names=module_names,
+        bundle_label=bundle_label,
+        marketplace_id=marketplace_id,
+    )
+    for module_name in module_names:
+        _install_one_bundled_module_line(bid, module_name, deps)
+    if not marketplace_id:
+        return
+    _install_marketplace_for_bundle(bid, marketplace_id, deps)
+
+
 @require(lambda profile: isinstance(profile, str) and profile.strip() != "", "profile must be non-empty string")
 @ensure(lambda result: isinstance(result, list), "result must be list of bundle ids")
 @beartype
@@ -160,23 +309,18 @@ def install_bundles_for_init(
     )
 
     root = install_root or DEFAULT_ROOT
-    to_install: list[str] = []
-    seen: set[str] = set()
     emit = show_progress and _emit_init_bundle_progress()
     console = Console()
-
-    def _add_bundle(bid: str) -> None:
-        if bid in seen:
-            return
-        for dep in BUNDLE_DEPENDENCIES.get(bid, []):
-            _add_bundle(dep)
-        seen.add(bid)
-        to_install.append(bid)
-
-    for bid in bundle_ids:
-        if bid not in CANONICAL_BUNDLES:
-            continue
-        _add_bundle(bid)
+    to_install = _expand_bundle_install_order(bundle_ids)
+    deps = _InitBundleInstallDeps(
+        root=root,
+        trust_non_official=trust_non_official,
+        non_interactive=non_interactive,
+        emit=emit,
+        console=console,
+        install_bundled_module=install_bundled_module,
+        install_module=install_module,
+    )
 
     if emit and to_install:
         bundle_list = ", ".join(to_install)
@@ -184,84 +328,7 @@ def _add_bundle(bid: str) -> None:
         console.print("[dim]  (copying bundled modules into your user module directory)[/dim]")
 
     for bid in to_install:
-        module_names = BUNDLE_TO_MODULE_NAMES.get(bid, [])
-        bundle_label = BUNDLE_DISPLAY.get(bid, bid)
-        marketplace_id = MARKETPLACE_ONLY_BUNDLES.get(bid)
-        if emit:
-            if module_names or marketplace_id:
-                console.print(f"[cyan]→[/cyan] Bundle [bold]{bid}[/bold] — {bundle_label}")
-            else:
-                console.print(
-                    f"[yellow]→[/yellow] Bundle [bold]{bid}[/bold] has no bundled modules in this CLI; "
-                    f"install with [bold]specfact module install nold-ai/{bid}[/bold] when online."
-                )
-        for module_name in module_names:
-            if emit:
-                console.print(f"[dim]   ·[/dim] Installing module [bold]{module_name}[/bold] …")
-            try:
-                installed = install_bundled_module(
-                    module_name,
-                    root,
-                    trust_non_official=trust_non_official,
-                    non_interactive=non_interactive,
-                )
-            except Exception as e:
-                from specfact_cli.common import get_bridge_logger
-
-                logger = get_bridge_logger(__name__)
-                logger.warning(
-                    "Bundle install failed for %s: %s. Dependency resolver may be unavailable.",
-                    module_name,
-                    e,
-                )
-                if emit:
-                    console.print(
-                        f"[red]✗[/red] Failed on module [bold]{module_name}[/bold] from bundle [bold]{bid}[/bold]: {e}"
-                    )
-                    console.print(
-                        "[dim]  Check disk space and permissions under ~/.specfact/modules, "
-                        "or retry if a transient I/O error.[/dim]"
-                    )
-                raise
-            if installed:
-                if emit:
-                    console.print(f"[green]   ✓[/green] {module_name} ready")
-            elif emit:
-                console.print(
-                    f"[yellow]   ⚠[/yellow] {module_name} is not bundled in this CLI build; "
-                    f"try [bold]specfact module install nold-ai/{bid}[/bold] when online."
-                )
-        if marketplace_id:
-            if emit:
-                console.print(f"[dim]   ·[/dim] Installing marketplace module [bold]{marketplace_id}[/bold] …")
-            try:
-                install_module(
-                    marketplace_id,
-                    install_root=root,
-                    non_interactive=non_interactive,
-                    trust_non_official=trust_non_official,
-                )
-            except Exception as e:
-                from specfact_cli.common import get_bridge_logger
-
-                logger = get_bridge_logger(__name__)
-                logger.warning(
-                    "Marketplace bundle install failed for %s: %s.",
-                    marketplace_id,
-                    e,
-                )
-                if emit:
-                    console.print(
-                        f"[red]✗[/red] Failed on marketplace module [bold]{marketplace_id}[/bold] "
-                        f"from bundle [bold]{bid}[/bold]: {e}"
-                    )
-                    console.print(
-                        "[dim]  Check network access and permissions under ~/.specfact/modules, "
-                        "or retry if a transient error.[/dim]"
-                    )
-                raise
-            if emit:
-                console.print(f"[green]   ✓[/green] {marketplace_id.split('/', 1)[1]} ready")
+        _process_one_bundle_install_row(bid, deps)
 
     if emit and to_install:
         console.print(f"[green]✓[/green] Installed: {', '.join(to_install)}")
diff --git a/src/specfact_cli/modules/module_registry/module-package.yaml b/src/specfact_cli/modules/module_registry/module-package.yaml
index 4750280d..c0cf77ba 100644
--- a/src/specfact_cli/modules/module_registry/module-package.yaml
+++ b/src/specfact_cli/modules/module_registry/module-package.yaml
@@ -1,5 +1,5 @@
 name: module-registry
-version: 0.1.15
+version: 0.1.17
 commands:
   - module
 category: core
@@ -17,5 +17,5 @@ publisher:
 description: 'Manage modules: search, list, show, install, and upgrade.'
 license: Apache-2.0
 integrity:
-  checksum: sha256:b4628edc05c19e73ae7148dcbfa62edec29f2dc9eab6d1d496274449246065cb
-  signature: f5jHpyzf+/ZK2mweUkAHzca110RtEgGk+wplafFqV/WzpKZ2B31dGWc4k8VxGC4wm6Bvrz0HTFkSla95P/F2Dw==
+  checksum: sha256:9a16aa56293e9da54f6a6e11a7d596ffe254fab0fe23658966f606dba27abf94
+  signature: LuwmQRpXtdH4GeKsT7cjm4TTNwnky2sVwuuFYoEzeh+V8BsBdjm4wm7WTTQMK5+KCy0q8erayaj4FOSiYRJcAQ==
diff --git a/src/specfact_cli/modules/module_registry/src/commands.py b/src/specfact_cli/modules/module_registry/src/commands.py
index 19ffc96d..709ec896 100644
--- a/src/specfact_cli/modules/module_registry/src/commands.py
+++ b/src/specfact_cli/modules/module_registry/src/commands.py
@@ -3,7 +3,11 @@
 from __future__ import annotations
 
 import inspect
+import os
 import shutil
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Annotated, Any, cast
 
@@ -46,24 +50,39 @@
 console = Console()
 
 
+def _module_upgrade_show_spinner() -> bool:
+    """Rich Live/spinner breaks some tests; mirror ``utils.progress`` test-mode detection."""
+    return os.environ.get("TEST_MODE") != "true" and os.environ.get("PYTEST_CURRENT_TEST") is None
+
+
+@contextmanager
+def _module_upgrade_status(description: str) -> Iterator[None]:
+    """Show a Rich status spinner during long-running upgrade steps (fetch, install)."""
+    if _module_upgrade_show_spinner():
+        with console.status(description, spinner="dots"):
+            yield
+    else:
+        yield
+
+
 def _init_scope_nonempty(scope: str) -> bool:
     return bool(scope)
 
 
-def _module_id_arg_nonempty(module_id: str) -> bool:
-    return bool(module_id.strip())
+def _strip_nonempty(s: str) -> bool:
+    return bool(s.strip())
 
 
 def _module_name_arg_nonempty(module_name: str) -> bool:
-    return bool(module_name.strip())
+    return _strip_nonempty(module_name)
 
 
 def _alias_name_nonempty(alias_name: str) -> bool:
-    return bool(alias_name.strip())
+    return _strip_nonempty(alias_name)
 
 
 def _command_name_nonempty(command_name: str) -> bool:
-    return bool(command_name.strip())
+    return _strip_nonempty(command_name)
 
 
 def _url_nonempty(url: str) -> bool:
@@ -71,15 +90,15 @@ def _url_nonempty(url: str) -> bool:
 
 
 def _registry_id_nonempty(registry_id: str) -> bool:
-    return registry_id.strip() != ""
+    return _strip_nonempty(registry_id)
 
 
-def _module_id_optional_nonempty(module_id: str | None) -> bool:
-    return module_id is None or module_id.strip() != ""
+def _search_query_nonempty(query: str) -> bool:
+    return _strip_nonempty(query)
 
 
-def _search_query_nonempty(query: str) -> bool:
-    return bool(query.strip())
+def _module_id_optional_nonempty(module_id: str | None) -> bool:
+    return module_id is None or module_id.strip() != ""
 
 
 def _list_source_filter_ok(source: str | None) -> bool:
@@ -249,34 +268,48 @@ def init_modules(
     console.print(f"[green]Seeded {seeded} module(s) into {target_root}[/green]")
 
 
-def _install_one(
-    module_id: str,
-    scope_normalized: str,
-    source_normalized: str,
-    target_root: Path,
-    version: str | None,
-    reinstall: bool,
-    trust_non_official: bool,
-    skip_deps: bool,
-    force: bool,
-    discovered_by_name: dict[str, Any],
-) -> bool:
+@dataclass(frozen=True)
+class _InstallOneParams:
+    scope_normalized: str
+    source_normalized: str
+    target_root: Path
+    version: str | None
+    reinstall: bool
+    trust_non_official: bool
+    skip_deps: bool
+    force: bool
+    discovered_by_name: dict[str, Any]
+
+
+def _install_one(module_id: str, params: _InstallOneParams) -> bool:
     """Install a single module; return True on success, False if skipped/already installed."""
     normalized, requested_name = _normalize_install_module_id(module_id)
-    if _install_skip_if_already_satisfied(scope_normalized, requested_name, target_root, reinstall, discovered_by_name):
+    if _install_skip_if_already_satisfied(
+        params.scope_normalized,
+        requested_name,
+        params.target_root,
+        params.reinstall,
+        params.discovered_by_name,
+    ):
         return True
-    if _try_install_bundled_module(source_normalized, requested_name, normalized, target_root, trust_non_official):
+    if _try_install_bundled_module(
+        params.source_normalized,
+        requested_name,
+        normalized,
+        params.target_root,
+        params.trust_non_official,
+    ):
         return True
     try:
         installed_path = install_module(
             normalized,
-            version=version,
-            reinstall=reinstall,
-            install_root=target_root,
-            trust_non_official=trust_non_official,
+            version=params.version,
+            reinstall=params.reinstall,
+            install_root=params.target_root,
+            trust_non_official=params.trust_non_official,
             non_interactive=is_non_interactive(),
-            skip_deps=skip_deps,
-            force=force,
+            skip_deps=params.skip_deps,
+            force=params.force,
         )
     except Exception as exc:
         console.print(f"[red]Failed installing {normalized}: {exc}[/red]")
@@ -288,10 +321,7 @@ def _install_one(
     return True
 
 
-@app.command()
-@require(_install_module_ids_nonempty, "at least one non-blank module id is required")
-@beartype
-def install(
+def _install_sig_part1(
     module_ids: Annotated[
         list[str],
         typer.Argument(help="Module id(s) (name or namespace/name); space-separated for multiple"),
@@ -299,6 +329,11 @@ def install(
     version: str | None = typer.Option(None, "--version", help="Install a specific version (single module only)"),
     scope: str = typer.Option("user", "--scope", help="Install scope: user or project"),
     source: str = typer.Option("auto", "--source", help="Install source: auto, bundled, or marketplace"),
+) -> None:
+    """Typer param signature fragment (merged for install); not invoked at runtime."""
+
+
+def _install_sig_part2(
     repo: Path | None = typer.Option(None, "--repo", help="Repository path for project scope (default: current dir)"),
     trust_non_official: bool = typer.Option(
         False,
@@ -315,13 +350,39 @@ def install(
         "--force",
         help="Force install even if dependency resolution reports conflicts",
     ),
+) -> None:
+    """Typer param signature fragment (merged for install); not invoked at runtime."""
+
+
+def _install_sig_part3(
     reinstall: bool = typer.Option(
         False,
         "--reinstall",
         help="Reinstall even if module is already present (e.g. to refresh integrity metadata)",
     ),
 ) -> None:
+    """Typer param signature fragment (merged for install); not invoked at runtime."""
+
+
+def _specfact_merge_install_param_specs(orig: Callable[..., Any]) -> dict[str, Any]:
+    merged: dict[str, Any] = {}
+    merged.update(orig(_install_sig_part1))
+    merged.update(orig(_install_sig_part2))
+    merged.update(orig(_install_sig_part3))
+    return merged
+
+
+@beartype
+def _install_impl(module_ids: list[str], **kwargs: Any) -> None:
     """Install one or more modules from bundled artifacts or marketplace registry."""
+    version = kwargs.get("version")
+    scope = kwargs.get("scope", "user")
+    source = kwargs.get("source", "auto")
+    repo = kwargs.get("repo")
+    trust_non_official = kwargs.get("trust_non_official", False)
+    skip_deps = kwargs.get("skip_deps", False)
+    force = kwargs.get("force", False)
+    reinstall = kwargs.get("reinstall", False)
     if version is not None and sum(1 for mid in module_ids if mid.strip()) > 1:
         console.print(
             "[red]--version applies to a single module; install one module at a time or omit --version.[/red]"
@@ -330,23 +391,36 @@ def install(
     scope_normalized, source_normalized = _parse_install_scope_and_source(scope, source)
     target_root = _resolve_install_target_root(scope_normalized, repo)
     discovered_by_name = {entry.metadata.name: entry for entry in discover_all_modules()}
+    params = _InstallOneParams(
+        scope_normalized=scope_normalized,
+        source_normalized=source_normalized,
+        target_root=target_root,
+        version=version,
+        reinstall=reinstall,
+        trust_non_official=trust_non_official,
+        skip_deps=skip_deps,
+        force=force,
+        discovered_by_name=discovered_by_name,
+    )
     for module_id in module_ids:
-        success = _install_one(
-            module_id,
-            scope_normalized,
-            source_normalized,
-            target_root,
-            version,
-            reinstall,
-            trust_non_official,
-            skip_deps,
-            force,
-            discovered_by_name,
-        )
-        if not success:
+        if not _install_one(module_id, params):
             raise typer.Exit(1)
 
 
+@app.command()
+@require(_install_module_ids_nonempty, "at least one non-blank module id is required")
+@beartype
+def install(
+    module_ids: Annotated[
+        list[str],
+        typer.Argument(help="Module id(s) (name or namespace/name); space-separated for multiple"),
+    ],
+    **kwargs,
+) -> None:
+    """Install one or more modules from bundled artifacts or marketplace registry."""
+    _install_impl(module_ids, **kwargs)
+
+
 def _normalize_uninstall_module_name(module_name: str) -> str:
     normalized = module_name
     if "/" in normalized:
@@ -383,35 +457,40 @@ def _resolve_uninstall_scope(
     return scope_normalized
 
 
-def _uninstall_from_explicit_scope(
-    scope_normalized: str | None,
-    normalized: str,
-    project_root: Path,
-    user_root: Path,
-    project_module_dir: Path,
-    user_module_dir: Path,
-) -> bool:
-    if scope_normalized == "project":
-        if not project_module_dir.exists():
-            console.print(f"[red]Module '{normalized}' is not installed in project scope ({project_root}).[/red]")
+@dataclass
+class _ExplicitUninstallPaths:
+    scope_normalized: str | None
+    normalized: str
+    project_root: Path
+    user_root: Path
+    project_module_dir: Path
+    user_module_dir: Path
+
+
+def _uninstall_from_explicit_scope(ctx: _ExplicitUninstallPaths) -> bool:
+    if ctx.scope_normalized == "project":
+        if not ctx.project_module_dir.exists():
+            console.print(
+                f"[red]Module '{ctx.normalized}' is not installed in project scope ({ctx.project_root}).[/red]"
+            )
             raise typer.Exit(1)
         try:
-            shutil.rmtree(project_module_dir)
+            shutil.rmtree(ctx.project_module_dir)
         except OSError as exc:
-            console.print(f"[red]Could not remove module directory {project_module_dir}: {exc}[/red]")
+            console.print(f"[red]Could not remove module directory {ctx.project_module_dir}: {exc}[/red]")
             raise typer.Exit(1) from exc
-        console.print(f"[green]Uninstalled[/green] {normalized} from {project_root}")
+        console.print(f"[green]Uninstalled[/green] {ctx.normalized} from {ctx.project_root}")
         return True
-    if scope_normalized == "user":
-        if not user_module_dir.exists():
-            console.print(f"[red]Module '{normalized}' is not installed in user scope ({user_root}).[/red]")
+    if ctx.scope_normalized == "user":
+        if not ctx.user_module_dir.exists():
+            console.print(f"[red]Module '{ctx.normalized}' is not installed in user scope ({ctx.user_root}).[/red]")
             raise typer.Exit(1)
         try:
-            shutil.rmtree(user_module_dir)
+            shutil.rmtree(ctx.user_module_dir)
         except OSError as exc:
-            console.print(f"[red]Could not remove module directory {user_module_dir}: {exc}[/red]")
+            console.print(f"[red]Could not remove module directory {ctx.user_module_dir}: {exc}[/red]")
             raise typer.Exit(1) from exc
-        console.print(f"[green]Uninstalled[/green] {normalized} from {user_root}")
+        console.print(f"[green]Uninstalled[/green] {ctx.normalized} from {ctx.user_root}")
         return True
     return False
 
@@ -426,7 +505,14 @@ def _uninstall_single_module(module_name: str, scope: str | None, repo: Path | N
     user_module_dir = user_root / normalized
     scope_normalized = _resolve_uninstall_scope(scope, normalized, project_module_dir, user_module_dir)
     if _uninstall_from_explicit_scope(
-        scope_normalized, normalized, project_root, user_root, project_module_dir, user_module_dir
+        _ExplicitUninstallPaths(
+            scope_normalized=scope_normalized,
+            normalized=normalized,
+            project_root=project_root,
+            user_root=user_root,
+            project_module_dir=project_module_dir,
+            user_module_dir=user_module_dir,
+        )
     ):
         return
     _uninstall_marketplace_default(normalized)
@@ -1024,6 +1110,8 @@ def show(module_name: str = typer.Argument(..., help="Installed module name")) -
 def _upgrade_row_for_target(target: str, by_id: dict[str, dict[str, Any]]) -> dict[str, Any]:
     if target in by_id:
         return by_id[target]
+    if target.count("/") > 1:
+        return {}
     short = target.split("/")[-1]
     if short in by_id:
         return by_id[short]
@@ -1036,6 +1124,10 @@ def _upgrade_row_for_target(target: str, by_id: dict[str, dict[str, Any]]) -> di
 def _full_marketplace_module_id_for_install(target: str) -> str:
     """Return ``namespace/name`` for ``install_module`` from a target key or short id."""
     t = target.strip()
+    if t.count("/") > 1:
+        raise ValueError(
+            f"Invalid module id {target!r}: expected owner/repo or a short module name, not a multi-segment path."
+        )
     if "/" in t and t.count("/") == 1:
         left, right = t.split("/", 1)
         if left.strip() and right.strip():
@@ -1062,10 +1154,11 @@ def _latest_version_map_from_registry_index(idx: dict[str, Any] | None) -> dict[
     for raw in mods:
         if not isinstance(raw, dict):
             continue
-        mid = str(raw.get("id", "")).strip()
+        raw_dict = cast(dict[str, Any], raw)
+        mid = str(raw_dict.get("id", "")).strip()
         if not mid:
             continue
-        lv = raw.get("latest_version")
+        lv = raw_dict.get("latest_version")
         if lv is None:
             continue
         s = str(lv).strip()
@@ -1088,15 +1181,35 @@ def _is_major_version_increase(current: str, latest: str) -> bool:
         return False
 
 
+def _upgrade_name_candidates(normalized: str, short: str, by_id: dict[str, dict[str, Any]]) -> list[str]:
+    candidates = [normalized]
+    if short != normalized:
+        candidates.append(short)
+    if "/" not in normalized and f"specfact-{normalized}" in by_id:
+        candidates.append(f"specfact-{normalized}")
+    return list(dict.fromkeys(candidates))
+
+
+def _resolve_marketplace_id_by_short(short: str, marketplace_by_id: dict[str, dict[str, Any]]) -> str | None:
+    for key in marketplace_by_id:
+        if key == short or str(key).endswith(f"/{short}"):
+            return key
+    return None
+
+
 def _resolve_one_upgrade_name(raw: str, by_id: dict[str, dict[str, Any]]) -> str:
     """Resolve a single CLI name to a module id key used in ``by_id`` / targets."""
     normalized = raw.strip()
     if not normalized:
         return normalized
-    candidates = [normalized]
-    if "/" not in normalized and f"specfact-{normalized}" in by_id:
-        candidates.append(f"specfact-{normalized}")
-    for cand in candidates:
+    if normalized.count("/") > 1:
+        console.print(
+            f"[red]Invalid module id {normalized!r}: use owner/repo or a short name (e.g. backlog), "
+            "not a multi-segment path.[/red]"
+        )
+        raise typer.Exit(1)
+    short = normalized.split("/")[-1]
+    for cand in _upgrade_name_candidates(normalized, short, by_id):
         if cand not in by_id:
             continue
         source = str(by_id[cand].get("source", "unknown"))
@@ -1107,12 +1220,9 @@ def _resolve_one_upgrade_name(raw: str, by_id: dict[str, dict[str, Any]]) -> str
             raise typer.Exit(1)
         return cand
     marketplace_by_id = {k: v for k, v in by_id.items() if str(v.get("source", "")) == "marketplace"}
-    candidates2 = [normalized]
-    if "/" not in normalized and f"specfact-{normalized}" in marketplace_by_id:
-        candidates2.append(f"specfact-{normalized}")
-    for cand in candidates2:
-        if cand in marketplace_by_id:
-            return cand
+    resolved = _resolve_marketplace_id_by_short(short, marketplace_by_id)
+    if resolved is not None:
+        return resolved
     console.print(f"[red]Module '{normalized}' is not installed and cannot be upgraded.[/red]")
     raise typer.Exit(1)
 
@@ -1131,6 +1241,73 @@ def _resolve_upgrade_target_ids(
     return [_resolve_one_upgrade_name(raw, by_id) for raw in module_names]
 
 
+def _major_upgrade_decision(
+    full_id: str,
+    current_v: str,
+    latest_v: str,
+    *,
+    yes: bool,
+) -> tuple[bool, tuple[str, str, str] | None]:
+    """Return (should_install, skipped_major_tuple when skipping a major bump)."""
+    if not _is_major_version_increase(current_v, latest_v):
+        return True, None
+    if yes:
+        return True, None
+    if is_non_interactive():
+        console.print(
+            f"[yellow]Skipping major upgrade for {full_id}: {current_v} -> {latest_v} "
+            "(non-interactive; use --yes to approve)[/yellow]"
+        )
+        return False, (full_id, current_v, latest_v)
+    if not typer.confirm(
+        f"Major version upgrade for {full_id} ({current_v} -> {latest_v}). Continue?",
+        default=False,
+    ):
+        return False, (full_id, current_v, latest_v)
+    return True, None
+
+
+@dataclass
+class _MarketplaceUpgradeAccum:
+    upgraded: list[tuple[str, str, str]]
+    up_to_date: list[str]
+    skipped_major: list[tuple[str, str, str]]
+
+
+def _run_one_marketplace_upgrade_target(
+    target: str,
+    by_id: dict[str, dict[str, Any]],
+    latest_by_id: dict[str, str],
+    *,
+    yes: bool,
+    accum: _MarketplaceUpgradeAccum,
+) -> None:
+    full_id = _full_marketplace_module_id_for_install(target)
+    row = _upgrade_row_for_target(target, by_id)
+    current_v = str(row.get("version", "unknown")).strip()
+    latest_v = str(row.get("latest_version") or "").strip()
+    if not latest_v:
+        latest_v = (latest_by_id.get(full_id, "") or "").strip()
+
+    if latest_v and _versions_equal_for_upgrade(current_v, latest_v):
+        accum.up_to_date.append(full_id)
+        return
+
+    if not latest_v:
+        with _module_upgrade_status(f"[cyan]Upgrading[/cyan] [bold]{full_id}[/bold] …"):
+            installed_path = install_module(full_id, reinstall=True)
+        accum.upgraded.append((full_id, current_v, _read_installed_module_version(installed_path)))
+        return
+
+    should_install, skip_tuple = _major_upgrade_decision(full_id, current_v, latest_v, yes=yes)
+    if skip_tuple is not None:
+        accum.skipped_major.append(skip_tuple)
+    if should_install:
+        with _module_upgrade_status(f"[cyan]Upgrading[/cyan] [bold]{full_id}[/bold] …"):
+            installed_path = install_module(full_id, reinstall=True)
+        accum.upgraded.append((full_id, current_v, _read_installed_module_version(installed_path)))
+
+
 def _run_marketplace_upgrades(
     target_ids: list[str],
     by_id: dict[str, dict[str, Any]],
@@ -1142,46 +1319,15 @@ def _run_marketplace_upgrades(
     up_to_date: list[str] = []
     skipped_major: list[tuple[str, str, str]] = []
     failed: list[str] = []
+    accum = _MarketplaceUpgradeAccum(
+        upgraded=upgraded,
+        up_to_date=up_to_date,
+        skipped_major=skipped_major,
+    )
 
     for target in target_ids:
         try:
-            full_id = _full_marketplace_module_id_for_install(target)
-            row = _upgrade_row_for_target(target, by_id)
-            current_v = str(row.get("version", "unknown")).strip()
-            latest_v = str(row.get("latest_version") or "").strip()
-            if not latest_v:
-                latest_v = (latest_by_id.get(full_id, "") or "").strip()
-
-            if latest_v and _versions_equal_for_upgrade(current_v, latest_v):
-                up_to_date.append(full_id)
-                continue
-
-            if not latest_v:
-                installed_path = install_module(full_id, reinstall=True)
-                upgraded.append((full_id, current_v, _read_installed_module_version(installed_path)))
-                continue
-
-            should_install = True
-            if _is_major_version_increase(current_v, latest_v):
-                if yes:
-                    should_install = True
-                elif is_non_interactive():
-                    console.print(
-                        f"[yellow]Skipping major upgrade for {full_id}: {current_v} -> {latest_v} "
-                        "(non-interactive; use --yes to approve)[/yellow]"
-                    )
-                    skipped_major.append((full_id, current_v, latest_v))
-                    should_install = False
-                elif not typer.confirm(
-                    f"Major version upgrade for {full_id} ({current_v} -> {latest_v}). Continue?",
-                    default=False,
-                ):
-                    skipped_major.append((full_id, current_v, latest_v))
-                    should_install = False
-
-            if should_install:
-                installed_path = install_module(full_id, reinstall=True)
-                upgraded.append((full_id, current_v, _read_installed_module_version(installed_path)))
+            _run_one_marketplace_upgrade_target(target, by_id, latest_by_id, yes=yes, accum=accum)
         except Exception as exc:
             console.print(f"[red]Failed upgrading {target}: {exc}[/red]")
             failed.append(target)
@@ -1225,7 +1371,13 @@ def upgrade(
     target_ids = _resolve_upgrade_target_ids(module_names, all, modules, by_id)
     if not target_ids:
         return
-    index = fetch_registry_index()
+    with _module_upgrade_status("[dim]Fetching marketplace registry index…[/dim]"):
+        index = fetch_registry_index()
+    if index is None:
+        console.print(
+            "[yellow]Marketplace registry unavailable (offline or network error). "
+            "Upgrade will use installed metadata only.[/yellow]"
+        )
     latest_by_id = _latest_version_map_from_registry_index(index)
     _run_marketplace_upgrades(target_ids, by_id, latest_by_id, yes=yes)
 
@@ -1236,6 +1388,35 @@ def upgrade(
 sync_with_bundle = module_io_shim.sync_with_bundle
 validate_bundle = module_io_shim.validate_bundle
 
+
+def _ensure_specfact_install_param_patch() -> None:
+    """When this module is imported before ``specfact_cli.cli`` (e.g. unit tests), Typer must
+    still resolve CLI params from merged install signatures instead of the thin ``install`` wrapper.
+    If ``cli`` already patched ``typer.utils.get_params_from_function``, skip.
+
+    Match by name/module because ``@app.command()`` wraps the callback, so ``func is install`` fails.
+    """
+    import importlib
+
+    import typer.utils as tu
+
+    if getattr(tu.get_params_from_function, "__name__", "") == "_specfact_get_params_from_function":
+        return
+    prev = tu.get_params_from_function
+    _mod = "specfact_cli.modules.module_registry.src.commands"
+
+    def _wrapped(func: Callable[..., Any]) -> Any:
+        if getattr(func, "__name__", "") == "install" and getattr(func, "__module__", "") == _mod:
+            return _specfact_merge_install_param_specs(prev)
+        return prev(func)
+
+    tu.get_params_from_function = _wrapped  # type: ignore[assignment]
+    typer_main = cast(Any, importlib.import_module("typer.main"))
+    typer_main.get_params_from_function = _wrapped  # type: ignore[assignment]
+
+
+_ensure_specfact_install_param_patch()
+
 __all__ = [
     "app",
     "export_from_bundle",
diff --git a/src/specfact_cli/registry/bootstrap.py b/src/specfact_cli/registry/bootstrap.py
index c9ad6351..2626fbf3 100644
--- a/src/specfact_cli/registry/bootstrap.py
+++ b/src/specfact_cli/registry/bootstrap.py
@@ -4,8 +4,18 @@
 Commands are discovered from configured module-package roots.
 Loaders import each package's src on first use and return its .app (Typer).
 cli.py must not import command modules at top level; it uses the registry.
-When category_grouping_enabled is True, mounts category groups (code, backlog, project, spec, govern)
-and compat shims for flat commands; otherwise mounts all modules flat.
+
+Topology (see ``register_module_package_commands`` in ``module_packages``):
+
+- When ``category_grouping_enabled`` is True (default): each non-core module registers under its
+  category path when ``meta.category`` is set. After packages load,
+  ``_mount_installed_category_groups`` mounts the category group commands (``code``, ``backlog``,
+  ``project``, ``spec``, ``govern``) for bundles that are installed and enabled. Legacy flat
+  aliases (for example ``analyze`` or ``plan`` at the root) are not registered.
+
+- When ``category_grouping_enabled`` is False: the same modules register with
+  ``_register_command_flat_path``, exposing each declared command name at the root (flat topology).
+  This is a compatibility path for older layouts; grouped categories are the default.
 """
 
 from __future__ import annotations
diff --git a/src/specfact_cli/registry/module_packages.py b/src/specfact_cli/registry/module_packages.py
index ed782a77..ac25fdcd 100644
--- a/src/specfact_cli/registry/module_packages.py
+++ b/src/specfact_cli/registry/module_packages.py
@@ -14,6 +14,7 @@
 import importlib.util
 import os
 import sys
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, cast
 
@@ -48,6 +49,46 @@
 from specfact_cli.utils.prompts import print_warning
 
 
+@dataclass
+class _ProtocolTopLevelScanState:
+    package_dir: Path
+    package_name: str
+    pending_paths: list[Path]
+    scanned_paths: set[Path]
+    exported_function_names: set[str]
+    class_method_names: dict[str, set[str]]
+    assigned_names: dict[str, ast.expr]
+
+
+@dataclass
+class _ProtocolComplianceCounters:
+    protocol_full: list[int]
+    protocol_partial: list[int]
+    protocol_legacy: list[int]
+    partial_modules: list[tuple[str, list[str]]]
+    legacy_modules: list[str]
+
+
+@dataclass
+class _ModuleIntegrityContext:
+    allow_unsigned: bool
+    is_test_mode: bool
+    logger: Any
+    skipped: list[tuple[str, str]]
+
+
+@dataclass
+class _PackageRegistrationContext:
+    enabled_map: dict[str, bool]
+    allow_unsigned: bool
+    is_test_mode: bool
+    logger: Any
+    skipped: list[tuple[str, str]]
+    bridge_owner_map: dict[str, str]
+    category_grouping_enabled: bool
+    counters: _ProtocolComplianceCounters
+
+
 # Display order for core modules (3 after migration-03); others follow alphabetically.
 CORE_NAMES = ("init", "module", "upgrade")
 CORE_MODULE_ORDER: tuple[str, ...] = (
@@ -709,39 +750,6 @@ def _resolve_package_load_path(package_dir: Path, package_name: str) -> Path:
     raise ValueError(f"Package {package_dir.name} has no src/app.py, src/{package_name}.py or src/{package_name}/")
 
 
-def _load_package_module(package_dir: Path, package_name: str) -> Any:
-    """Load and return a module package entrypoint module."""
-    src_dir = package_dir / "src"
-    if str(src_dir) not in sys.path:
-        sys.path.insert(0, str(src_dir))
-    load_path = _resolve_package_load_path(package_dir, package_name)
-    submodule_locations = [str(load_path.parent)] if load_path.name == "__init__.py" else None
-    module_token = _normalized_module_name(package_dir.name)
-    spec = importlib.util.spec_from_file_location(
-        f"_specfact_module_{module_token}",
-        load_path,
-        submodule_search_locations=submodule_locations,
-    )
-    if spec is None or spec.loader is None:
-        raise ValueError(f"Cannot load from {package_dir.name}")
-    mod = importlib.util.module_from_spec(spec)
-    sys.modules[spec.name] = mod
-    spec.loader.exec_module(mod)
-    return mod
-
-
-@beartype
-@require(lambda module_class: module_class is not None, "Module class must be provided")
-@ensure(lambda result: isinstance(result, list), "Protocol operation list must be returned")
-def _check_protocol_compliance(module_class: Any) -> list[str]:
-    """Return supported protocol operations based on available attributes."""
-    operations: list[str] = []
-    for operation, method_name in PROTOCOL_METHODS.items():
-        if hasattr(module_class, method_name):
-            operations.append(operation)
-    return operations
-
-
 def _resolve_protocol_source_paths(
     package_dir: Path,
     package_name: str,
@@ -829,41 +837,31 @@ def _protocol_record_assignments(
             exported_function_names.add(target.id)
 
 
-def _protocol_process_top_level_node(
-    node: ast.stmt,
-    package_dir: Path,
-    package_name: str,
-    source_path: Path,
-    pending_paths: list[Path],
-    scanned_paths: set[Path],
-    exported_function_names: set[str],
-    class_method_names: dict[str, set[str]],
-    assigned_names: dict[str, ast.expr],
-) -> None:
+def _protocol_process_top_level_node(node: ast.stmt, source_path: Path, state: _ProtocolTopLevelScanState) -> None:
     if isinstance(node, ast.ClassDef):
         methods: set[str] = set()
         for class_node in node.body:
             if isinstance(class_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                 methods.add(class_node.name)
-        class_method_names[node.name] = methods
+        state.class_method_names[node.name] = methods
         return
     if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-        exported_function_names.add(node.name)
+        state.exported_function_names.add(node.name)
         return
     if isinstance(node, ast.ImportFrom):
         imported_names = {alias.name for alias in node.names}
         if set(PROTOCOL_INTERFACE_BINDINGS).isdisjoint(imported_names):
             return
-        imported_source = _resolve_import_from_source_path(package_dir, package_name, source_path, node)
+        imported_source = _resolve_import_from_source_path(state.package_dir, state.package_name, source_path, node)
         if imported_source is None:
             return
         resolved = imported_source.resolve()
-        if resolved in scanned_paths:
+        if resolved in state.scanned_paths:
             return
-        scanned_paths.add(resolved)
-        pending_paths.append(imported_source)
+        state.scanned_paths.add(resolved)
+        state.pending_paths.append(imported_source)
         return
-    _protocol_record_assignments(node, assigned_names, exported_function_names)
+    _protocol_record_assignments(node, state.assigned_names, state.exported_function_names)
 
 
 def _protocol_merge_binding_methods(
@@ -909,26 +907,27 @@ def _check_protocol_compliance_from_source(
     scanned_sources: list[str] = []
     pending_paths = _resolve_protocol_source_paths(package_dir, package_name, command_names=command_names)
     scanned_paths = {path.resolve() for path in pending_paths}
+    scan_state = _ProtocolTopLevelScanState(
+        package_dir=package_dir,
+        package_name=package_name,
+        pending_paths=pending_paths,
+        scanned_paths=scanned_paths,
+        exported_function_names=exported_function_names,
+        class_method_names=class_method_names,
+        assigned_names=assigned_names,
+    )
 
-    while pending_paths:
-        source_path = pending_paths.pop(0)
+    while scan_state.pending_paths:
+        source_path = scan_state.pending_paths.pop(0)
         source = source_path.read_text(encoding="utf-8")
         scanned_sources.append(source)
         tree = ast.parse(source, filename=str(source_path))
         for node in tree.body:
-            _protocol_process_top_level_node(
-                node,
-                package_dir,
-                package_name,
-                source_path,
-                pending_paths,
-                scanned_paths,
-                exported_function_names,
-                class_method_names,
-                assigned_names,
-            )
+            _protocol_process_top_level_node(node, source_path, scan_state)
 
-    _protocol_merge_binding_methods(assigned_names, class_method_names, exported_function_names)
+    _protocol_merge_binding_methods(
+        scan_state.assigned_names, scan_state.class_method_names, scan_state.exported_function_names
+    )
 
     operations: list[str] = []
     for operation, method_name in PROTOCOL_METHODS.items():
@@ -1122,24 +1121,17 @@ def _register_service_bridges_safe(meta: Any, bridge_owner_map: dict[str, str],
             )
 
 
-def _module_integrity_allows_load(
-    package_dir: Path,
-    meta: Any,
-    allow_unsigned: bool,
-    is_test_mode: bool,
-    logger: Any,
-    skipped: list[tuple[str, str]],
-) -> bool:
-    if verify_module_artifact(package_dir, meta, allow_unsigned=allow_unsigned):
+def _module_integrity_allows_load(package_dir: Path, meta: Any, ctx: _ModuleIntegrityContext) -> bool:
+    if verify_module_artifact(package_dir, meta, allow_unsigned=ctx.allow_unsigned):
         return True
     if _is_builtin_module_package(package_dir):
-        logger.warning(
+        ctx.logger.warning(
             "Built-in module '%s' failed integrity verification; loading anyway to keep CLI functional.",
             meta.name,
         )
         return True
-    if is_test_mode and allow_unsigned:
-        logger.debug(
+    if ctx.is_test_mode and ctx.allow_unsigned:
+        ctx.logger.debug(
             "TEST_MODE: allowing built-in module '%s' despite failed integrity verification.",
             meta.name,
         )
@@ -1149,41 +1141,47 @@ def _module_integrity_allows_load(
         "This may indicate tampering or an outdated local module copy. "
         "Run `specfact module init` to restore trusted bundled modules."
     )
-    skipped.append((meta.name, "integrity/trust check failed"))
+    ctx.skipped.append((meta.name, "integrity/trust check failed"))
     return False
 
 
+def _apply_protocol_counters_from_operations(
+    meta: Any,
+    operations: list[str],
+    logger: Any,
+    counters: _ProtocolComplianceCounters,
+) -> None:
+    if len(operations) == 4:
+        counters.protocol_full[0] += 1
+        return
+    if operations:
+        counters.partial_modules.append((meta.name, operations))
+        if is_debug_mode():
+            logger.info("Module %s: ModuleIOContract partial (%s)", meta.name, ", ".join(operations))
+        counters.protocol_partial[0] += 1
+        return
+    counters.legacy_modules.append(meta.name)
+    if is_debug_mode():
+        logger.warning("Module %s: No ModuleIOContract (legacy mode)", meta.name)
+    counters.protocol_legacy[0] += 1
+
+
 def _record_protocol_compliance_result(
     package_dir: Path,
     meta: Any,
     logger: Any,
-    protocol_full: list[int],
-    protocol_partial: list[int],
-    protocol_legacy: list[int],
-    partial_modules: list[tuple[str, list[str]]],
-    legacy_modules: list[str],
+    counters: _ProtocolComplianceCounters,
 ) -> None:
     try:
         operations = _check_protocol_compliance_from_source(package_dir, meta.name, command_names=meta.commands)
         meta.protocol_operations = operations
-        if len(operations) == 4:
-            protocol_full[0] += 1
-        elif operations:
-            partial_modules.append((meta.name, operations))
-            if is_debug_mode():
-                logger.info("Module %s: ModuleIOContract partial (%s)", meta.name, ", ".join(operations))
-            protocol_partial[0] += 1
-        else:
-            legacy_modules.append(meta.name)
-            if is_debug_mode():
-                logger.warning("Module %s: No ModuleIOContract (legacy mode)", meta.name)
-            protocol_legacy[0] += 1
+        _apply_protocol_counters_from_operations(meta, operations, logger, counters)
     except Exception as exc:
-        legacy_modules.append(meta.name)
+        counters.legacy_modules.append(meta.name)
         if is_debug_mode():
             logger.warning("Module %s: Unable to inspect protocol compliance (%s)", meta.name, exc)
         meta.protocol_operations = []
-        protocol_legacy[0] += 1
+        counters.protocol_legacy[0] += 1
 
 
 def _register_command_category_path(
@@ -1283,49 +1281,42 @@ def _register_commands_for_package(
     category_grouping_enabled: bool,
     logger: Any,
 ) -> None:
+    """Register package commands. Categorized marketplace modules never use flat root registration."""
+    _ = category_grouping_enabled  # retained for API compatibility; grouping no longer selects flat vs category
     for cmd_name in meta.commands:
-        if category_grouping_enabled and meta.category is not None:
+        if meta.category is not None:
             _register_command_category_path(package_dir, meta, cmd_name, logger)
         else:
             _register_command_flat_path(package_dir, meta, cmd_name, logger)
 
 
-def _register_one_package_if_eligible(
-    package_dir: Path,
-    meta: Any,
-    enabled_map: dict[str, bool],
-    allow_unsigned: bool,
-    is_test_mode: bool,
-    logger: Any,
-    skipped: list[tuple[str, str]],
-    bridge_owner_map: dict[str, str],
-    category_grouping_enabled: bool,
-    protocol_full: list[int],
-    protocol_partial: list[int],
-    protocol_legacy: list[int],
-    partial_modules: list[tuple[str, list[str]]],
-    legacy_modules: list[str],
-) -> None:
-    if not enabled_map.get(meta.name, True):
+def _register_one_package_if_eligible(package_dir: Path, meta: Any, reg: _PackageRegistrationContext) -> None:
+    if not reg.enabled_map.get(meta.name, True):
         return
     compatible = _check_core_compatibility(meta, cli_version)
     if not compatible:
-        skipped.append((meta.name, f"requires {meta.core_compatibility}, cli is {cli_version}"))
+        reg.skipped.append((meta.name, f"requires {meta.core_compatibility}, cli is {cli_version}"))
         return
-    deps_ok, missing = _validate_module_dependencies(meta, enabled_map)
+    deps_ok, missing = _validate_module_dependencies(meta, reg.enabled_map)
     if not deps_ok:
-        skipped.append((meta.name, f"missing dependencies: {', '.join(missing)}"))
+        reg.skipped.append((meta.name, f"missing dependencies: {', '.join(missing)}"))
         return
-    if not _module_integrity_allows_load(package_dir, meta, allow_unsigned, is_test_mode, logger, skipped):
+    integrity_ctx = _ModuleIntegrityContext(
+        allow_unsigned=reg.allow_unsigned,
+        is_test_mode=reg.is_test_mode,
+        logger=reg.logger,
+        skipped=reg.skipped,
+    )
+    if not _module_integrity_allows_load(package_dir, meta, integrity_ctx):
         return
     if not _check_schema_compatibility(meta.schema_version, CURRENT_PROJECT_SCHEMA_VERSION):
-        skipped.append(
+        reg.skipped.append(
             (
                 meta.name,
                 f"schema version {meta.schema_version} required, current is {CURRENT_PROJECT_SCHEMA_VERSION}",
             )
         )
-        logger.debug(
+        reg.logger.debug(
             "Module %s: Schema version %s required, but current is %s (skipped)",
             meta.name,
             meta.schema_version,
@@ -1333,34 +1324,18 @@ def _register_one_package_if_eligible(
         )
         return
     if meta.schema_version is None:
-        logger.debug("Module %s: No schema version declared (assuming current)", meta.name)
+        reg.logger.debug("Module %s: No schema version declared (assuming current)", meta.name)
     else:
-        logger.debug("Module %s: Schema version %s (compatible)", meta.name, meta.schema_version)
-
-    _register_schema_extensions_safe(meta, logger)
-    _register_service_bridges_safe(meta, bridge_owner_map, logger)
-    _record_protocol_compliance_result(
-        package_dir,
-        meta,
-        logger,
-        protocol_full,
-        protocol_partial,
-        protocol_legacy,
-        partial_modules,
-        legacy_modules,
-    )
-    _register_commands_for_package(package_dir, meta, category_grouping_enabled, logger)
+        reg.logger.debug("Module %s: Schema version %s (compatible)", meta.name, meta.schema_version)
 
+    _register_schema_extensions_safe(meta, reg.logger)
+    _register_service_bridges_safe(meta, reg.bridge_owner_map, reg.logger)
+    _record_protocol_compliance_result(package_dir, meta, reg.logger, reg.counters)
+    _register_commands_for_package(package_dir, meta, reg.category_grouping_enabled, reg.logger)
 
-def _log_protocol_compatibility_footer(
-    logger: Any,
-    protocol_full: list[int],
-    protocol_partial: list[int],
-    protocol_legacy: list[int],
-    partial_modules: list[tuple[str, list[str]]],
-    legacy_modules: list[str],
-) -> None:
-    pf, pp, pl = protocol_full[0], protocol_partial[0], protocol_legacy[0]
+
+def _log_protocol_compatibility_footer(logger: Any, counters: _ProtocolComplianceCounters) -> None:
+    pf, pp, pl = counters.protocol_full[0], counters.protocol_partial[0], counters.protocol_legacy[0]
     discovered_count = pf + pp + pl
     if not discovered_count or not (pp > 0 or pl > 0) or not is_debug_mode():
         return
@@ -1372,11 +1347,11 @@ def _log_protocol_compatibility_footer(
         pp,
         pl,
     )
-    if partial_modules:
-        partial_desc = ", ".join(f"{name} ({'/'.join(ops)})" for name, ops in sorted(partial_modules))
+    if counters.partial_modules:
+        partial_desc = ", ".join(f"{name} ({'/'.join(ops)})" for name, ops in sorted(counters.partial_modules))
         logger.info("Partially compliant modules: %s", partial_desc)
-    if legacy_modules:
-        logger.info("Legacy modules: %s", ", ".join(sorted(set(legacy_modules))))
+    if counters.legacy_modules:
+        logger.info("Legacy modules: %s", ", ".join(sorted(set(counters.legacy_modules))))
 
 
 def _log_skipped_modules_debug(logger: Any, skipped: list[tuple[str, str]]) -> None:
@@ -1400,7 +1375,8 @@ def register_module_package_commands(
 
     Call after register_builtin_commands(). enable_ids/disable_ids from CLI (--enable-module/--disable-module).
     allow_unsigned: If True, allow modules without integrity metadata. Default from SPECFACT_ALLOW_UNSIGNED env.
-    category_grouping_enabled: If True, register category groups (code, backlog, project, spec, govern).
+    category_grouping_enabled: Ignored for registration (retained for API compatibility). Category groups are
+    always mounted for installed bundles; categorized modules never register flat root aliases.
     """
     enable_ids = enable_ids or []
     disable_ids = disable_ids or []
@@ -1416,41 +1392,30 @@ def register_module_package_commands(
     enabled_map = merge_module_state(discovered_list, state, enable_ids, disable_ids)
     logger = get_bridge_logger(__name__)
     skipped: list[tuple[str, str]] = []
-    protocol_full = [0]
-    protocol_partial = [0]
-    protocol_legacy = [0]
-    partial_modules: list[tuple[str, list[str]]] = []
-    legacy_modules: list[str] = []
+    counters = _ProtocolComplianceCounters(
+        protocol_full=[0],
+        protocol_partial=[0],
+        protocol_legacy=[0],
+        partial_modules=[],
+        legacy_modules=[],
+    )
     bridge_owner_map: dict[str, str] = {
         bridge_id: BRIDGE_REGISTRY.get_owner(bridge_id) or "unknown" for bridge_id in BRIDGE_REGISTRY.list_bridge_ids()
     }
-    for package_dir, meta in packages:
-        _register_one_package_if_eligible(
-            package_dir,
-            meta,
-            enabled_map,
-            allow_unsigned,
-            is_test_mode,
-            logger,
-            skipped,
-            bridge_owner_map,
-            category_grouping_enabled,
-            protocol_full,
-            protocol_partial,
-            protocol_legacy,
-            partial_modules,
-            legacy_modules,
-        )
-    if category_grouping_enabled:
-        _mount_installed_category_groups(packages, enabled_map)
-    _log_protocol_compatibility_footer(
-        logger,
-        protocol_full,
-        protocol_partial,
-        protocol_legacy,
-        partial_modules,
-        legacy_modules,
+    reg_ctx = _PackageRegistrationContext(
+        enabled_map=enabled_map,
+        allow_unsigned=allow_unsigned,
+        is_test_mode=is_test_mode,
+        logger=logger,
+        skipped=skipped,
+        bridge_owner_map=bridge_owner_map,
+        category_grouping_enabled=category_grouping_enabled,
+        counters=counters,
     )
+    for package_dir, meta in packages:
+        _register_one_package_if_eligible(package_dir, meta, reg_ctx)
+    _mount_installed_category_groups(packages, enabled_map)
+    _log_protocol_compatibility_footer(logger, counters)
     _log_skipped_modules_debug(logger, skipped)
 
 
diff --git a/tests/unit/modules/init/test_first_run_selection.py b/tests/unit/modules/init/test_first_run_selection.py
index f3bb8d83..f2140c19 100644
--- a/tests/unit/modules/init/test_first_run_selection.py
+++ b/tests/unit/modules/init/test_first_run_selection.py
@@ -389,19 +389,16 @@ def _fake_install(bundle_ids: list[str], install_root: Path, **kwargs: object) -
 
 
 def test_spec_bundle_install_includes_project_dep(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
-    installed_modules: list[str] = []
+    installed_ids: list[str] = []
 
-    def _record_install(module_name: str, target_root: Path, **kwargs: object) -> bool:
-        installed_modules.append(module_name)
-        return True
+    def _record_marketplace(module_id: str, **kwargs: object) -> Path:
+        installed_ids.append(module_id)
+        return tmp_path / module_id.split("/")[1]
 
     monkeypatch.setattr(
-        "specfact_cli.registry.module_installer.install_bundled_module",
-        _record_install,
+        "specfact_cli.registry.module_installer.install_module",
+        _record_marketplace,
     )
     frs.install_bundles_for_init(["specfact-spec"], install_root=tmp_path, show_progress=False)
-    project_module_names = set(frs.BUNDLE_TO_MODULE_NAMES.get("specfact-project", []))
-    spec_module_names = set(frs.BUNDLE_TO_MODULE_NAMES.get("specfact-spec", []))
-    installed_set = set(installed_modules)
-    assert project_module_names & installed_set, "spec bundle must trigger project bundle dep install"
-    assert spec_module_names & installed_set, "spec bundle modules must be installed"
+    assert "nold-ai/specfact-project" in installed_ids, "spec bundle depends on project marketplace module"
+    assert "nold-ai/specfact-spec" in installed_ids
diff --git a/tests/unit/modules/module_registry/test_commands.py b/tests/unit/modules/module_registry/test_commands.py
index 7ceb2c75..3e381631 100644
--- a/tests/unit/modules/module_registry/test_commands.py
+++ b/tests/unit/modules/module_registry/test_commands.py
@@ -1104,6 +1104,47 @@ def test_upgrade_rejects_non_marketplace_source(monkeypatch) -> None:
     assert "marketplace modules" in result.stdout and "upgradeable" in result.stdout
 
 
+def test_upgrade_rejects_multi_segment_module_id(monkeypatch, tmp_path: Path) -> None:
+    """Malformed owner/repo/extra must not resolve via last-segment fallback to a different module."""
+    installed: list[str] = []
+
+    def _install(module_id: str, version=None, reinstall: bool = False):
+        installed.append(module_id)
+        return tmp_path / module_id.split("/")[-1]
+
+    monkeypatch.setattr(
+        "specfact_cli.modules.module_registry.src.commands.install_module",
+        _install,
+    )
+    monkeypatch.setattr(
+        "specfact_cli.modules.module_registry.src.commands.get_modules_with_state",
+        lambda: [
+            {"id": "nold-ai/specfact-backlog", "version": "0.2.0", "enabled": True, "source": "marketplace"},
+        ],
+    )
+
+    result = runner.invoke(app, ["upgrade", "foo/bar/backlog"])
+
+    assert result.exit_code == 1
+    assert not installed
+    assert "Invalid module id" in result.stdout
+    assert "multi-segment" in result.stdout
+
+
+def test_upgrade_row_for_target_does_not_match_last_segment_for_multi_slash_ids() -> None:
+    from specfact_cli.modules.module_registry.src.commands import _upgrade_row_for_target
+
+    by_id = {"nold-ai/specfact-backlog": {"version": "1", "source": "marketplace"}}
+    assert _upgrade_row_for_target("foo/bar/backlog", by_id) == {}
+
+
+def test_full_marketplace_module_id_for_install_rejects_multi_segment_path() -> None:
+    from specfact_cli.modules.module_registry.src.commands import _full_marketplace_module_id_for_install
+
+    with pytest.raises(ValueError, match="multi-segment"):
+        _full_marketplace_module_id_for_install("foo/bar/backlog")
+
+
 def test_enable_command_updates_state_with_dependency_checks(monkeypatch) -> None:
     captured = {"enable_ids": None, "disable_ids": None, "force": None}
 
diff --git a/tests/unit/registry/test_category_groups.py b/tests/unit/registry/test_category_groups.py
index 838b17dc..71a3064c 100644
--- a/tests/unit/registry/test_category_groups.py
+++ b/tests/unit/registry/test_category_groups.py
@@ -46,24 +46,36 @@ def test_bootstrap_with_category_grouping_enabled_registers_group_commands() ->
     }
     assert set(names).issubset(allowed), f"Unexpected root commands found: {sorted(set(names) - allowed)}"
     assert {"init", "module", "upgrade"}.issubset(set(names))
+    if "code" in names:
+        assert {"project", "spec"} <= set(names), (
+            "When the code category group is mounted, project and spec groups must register too."
+        )
     assert not (set(names) & forbidden_flat), (
         f"Flat shims should not be registered: {sorted(set(names) & forbidden_flat)}"
     )
 
 
-def test_bootstrap_with_category_grouping_disabled_registers_flat_commands() -> None:
-    """With category grouping disabled, grouped aliases are not mounted via category grouping."""
+def test_bootstrap_with_category_grouping_disabled_still_has_no_flat_shims() -> None:
+    """Flat bundle shims are not registered even when SPECFACT_CATEGORY_GROUPING_ENABLED is false."""
     with patch.dict(os.environ, {"SPECFACT_CATEGORY_GROUPING_ENABLED": "false"}, clear=False):
         register_builtin_commands()
         rebuild_root_app_from_registry()
     names = [name for name, _ in CommandRegistry.list_commands_for_help()]
-    # Skip assertions if bundles aren't installed (e.g., in CI without modules)
-    if "code" not in names:
-        pytest.skip("Codebase bundle not installed; skipping bundle-native command assertions")
-    assert "code" in names, "Bundle-native root command 'code' should remain available when grouping is disabled"
-    assert "govern" in names, "Bundle-native root command 'govern' should remain available when grouping is disabled"
-    assert "project" in names
-    assert "spec" in names
+    forbidden_flat = {
+        "analyze",
+        "drift",
+        "validate",
+        "repro",
+        "import",
+        "plan",
+        "sync",
+        "migrate",
+    }
+    assert not (set(names) & forbidden_flat), (
+        f"Flat shims must not be registered: {sorted(set(names) & forbidden_flat)}"
+    )
+    if "code" in names:
+        assert "project" in names and "spec" in names
 
 
 def test_code_analyze_routes_same_as_flat_analyze(
diff --git a/tests/unit/registry/test_module_bridge_registration.py b/tests/unit/registry/test_module_bridge_registration.py
index 93ab6f1d..95877b90 100644
--- a/tests/unit/registry/test_module_bridge_registration.py
+++ b/tests/unit/registry/test_module_bridge_registration.py
@@ -39,7 +39,6 @@ def test_register_module_package_commands_registers_declared_bridges(monkeypatch
     monkeypatch.setattr(module_packages, "verify_module_artifact", lambda _dir, _meta, allow_unsigned=False: True)
     monkeypatch.setattr(module_packages, "read_modules_state", dict)
     monkeypatch.setattr(module_packages, "_make_package_loader", lambda *_args: object)
-    monkeypatch.setattr(module_packages, "_load_package_module", lambda *_args: object())
     monkeypatch.setattr(module_packages, "BRIDGE_REGISTRY", registry, raising=False)
 
     module_packages.register_module_package_commands()
@@ -56,7 +55,6 @@ def test_invalid_bridge_declaration_is_non_fatal(monkeypatch, tmp_path: Path) ->
     monkeypatch.setattr(module_packages, "verify_module_artifact", lambda _dir, _meta, allow_unsigned=False: True)
     monkeypatch.setattr(module_packages, "read_modules_state", dict)
     monkeypatch.setattr(module_packages, "_make_package_loader", lambda *_args: object)
-    monkeypatch.setattr(module_packages, "_load_package_module", lambda *_args: object())
     monkeypatch.setattr(module_packages, "BRIDGE_REGISTRY", registry, raising=False)
 
     module_packages.register_module_package_commands()
diff --git a/tests/unit/registry/test_module_protocol_validation.py b/tests/unit/registry/test_module_protocol_validation.py
index b1d5b603..ae81d611 100644
--- a/tests/unit/registry/test_module_protocol_validation.py
+++ b/tests/unit/registry/test_module_protocol_validation.py
@@ -2,7 +2,17 @@
 
 from __future__ import annotations
 
-from specfact_cli.registry.module_packages import _check_protocol_compliance, _check_schema_compatibility
+from typing import Any
+
+from specfact_cli.registry.module_packages import PROTOCOL_METHODS, _check_schema_compatibility
+
+
+def _protocol_operations_for_class(module_class: Any) -> list[str]:
+    operations: list[str] = []
+    for operation, method_name in PROTOCOL_METHODS.items():
+        if hasattr(module_class, method_name):
+            operations.append(operation)
+    return operations
 
 
 class FullProtocolModule:
@@ -33,22 +43,22 @@ def run(self):
 
 
 def test_discovery_detects_protocol_implementation() -> None:
-    operations = _check_protocol_compliance(FullProtocolModule)
+    operations = _protocol_operations_for_class(FullProtocolModule)
     assert set(operations) == {"import", "export", "sync", "validate"}
 
 
 def test_full_protocol_logged() -> None:
-    operations = _check_protocol_compliance(FullProtocolModule)
+    operations = _protocol_operations_for_class(FullProtocolModule)
     assert len(operations) == 4
 
 
 def test_partial_protocol_logged() -> None:
-    operations = _check_protocol_compliance(PartialProtocolModule)
+    operations = _protocol_operations_for_class(PartialProtocolModule)
     assert set(operations) == {"import", "validate"}
 
 
 def test_no_protocol_legacy_mode() -> None:
-    operations = _check_protocol_compliance(LegacyModule)
+    operations = _protocol_operations_for_class(LegacyModule)
     assert operations == []
 
 
diff --git a/tests/unit/specfact_cli/modules/test_module_upgrade_improvements.py b/tests/unit/specfact_cli/modules/test_module_upgrade_improvements.py
index f642f867..d55adc7c 100644
--- a/tests/unit/specfact_cli/modules/test_module_upgrade_improvements.py
+++ b/tests/unit/specfact_cli/modules/test_module_upgrade_improvements.py
@@ -8,13 +8,17 @@
 
 from pathlib import Path
 from typing import Any
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
 import click
 import pytest
 from typer.testing import CliRunner
 
-from specfact_cli.modules.module_registry.src.commands import _run_marketplace_upgrades
+from specfact_cli.modules.module_registry.src.commands import (
+    _resolve_one_upgrade_name,
+    _run_marketplace_upgrades,
+    app as module_app,
+)
 
 
 runner = CliRunner()
@@ -120,8 +124,6 @@ def _fake_read_version(module_dir: Path) -> str:
 
 def test_upgrade_command_accepts_multiple_module_names(tmp_path: Path) -> None:
     """upgrade command must accept multiple positional module names."""
-    from specfact_cli.cli import app
-
     with (
         patch(
             "specfact_cli.modules.module_registry.src.commands.get_modules_with_state",
@@ -146,7 +148,7 @@ def test_upgrade_command_accepts_multiple_module_names(tmp_path: Path) -> None:
         patch("specfact_cli.modules.module_registry.src.commands._resolve_upgrade_target_ids") as mock_resolve,
     ):
         mock_resolve.return_value = ["nold-ai/specfact-backlog", "nold-ai/specfact-codebase"]
-        result = runner.invoke(app, ["module", "upgrade", "backlog", "codebase"])
+        result = runner.invoke(module_app, ["upgrade", "backlog", "codebase"])
 
     # Should not show "No such argument" error
     assert "No such argument" not in _unstyled(result.output), result.output
@@ -227,3 +229,76 @@ def _fake_read_version(p: Path) -> str:
         _run_marketplace_upgrades(["nold-ai/specfact-backlog"], by_id, {}, yes=True)
 
     mock_confirm.assert_not_called()  # --yes flag skips prompt
+
+
+def test_upgrade_command_warns_when_registry_unavailable(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    """When the registry index cannot be fetched, upgrade prints a warning before continuing."""
+    monkeypatch.setattr(
+        "specfact_cli.modules.module_registry.src.commands.fetch_registry_index",
+        lambda **_: None,
+    )
+    monkeypatch.setattr(
+        "specfact_cli.modules.module_registry.src.commands.get_modules_with_state",
+        lambda: [{"id": "backlog", "version": "0.2.0", "enabled": True, "source": "marketplace"}],
+    )
+
+    def _install(module_id: str, **kwargs: object) -> Path:
+        return tmp_path / "backlog"
+
+    monkeypatch.setattr(
+        "specfact_cli.modules.module_registry.src.commands.install_module",
+        _install,
+    )
+    monkeypatch.setattr(
+        "specfact_cli.modules.module_registry.src.commands._read_installed_module_version",
+        lambda _p: "0.2.0",
+    )
+    result = runner.invoke(module_app, ["upgrade", "backlog"])
+    assert result.exit_code == 0
+    out = (result.stdout or "") + (result.stderr or "")
+    assert "unavailable" in out.lower() or "network error" in out.lower()
+
+
+def test_run_marketplace_upgrades_calls_console_status_when_spinner_enabled(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """When not in pytest/test mode, install path uses ``console.status`` for feedback."""
+    monkeypatch.delenv("PYTEST_CURRENT_TEST", raising=False)
+    monkeypatch.delenv("TEST_MODE", raising=False)
+
+    mock_console = MagicMock()
+    mock_ctx = MagicMock()
+    mock_ctx.__enter__ = MagicMock(return_value=None)
+    mock_ctx.__exit__ = MagicMock(return_value=None)
+    mock_console.status = MagicMock(return_value=mock_ctx)
+
+    by_id: dict[str, dict[str, Any]] = {
+        "nold-ai/specfact-backlog": {"version": "0.1.0", "source": "marketplace"},
+    }
+
+    def _fake_install(module_id: str, **kwargs: object) -> Path:
+        return tmp_path / "m"
+
+    with (
+        patch("specfact_cli.modules.module_registry.src.commands.console", mock_console),
+        patch("specfact_cli.modules.module_registry.src.commands.install_module", side_effect=_fake_install),
+        patch(
+            "specfact_cli.modules.module_registry.src.commands._read_installed_module_version",
+            return_value="0.2.0",
+        ),
+    ):
+        _run_marketplace_upgrades(["nold-ai/specfact-backlog"], by_id, {})
+
+    mock_console.status.assert_called()
+
+
+def test_resolve_one_upgrade_name_accepts_namespaced_id_when_installed_key_is_short() -> None:
+    """`specfact module upgrade nold-ai/specfact-backlog` must resolve when list uses short id keys."""
+    by_id: dict[str, dict[str, Any]] = {
+        "specfact-backlog": {
+            "version": "0.41.16",
+            "source": "marketplace",
+            "latest_version": "0.41.16",
+        }
+    }
+    assert _resolve_one_upgrade_name("nold-ai/specfact-backlog", by_id) == "specfact-backlog"
diff --git a/tests/unit/specfact_cli/registry/test_profile_presets.py b/tests/unit/specfact_cli/registry/test_profile_presets.py
index 28bd4821..91c8544d 100644
--- a/tests/unit/specfact_cli/registry/test_profile_presets.py
+++ b/tests/unit/specfact_cli/registry/test_profile_presets.py
@@ -111,14 +111,9 @@ def _fake_install_module(module_id: str, **kwargs: object) -> Path:
 
 
 def test_install_bundles_for_init_solo_developer_installs_both(tmp_path: Path) -> None:
-    """Running install_bundles_for_init for solo-developer bundles installs both codebase and code-review."""
-    installed_modules: list[str] = []
+    """Solo-developer bundles install via marketplace (slim CLI has no per-command bundled workflow dirs)."""
     installed_marketplace_ids: list[str] = []
 
-    def _fake_bundled(module_name: str, root: Path, **kwargs: object) -> bool:
-        installed_modules.append(module_name)
-        return True
-
     def _fake_marketplace(module_id: str, **kwargs: object) -> Path:
         installed_marketplace_ids.append(module_id)
         return tmp_path / module_id.split("/")[1]
@@ -126,7 +121,7 @@ def _fake_marketplace(module_id: str, **kwargs: object) -> Path:
     with (
         patch(
             "specfact_cli.registry.module_installer.install_bundled_module",
-            side_effect=_fake_bundled,
+            return_value=False,
         ),
         patch(
             "specfact_cli.registry.module_installer.install_module",
@@ -139,7 +134,5 @@ def _fake_marketplace(module_id: str, **kwargs: object) -> Path:
             non_interactive=True,
         )
 
-    assert len(installed_modules) > 0, "Bundled modules should be installed for specfact-codebase"
-    assert any("specfact-code-review" in mid for mid in installed_marketplace_ids), (
-        "Marketplace installer should be called for specfact-code-review"
-    )
+    assert "nold-ai/specfact-codebase" in installed_marketplace_ids
+    assert "nold-ai/specfact-code-review" in installed_marketplace_ids
diff --git a/tests/unit/specfact_cli/test_module_not_found_error.py b/tests/unit/specfact_cli/test_module_not_found_error.py
index a03c1b26..6b7bbc6e 100644
--- a/tests/unit/specfact_cli/test_module_not_found_error.py
+++ b/tests/unit/specfact_cli/test_module_not_found_error.py
@@ -45,6 +45,14 @@ def test_module_not_found_error_includes_uvx_command() -> None:
     )
 
 
+def test_no_flat_import_in_missing_bundle_map() -> None:
+    """Flat `import` is not supported; hints use `code` / `project` groups only."""
+    from specfact_cli.cli import _INVOKED_TO_MARKETPLACE_MODULE
+
+    assert "import" not in _INVOKED_TO_MARKETPLACE_MODULE
+    assert _INVOKED_TO_MARKETPLACE_MODULE["project"] == "nold-ai/specfact-project"
+
+
 def test_module_not_found_error_includes_init_profile_placeholder() -> None:
     """Module-not-found error for 'code' command must include init --profile guidance."""
     result = runner.invoke(app, ["code"])
diff --git a/tools/semgrep/README.md b/tools/semgrep/README.md
index 72b5cb78..3e7c9b9c 100644
--- a/tools/semgrep/README.md
+++ b/tools/semgrep/README.md
@@ -8,6 +8,16 @@ This directory contains Semgrep rules for:
 
 **Note**: These files (`tools/semgrep/*.yml`) are used for **development** (hatch scripts, local testing). For **runtime** use in the installed package, the files are bundled as `src/specfact_cli/resources/semgrep/*.yml` and will be automatically included in the package distribution.
 
+### Running Semgrep (1.38+)
+
+Semgrep no longer auto-discovers `.semgrep.yml` in the project root; pass **`--config`** explicitly ([CLI reference](https://semgrep.dev/docs/cli-reference)).
+
+- **All rules in this directory**: `hatch run semgrep-full src` (uses `semgrep --config tools/semgrep`).
+- **Single rule file** (e.g. async only): `hatch run scan src` (uses `tools/semgrep/async.yml`).
+- **Raw CLI**: `semgrep --config tools/semgrep src`
+
+The Hatch env includes **`setuptools`** so Semgrep’s OpenTelemetry stack can import `pkg_resources` on Python 3.12+ minimal venvs.
+
 ## Rules
 
 ### `async.yml` - Python Async Anti-Patterns