nold-ai · djm81 · Feb 21, 2026 · Feb 20, 2026 · Feb 21, 2026 · Feb 21, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,22 @@ All notable changes to this project will be documented in this file.
 **Important:** Changes need to be documented below this block as this is the header section. Each section should be separated by a horizontal rule. Newer changelog entries need to be added on top of prior ones to keep the history chronological with most recent changes first.
 
 ---
+## [0.35.0] - 2026-02-20
+
+### Added
+
+- Central module marketplace foundations (OpenSpec change `marketplace-01-central-module-registry`) with multi-location discovery, source tracking (`builtin`/`marketplace`/`custom`), and source-priority shadow handling.
+- New module registry client and installer workflows for fetching registry index, secure module download with checksum verification, install/uninstall operations, and core compatibility validation.
+- New `specfact module` command group with `install`, `uninstall`, `search`, `list`, and `upgrade` subcommands.
+- New docs: [Installing Modules](docs/guides/installing-modules.md) and [Module Marketplace](docs/guides/module-marketplace.md), plus architecture and sidebar updates for marketplace workflows.
+
+### Changed
+
+- Module package metadata now includes `source` to persist module origin across discovery and lifecycle registration.
+- README module lifecycle baseline now includes marketplace command entry points.
+
+---
+
 ## [0.34.1] - 2026-02-18
 
 ### Fixed

diff --git a/README.md b/README.md
@@ -158,13 +158,15 @@ Start with:
 
 SpecFact now has a lifecycle-managed module system:
 
-- `specfact init` is bootstrap-first: initializes local CLI state, discovers installed modules, and reports prompt status.
+- `specfact init` is bootstrap-first: initializes local CLI state and reports prompt status.
 - `specfact init ide` handles IDE prompt/template sync and IDE settings updates.
-- `specfact init --list-modules` shows effective enabled/disabled state.
-- `specfact init --enable-module` / `--disable-module` support:
-  - interactive selection in interactive terminals when no module id is provided
-  - explicit ids in non-interactive mode (for automation)
-  - dependency-aware safety checks with `--force` cascading enable/disable behavior
+- `specfact module` is the canonical lifecycle surface:
+  - `specfact module install <namespace/name>` installs marketplace modules into `~/.specfact/marketplace-modules/`.
+  - `specfact module list [--source builtin|marketplace|custom]` shows multi-source discovery state.
+  - `specfact module enable <id>` / `specfact module disable <id> [--force]` manage enabled state.
+  - `specfact module uninstall <name>` and `specfact module upgrade <name>` manage marketplace lifecycle.
+- `specfact init --list-modules`, `--enable-module`, and `--disable-module` remain supported as compatibility aliases during migration.
+- Module lifecycle operations keep dependency-aware safety checks with `--force` cascading behavior.
 - Module manifests support dependency and core-version compatibility enforcement at registration time.
 
 This lifecycle model is the baseline for future granular module updates and enhancements. Module installation from third-party or open-source community providers is planned, but not implemented yet.

diff --git a/docs/README.md b/docs/README.md
@@ -78,13 +78,13 @@ Start with:
 
 SpecFact CLI uses a lifecycle-managed module system:
 
-- `specfact init` bootstraps local state and manages module enable/disable lifecycle.
+- `specfact init` bootstraps local state.
 - `specfact init ide` handles IDE prompt/template installation and updates.
-- `specfact init --list-modules` shows current enabled/disabled state.
-- `--enable-module` and `--disable-module` support interactive selection in interactive terminals and explicit ids in non-interactive mode.
+- `specfact module` is the canonical lifecycle surface for install/list/show/search/enable/disable/uninstall/upgrade.
+- `specfact init --list-modules`, `--enable-module`, and `--disable-module` remain compatibility aliases.
 - Dependency and compatibility guards prevent invalid module states; `--force` enables dependency-aware cascades.
 
-This is the baseline for future granular module updates and enhancements. Third-party/community module installation is planned, but not available yet.
+This is the baseline for marketplace-driven module lifecycle and future community module distribution.
 
 ### Why the Module System Is the Foundation
 
@@ -104,6 +104,8 @@ For implementation details, see:
 
 - [Architecture](reference/architecture.md)
 - [Module Contracts](reference/module-contracts.md)
+- [Installing Modules](guides/installing-modules.md)
+- [Module Marketplace](guides/module-marketplace.md)
 
 ---
 

diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -144,6 +144,8 @@ <h2 class="docs-sidebar-title">
                 <li><a href="{{ '/guides/policy-engine-commands/' | relative_url }}">Policy Engine Commands</a></li>
                 <li><a href="{{ '/guides/creating-custom-bridges/' | relative_url }}">Creating Custom Bridges</a></li>
                 <li><a href="{{ '/guides/extending-projectbundle/' | relative_url }}">Extending ProjectBundle</a></li>
+                <li><a href="{{ '/guides/installing-modules/' | relative_url }}">Installing Modules</a></li>
+                <li><a href="{{ '/guides/module-marketplace/' | relative_url }}">Module Marketplace</a></li>
                 <li><a href="{{ '/guides/using-module-security-and-extensions/' | relative_url }}">Using Module Security and Extensions</a></li>
                 <li><a href="{{ '/brownfield-engineer/' | relative_url }}">Working With Existing Code</a></li>
                 <li><a href="{{ '/brownfield-journey/' | relative_url }}">Existing Code Journey</a></li>

diff --git a/docs/guides/README.md b/docs/guides/README.md
@@ -27,6 +27,8 @@ Practical guides for using SpecFact CLI effectively.
 - **[Backlog Refinement](backlog-refinement.md)** 🆕 **NEW FEATURE** - AI-assisted template-driven refinement for standardizing work items with persona/framework filtering, sprint/iteration support, and DoR validation
 - **[Specmatic Integration](specmatic-integration.md)** - API contract testing with Specmatic (validate specs, generate tests, mock servers)
 - **[Troubleshooting](troubleshooting.md)** - Common issues and solutions
+- **[Installing Modules](installing-modules.md)** - Install, list, show, search, enable/disable, uninstall, and upgrade modules
+- **[Module Marketplace](module-marketplace.md)** - Discovery priority, trust vs origin semantics, and security model
 - **[Competitive Analysis](competitive-analysis.md)** - How SpecFact compares to other tools
 - **[Operational Modes](../reference/modes.md)** - CI/CD vs CoPilot modes (reference)
 

diff --git a/docs/guides/installing-modules.md b/docs/guides/installing-modules.md
@@ -0,0 +1,110 @@
+---
+layout: default
+title: Installing Modules
+permalink: /guides/installing-modules/
+description: Install, list, show, enable, disable, uninstall, and upgrade SpecFact modules.
+---
+
+# Installing Modules
+
+Use the `specfact module` command group to manage marketplace and locally discovered modules.
+
+## Install Behavior
+
+```bash
+# Marketplace id format
+specfact module install specfact/backlog
+
+# Bare names are accepted and normalized to specfact/<name>
+specfact module install backlog
+
+# Install a specific version
+specfact module install specfact/backlog --version 0.35.0
+```
+
+Notes:
+
+- If a module is already available locally (`built-in` or `custom`), install is skipped with a clear message.
+- Invalid ids show an explicit error (`name` or `namespace/name` only).
+
+## List Modules
+
+```bash
+specfact module list
+specfact module list --show-origin
+specfact module list --source marketplace
+```
+
+Default columns:
+
+- `Module`
+- `Version`
+- `State`
+- `Trust` (`official`, `community`, `local-dev`)
+- `Publisher`
+
+With `--show-origin`, an additional `Origin` column is shown (`built-in`, `marketplace`, `custom`).
+
+## Show Detailed Module Info
+
+```bash
+specfact module show module-registry
+```
+
+This prints detailed metadata:
+
+- Name, description, version, state
+- Trust, publisher, publisher URL, license
+- Origin, tier, core compatibility
+- Full command tree (including subcommands) with short command descriptions
+
+## Search Modules
+
+```bash
+specfact module search bundle-mapper
+```
+
+Search includes both:
+
+- Marketplace registry entries (`scope=marketplace`)
+- Locally discovered modules (`scope=installed`)
+
+Results are sorted alphabetically by module id.
+
+## Enable and Disable Modules
+
+```bash
+specfact module enable backlog
+specfact module disable backlog
+specfact module disable plan --force
+```
+
+Use `--force` to allow dependency-aware cascades when required.
+
+## Uninstall Behavior
+
+```bash
+specfact module uninstall backlog
+specfact module uninstall specfact/backlog
+```
+
+Uninstall only removes marketplace-installed modules.
+
+Clear guidance is provided for:
+
+- `built-in` modules (disable instead of uninstall)
+- `custom` modules (remove from local module roots)
+- unknown/untracked modules (`module list --show-origin`)
+
+## Upgrade Behavior
+
+```bash
+# Upgrade a single marketplace module
+specfact module upgrade backlog
+
+# Upgrade all marketplace modules
+specfact module upgrade
+specfact module upgrade --all
+```
+
+Upgrade applies only to modules with origin `marketplace`.
diff --git a/docs/guides/module-marketplace.md b/docs/guides/module-marketplace.md
@@ -0,0 +1,66 @@
+---
+layout: default
+title: Module Marketplace
+permalink: /guides/module-marketplace/
+description: Registry model, discovery priority, trust semantics, and security checks for SpecFact modules.
+---
+
+# Module Marketplace
+
+SpecFact supports centralized marketplace distribution with local multi-source discovery.
+
+## Registry Overview
+
+- Registry repository: <https://github.com/nold-ai/specfact-cli-modules>
+- Index document: `registry/index.json`
+- Marketplace module id format: `namespace/name` (for example `specfact/backlog`)
+
+## Discovery and Priority
+
+Local module discovery scans these roots in priority order:
+
+1. `built-in` modules (`src/specfact_cli/modules`)
+2. `marketplace` modules (`~/.specfact/marketplace-modules`)
+3. `custom` modules (`~/.specfact/custom-modules`)
+4. extra custom roots (workspace `modules/` and `SPECFACT_MODULES_ROOTS`)
+
+If module names collide, higher-priority sources win and lower-priority entries are shadowed.
+
+## Trust vs Origin
+
+SpecFact shows both trust semantics and origin details:
+
+- `Trust` column (default): `official`, `community`, `local-dev`
+- `Origin` column (`--show-origin`): `built-in`, `marketplace`, `custom`
+
+Use:
+
+```bash
+specfact module list --show-origin
+```
+
+## Security Model
+
+Install workflow enforces integrity and compatibility checks:
+
+1. Fetch registry index
+2. Download module archive
+3. Validate SHA-256 checksum
+4. Validate module `core_compatibility` against current CLI version
+5. Install into `~/.specfact/marketplace-modules/`
+
+Checksum mismatch blocks installation.
+
+## Marketplace vs Local Modules
+
+- `specfact module install` targets marketplace modules.
+- If a requested module already exists locally (`built-in`/`custom`), install reports that no marketplace install is needed.
+- `specfact module uninstall` removes only marketplace-installed modules and provides actionable guidance for built-in/custom modules.
+
+## Module Introspection
+
+`specfact module show <name>` includes:
+
+- Module metadata (publisher, license, trust, origin, compatibility)
+- Full command tree, including subcommands
+- Short command descriptions derived from Typer command registration
diff --git a/docs/index.md b/docs/index.md
@@ -84,6 +84,16 @@ Why this matters:
 - **[Extending ProjectBundle](guides/extending-projectbundle.md)** - Declare and use namespaced extension fields on Feature/ProjectBundle
 - **[Module Security](reference/module-security.md)** - Publisher, integrity (checksum/signature), and versioned dependencies
 
+
+## Module Marketplace
+
+SpecFact now supports a central marketplace workflow for module installation and lifecycle management.
+
+- **[Installing Modules](guides/installing-modules.md)** - Install, list, uninstall, and upgrade modules
+- **[Module Marketplace](guides/module-marketplace.md)** - Registry model, security checks, and discovery priority
+
+Compatibility note: `specfact init --list-modules`, `--enable-module`, and `--disable-module` remain available as migration aliases while `specfact module` (`install`, `list`, `show`, `search`, `enable`, `disable`, `uninstall`, `upgrade`) is the canonical lifecycle command group.
+
 ## 📚 Documentation
 
 ### Guides

diff --git a/docs/reference/README.md b/docs/reference/README.md
@@ -22,6 +22,7 @@ Complete technical reference for SpecFact CLI.
 - **[Feature Keys](feature-keys.md)** - Key normalization and formats
 - **[Directory Structure](directory-structure.md)** - Project structure and organization
 - **[Schema Versioning](schema-versioning.md)** - Bundle schema versions and backward compatibility (v1.0, v1.1)
+- **[Module Security](module-security.md)** - Marketplace/module integrity and publisher metadata
 
 ## Quick Reference
 
@@ -38,6 +39,11 @@ Complete technical reference for SpecFact CLI.
 - `specfact spec generate-tests [--bundle <name>]` - Generate contract tests from specifications
 - `specfact spec mock [--bundle <name>]` - Launch mock server for development
 - `specfact init ide --ide <cursor|vscode|copilot|...>` - Initialize IDE integration explicitly
+- `specfact module install <name|namespace/name>` - Install marketplace module (bare names normalize to `specfact/<name>`)
+- `specfact module list [--source ...] [--show-origin]` - List modules with trust/publisher and optional origin details
+- `specfact module show <name>` - Show detailed module metadata and full command tree with short descriptions
+- `specfact module search <query>` - Search marketplace and installed modules
+- `specfact module uninstall <name|namespace/name>` / `specfact module upgrade [<name>|--all]` - Manage module lifecycle with source-aware behavior
 
 ### Modes
 

diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md
@@ -77,6 +77,49 @@ SpecFact is transitioning from hard-wired command wiring to a module-first archi
 - Easier interface-based testing and safer incremental migrations.
 - Better path for pending OpenSpec-driven module evolution.
 
+## Module Marketplace
+
+SpecFact supports marketplace-driven module distribution with deterministic multi-location discovery.
+
+### Discovery Pattern
+
+Module discovery scans in strict priority order:
+
+1. Built-in modules (`site-packages/specfact_cli/modules/`)
+2. Marketplace modules (`~/.specfact/marketplace-modules/`)
+3. Custom modules (`~/.specfact/custom-modules/`)
+
+When duplicate module names exist, the higher-priority source wins and shadowed modules are ignored.
+
+### Registry Client Architecture
+
+The registry client fetches `index.json` from the central module repository and resolves:
+
+- module metadata (`id`, `namespace`, `latest_version`, compatibility)
+- download URL
+- checksum for integrity validation
+
+Install and search commands degrade gracefully in offline mode.
+
+### Install Sequence
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI as specfact module install
+    participant Registry as Marketplace Registry
+    participant Local as ~/.specfact/marketplace-modules
+
+    User->>CLI: install specfact/backlog
+    CLI->>Registry: fetch index.json
+    Registry-->>CLI: module metadata + checksum
+    CLI->>Registry: download tarball
+    Registry-->>CLI: module archive
+    CLI->>CLI: verify checksum + compatibility
+    CLI->>Local: extract and register module
+    CLI-->>User: install success
+```
+
 ## Operational Modes
 
 SpecFact CLI supports two operational modes for different use cases:
@@ -626,16 +669,16 @@ class ChangeArchive(BaseModel):
 - **File**: `~/.specfact/registry/modules.json` (created when you run `specfact init`).
 - **Content**: List of `{ "id", "version", "enabled" }` per module. Only modules with `enabled: true` have their commands registered.
 - **CLI**:
-  - `specfact init --list-modules` shows effective state.
-  - `specfact init --enable-module <id>` and `--disable-module <id>` update persisted state.
-  - In interactive terminals, `specfact init --enable-module` and `specfact init --disable-module` (without ids) open an interactive selector.
+  - Canonical lifecycle surface: `specfact module` (`install`, `list`, `uninstall`, `upgrade`).
+  - Compatibility aliases: `specfact init --list-modules`, `--enable-module`, `--disable-module` remain supported during migration.
+  - In interactive terminals, bare init compatibility flags still open an interactive selector.
   - In non-interactive mode, explicit module ids are required.
   - Safe dependency guards block invalid enable/disable actions unless `--force` is used.
   - With `--force`, enable cascades to required dependencies and disable cascades to enabled dependents.
 
 ### Lifecycle notes and roadmap
 
-- `specfact init` is bootstrap/module-lifecycle focused.
+- `specfact init` is bootstrap-focused; lifecycle UX is canonical in `specfact module` with init aliases preserved for compatibility.
 - `specfact init ide` is responsible for IDE prompt/template setup.
 - This lifecycle architecture is the baseline for future granular module updates and enhancements.
 - Third-party/community module installation is planned as a next step, but not implemented yet.