docs: align core docs and sync pending changes

CHANGELOG.md

@@ -32,6 +32,7 @@ All notable changes to this project will be documented in this file.
 - Module source relocation to bundle namespaces with compatibility shims: legacy `specfact_cli.modules.*` imports now re-export from `specfact_<bundle>.*` namespaces during migration.
 - Official module install output now explicitly confirms verification status (`Verified: official (nold-ai)`).
 - Documentation updates across getting-started, docs landing page, module categories, marketplace guides, layout navigation, and root README to reflect marketplace-distributed official bundles.
+- Full docs alignment audit for the lean-core plus modules-repo architecture (OpenSpec change `docs-01-core-modules-docs-alignment`, issue [#348](https://github.com/nold-ai/specfact-cli/issues/348)): README, docs landing pages, reference pages, tutorials, and publishing/signing guidance were reviewed and corrected so command examples use grouped command paths, bundle ownership is attributed to `specfact-cli-modules`, and temporary-in-core module docs are explicitly marked for future migration.
 - Core help/registry behavior now mounts category groups only for installed bundles, preventing non-installed groups from appearing at top level.
 - Marketplace package loader now resolves namespaced command entrypoints (`src/<package>/<command>/app.py`) for installed modules.
 - Installed bundle detection now infers `specfact-*` bundle IDs from namespaced module names when manifest `bundle` metadata is absent.

README.md

@@ -170,13 +170,12 @@ Start with:
 
 ## Modules and Capabilities
 
-**Core modules**
+**Core runtime**
 
-- **Analyze**: Extract specs and plans from existing code.
-- **Validate**: Enforce contracts, run reproducible checks, and block regressions.
-- **Report**: CI/CD summaries and evidence outputs.
+- **Permanent commands**: `init`, `module`, `upgrade`
+- **Core responsibilities**: lifecycle, registry, trust, contracts, orchestration, shared runtime utilities
 
-**Agile DevOps modules**
+**Marketplace-installed bundles**
 
 - **Backlog**: Refinement, dependency analysis, sprint summaries, risk rollups.
 - **Ceremony**: Standup, refinement, and planning entry points.
@@ -199,7 +198,8 @@ For technical architecture details (module lifecycle, registry internals, adapte
 
 SpecFact ships official bundle packages via the dedicated marketplace registry repository
 `nold-ai/specfact-cli-modules`.
-Bundle/module docs now live in the modules repository docs site:
+Bundle-specific docs are still temporarily hosted in this docs set while the long-term
+bundle docs home is prepared in the modules repository docs site:
 `https://nold-ai.github.io/specfact-cli-modules/`.
 
 Install examples:
@@ -225,6 +225,10 @@ auto-install dependencies:
 - `nold-ai/specfact-spec` pulls `nold-ai/specfact-project`
 - `nold-ai/specfact-govern` pulls `nold-ai/specfact-project`
 
+Use this repo's docs for the current CLI/runtime release branch. Module-specific guides
+will move to `specfact-cli-modules` so future bundle-only changes do not require ongoing
+docs maintenance in long-lived `specfact-cli` release branches.
+
 ---
 
 ## Where SpecFact Fits

docs/README.md

@@ -22,18 +22,18 @@ Most tools help **either** coders **or** agile teams. SpecFact does both:
 Recommended command entrypoints:
 - `specfact backlog ceremony standup ...`
 - `specfact backlog ceremony refinement ...`
-- `specfact policy validate ...`
-- `specfact policy suggest ...`
+- `specfact backlog policy validate ...`
+- `specfact backlog policy suggest ...`
 
 What the Policy Engine does in practice:
 - Converts team working agreements (DoR, DoD, flow/PI readiness) into deterministic checks.
 - Flags exact policy gaps per backlog item with actionable evidence pointers.
 - Produces patch-ready suggestions so teams can remediate quickly.
 
 Start with:
-- `specfact policy init --template scrum`
-- `specfact policy validate --group-by-item`
-- `specfact policy suggest --group-by-item --limit 5`
+- `specfact backlog policy init --template scrum`
+- `specfact backlog policy validate --group-by-item`
+- `specfact backlog policy suggest --group-by-item --limit 5`
 
 **Try it now**
 
@@ -55,13 +55,12 @@ Start with:
 
 ## Modules and Capabilities
 
-**Core modules**
+**Core runtime**
 
-- **Analyze**: Extract specs and plans from existing code.
-- **Validate**: Enforce contracts, run reproducible checks, and block regressions.
-- **Report**: CI/CD summaries and evidence outputs.
+- **Permanent commands**: `init`, `module`, `upgrade`
+- **Core responsibilities**: lifecycle, registry, trust, contracts, orchestration, shared runtime utilities
 
-**Agile DevOps modules**
+**Marketplace-installed bundles**
 
 - **Backlog**: Refinement, dependency analysis, sprint summaries, risk rollups.
 - **Ceremony**: Standup, refinement, and planning entry points.
@@ -85,12 +84,16 @@ SpecFact CLI uses a lifecycle-managed module system:
 
 This is the baseline for marketplace-driven module lifecycle and future community module distribution.
 
+Module-specific guides are still temporarily hosted in this docs set while the long-term
+bundle docs home is prepared in `nold-ai/specfact-cli-modules`.
+
 ### Why the Module System Is the Foundation
 
 This architecture intentionally separates the CLI core from feature modules:
 
 - Core provides lifecycle, registry, contracts, and orchestration.
-- Modules provide feature-specific command logic and integrations.
+- Official workflow bundles are authored and released from `nold-ai/specfact-cli-modules`.
+- This docs set still hosts bundle-specific guidance temporarily for the `0.40.x` release line.
 - Compatibility shims preserve legacy import paths during migration windows.
 
 Practical outcomes:

docs/_layouts/default.html

@@ -142,16 +142,16 @@ <h2 class="docs-sidebar-title">
 
               <p class="docs-nav-section">Guides</p>
               <ul>
+                <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/marketplace/' | relative_url }}">Marketplace Bundles</a></li>
                 <li><a href="{{ '/guides/command-chains/' | relative_url }}">Command Chains</a></li>
                 <li><a href="{{ '/guides/agile-scrum-workflows/' | relative_url }}">Agile/Scrum Workflows</a></li>
                 <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/module-development/' | relative_url }}">Module Development</a></li>
                 <li><a href="{{ '/guides/adapter-development/' | relative_url }}">Adapter Development</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/marketplace/' | relative_url }}">Marketplace Bundles</a></li>
                 <li><a href="{{ '/guides/module-signing-and-key-rotation/' | relative_url }}">Module Signing and Key Rotation</a></li>
                 <li><a href="{{ '/guides/using-module-security-and-extensions/' | relative_url }}">Using Module Security and Extensions</a></li>
                 <li><a href="{{ '/guides/brownfield-engineer/' | relative_url }}">Working With Existing Code</a></li>
@@ -181,6 +181,7 @@ <h2 class="docs-sidebar-title">
               <ul>
                 <li><a href="{{ '/reference/' | relative_url }}">Reference Documentation</a></li>
                 <li><a href="{{ '/reference/commands/' | relative_url }}">Command Reference</a></li>
+                <li><a href="{{ '/reference/module-categories/' | relative_url }}">Module Categories</a></li>
                 <li><a href="{{ '/reference/thorough-codebase-validation/' | relative_url }}">Thorough Codebase Validation</a></li>
                 <li><a href="{{ '/reference/authentication/' | relative_url }}">Authentication</a></li>
                 <li><a href="{{ '/reference/architecture/' | relative_url }}">Architecture</a></li>
@@ -191,7 +192,6 @@ <h2 class="docs-sidebar-title">
                 <li><a href="{{ '/reference/projectbundle-schema/' | relative_url }}">ProjectBundle Schema</a></li>
                 <li><a href="{{ '/reference/module-contracts/' | relative_url }}">Module Contracts</a></li>
                 <li><a href="{{ '/reference/module-security/' | relative_url }}">Module Security</a></li>
-                <li><a href="{{ '/reference/module-categories/' | relative_url }}">Module Categories</a></li>
                 <li><a href="{{ '/reference/bridge-registry/' | relative_url }}">Bridge Registry</a></li>
                 <li><a href="{{ '/guides/integrations-overview/' | relative_url }}">Integrations Overview</a></li>
               </ul>

docs/adapters/azuredevops.md

@@ -6,6 +6,10 @@ permalink: /adapters/azuredevops/
 
 # Azure DevOps Adapter
 
+
+> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the
+> current release line and is planned to migrate to `specfact-cli-modules`.
+
 The Azure DevOps adapter provides bidirectional synchronization between OpenSpec change proposals and Azure DevOps work items, enabling agile DevOps-driven workflow support for enterprise teams.
 
 ## Overview
@@ -64,7 +68,7 @@ The adapter automatically derives work item type from your project's process tem
 You can override with `--ado-work-item-type`:
 
 ```bash
-specfact sync bridge --adapter ado --mode export-only \
+specfact project sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --ado-work-item-type "Bug" \
@@ -446,7 +450,7 @@ This handles cases where:
 
 ```bash
 # Export OpenSpec change proposals to Azure DevOps work items
-specfact sync bridge --adapter ado --mode export-only \
+specfact project sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --repo /path/to/openspec-repo
@@ -456,7 +460,7 @@ specfact sync bridge --adapter ado --mode export-only \
 
 ```bash
 # Import work items AND export proposals
-specfact sync bridge --adapter ado --bidirectional \
+specfact project sync bridge --adapter ado --bidirectional \
   --ado-org your-org \
   --ado-project your-project \
   --repo /path/to/openspec-repo
@@ -466,7 +470,7 @@ specfact sync bridge --adapter ado --bidirectional \
 
 ```bash
 # Import specific work items into bundle
-specfact sync bridge --adapter ado --mode bidirectional \
+specfact project sync bridge --adapter ado --mode bidirectional \
   --ado-org your-org \
   --ado-project your-project \
   --bundle main \
@@ -478,7 +482,7 @@ specfact sync bridge --adapter ado --mode bidirectional \
 
 ```bash
 # Update existing work item with latest proposal content
-specfact sync bridge --adapter ado --mode export-only \
+specfact project sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --change-ids add-feature-x \
@@ -490,7 +494,7 @@ specfact sync bridge --adapter ado --mode export-only \
 
 ```bash
 # Detect code changes and add progress comments
-specfact sync bridge --adapter ado --mode export-only \
+specfact project sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --track-code-changes \
@@ -502,7 +506,7 @@ specfact sync bridge --adapter ado --mode export-only \
 
 ```bash
 # Export from bundle to ADO (uses stored lossless content)
-specfact sync bridge --adapter ado --mode export-only \
+specfact project sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --bundle main \

docs/adapters/github.md

@@ -6,6 +6,10 @@ permalink: /adapters/github/
 
 # GitHub Adapter
 
+
+> Temporary docs note: this bundle-focused page remains hosted in the core docs set for the
+> current release line and is planned to migrate to `specfact-cli-modules`.
+
 The GitHub adapter provides bidirectional synchronization between OpenSpec change proposals and GitHub Issues, enabling agile DevOps-driven workflow support.
 
 ## Overview
@@ -334,14 +338,14 @@ To create a GitHub issue from an OpenSpec change and have the issue number/URL w
 
 ```bash
 # Export one or more changes; creates issues and updates proposal.md Source Tracking
-specfact sync bridge --adapter github --mode export-only \
+specfact project sync bridge --adapter github --mode export-only \
   --repo . \
   --repo-owner nold-ai \
   --repo-name specfact-cli \
   --change-ids <change-id>
 
 # Example: export backlog-scrum-05-summarize-markdown-output
-specfact sync bridge --adapter github --mode export-only \
+specfact project sync bridge --adapter github --mode export-only \
   --repo . \
   --repo-owner nold-ai \
   --repo-name specfact-cli \
@@ -362,15 +366,15 @@ When you improve comment logic or branch detection, use `--include-archived` to
 
 ```bash
 # Update all archived proposals with new comment logic
-specfact sync bridge --adapter github --mode export-only \
+specfact project sync bridge --adapter github --mode export-only \
   --repo-owner your-org \
   --repo-name your-repo \
   --include-archived \
   --update-existing \
   --repo /path/to/openspec-repo
 
 # Update specific archived proposal
-specfact sync bridge --adapter github --mode export-only \
+specfact project sync bridge --adapter github --mode export-only \
   --repo-owner your-org \
   --repo-name your-repo \
   --change-ids add-code-change-tracking \

docs/examples/brownfield-data-pipeline.md

@@ -29,7 +29,7 @@ You inherited a 5-year-old Python data pipeline with:
 
 ```bash
 # Analyze the legacy data pipeline
-specfact import from-code customer-etl \
+specfact project import from-code customer-etl \
   --repo ./legacy-etl-pipeline \
   --language python
 
@@ -81,7 +81,7 @@ After extracting the plan, create a hard SDD manifest:
 
 ```bash
 # Create SDD manifest from the extracted plan
-specfact plan harden customer-etl
+specfact project plan harden customer-etl
 ```
 
 ### Output
@@ -109,7 +109,7 @@ Validate that your SDD manifest matches your plan:
 
 ```bash
 # Validate SDD manifest against plan
-specfact enforce sdd customer-etl
+specfact govern enforce sdd customer-etl
 ```
 
 ### Output
@@ -131,7 +131,7 @@ Promote your plan to "review" stage (requires valid SDD):
 
 ```bash
 # Promote plan to review stage
-specfact plan promote customer-etl --stage review
+specfact project plan promote customer-etl --stage review
 ```
 
 **Why this matters**: Plan promotion enforces SDD presence, ensuring you have a hard spec before starting modernization work.
@@ -211,7 +211,7 @@ def transform_order(raw_order: Dict[str, Any]) -> Dict[str, Any]:
 After adding contracts, re-validate your SDD:
 
 ```bash
-specfact enforce sdd customer-etl
+specfact govern enforce sdd customer-etl
 ```
 
 ---
@@ -338,7 +338,7 @@ def transform_order(raw_order: Dict[str, Any]) -> Dict[str, Any]:
 
 **Solution:**
 
-1. Ran `specfact import from-code` → 47 features extracted in 12 seconds
+1. Ran `specfact project import from-code` → 47 features extracted in 12 seconds
 2. Added contracts to 23 critical data transformation functions
 3. CrossHair discovered 6 edge cases in legacy validation logic
 4. Enforced contracts during migration, blocked 11 regressions