docs: restructure core site IA to 6-section progressive nav

docs/README.md

@@ -41,7 +41,7 @@ This docs set keeps release-line overview and handoff content for bundle workflo
 - [Getting Started](getting-started/README.md)
 - [Command Reference](reference/commands.md)
 - [Reference Index](reference/README.md)
-- [Architecture Reference](reference/architecture.md)
+- [Architecture Reference](architecture/overview.md)
 
 ## Current Core Command Topology
 
@@ -82,7 +82,7 @@ Start with:
 
 ### Recommended next reads
 
-- [Installing Modules](guides/installing-modules.md)
+- [Installing Modules](module-system/installing-modules.md)
 - [Module Categories](reference/module-categories.md)
 - [Module Contracts](reference/module-contracts.md)
 - [Canonical modules docs site](https://modules.specfact.io/)

docs/_layouts/default.html

@@ -131,75 +131,56 @@ <h2 class="docs-sidebar-title">
               <p class="docs-nav-section">Getting Started</p>
               <ul>
                 <li><a href="{{ '/getting-started/installation/' | relative_url }}">Installation</a></li>
-                <li><a href="{{ '/guides/migration-guide/' | relative_url }}">Upgrade Guide</a></li>
-                <li><a href="{{ '/getting-started/first-steps/' | relative_url }}">First Steps</a></li>
-                <li><a href="{{ '/getting-started/module-bootstrap-checklist/' | relative_url }}">Module Bootstrap Checklist</a></li>
-                <li><a href="{{ '/getting-started/tutorial-backlog-quickstart-demo/' | relative_url }}">Tutorial: Backlog Quickstart Demo</a></li>
-                <li><a href="{{ '/getting-started/tutorial-backlog-refine-ai-ide/' | relative_url }}">Tutorial: Backlog Refine with AI IDE</a></li>
-                <li><a href="{{ '/getting-started/tutorial-daily-standup-sprint-review/' | relative_url }}">Tutorial: Daily Standup and Sprint Review</a></li>
+                <li><a href="{{ '/getting-started/quickstart/' | relative_url }}">5-Minute Quickstart</a></li>
               </ul>
 
-              <p class="docs-nav-section">Guides</p>
+              <p class="docs-nav-section">Core CLI</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="{{ '/modules/code-review/' | relative_url }}">Code Review Module</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="{{ '/core-cli/init/' | relative_url }}">specfact init</a></li>
+                <li><a href="{{ '/core-cli/module/' | relative_url }}">specfact module</a></li>
+                <li><a href="{{ '/core-cli/upgrade/' | relative_url }}">specfact upgrade</a></li>
+                <li><a href="{{ '/core-cli/modes/' | relative_url }}">Operational Modes</a></li>
+                <li><a href="{{ '/core-cli/debug-logging/' | relative_url }}">Debug Logging</a></li>
+              </ul>
+
+              <p class="docs-nav-section">Module System</p>
+              <ul>
+                <li><a href="{{ '/module-system/installing-modules/' | relative_url }}">Installing Modules</a></li>
+                <li><a href="{{ '/module-system/module-marketplace/' | relative_url }}">Module Marketplace</a></li>
+                <li><a href="{{ '/module-system/marketplace/' | relative_url }}">Marketplace Bundles</a></li>
+                <li><a href="{{ '/module-system/custom-registries/' | relative_url }}">Custom Registries</a></li>
+                <li><a href="{{ '/module-system/bootstrap-checklist/' | relative_url }}">Bootstrap Checklist</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/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>
-                <li><a href="{{ '/guides/brownfield-journey/' | relative_url }}">Existing Code Journey</a></li>
-                <li><a href="{{ '/guides/sidecar-validation/' | relative_url }}">Sidecar Validation</a></li>
-                <li><a href="{{ '/guides/ux-features/' | relative_url }}">UX Features</a></li>
-                <li><a href="{{ '/guides/use-cases/' | relative_url }}">Use Cases</a></li>
-                <li><a href="{{ '/guides/ide-integration/' | relative_url }}">IDE Integration</a></li>
-                <li><a href="{{ '/guides/copilot-mode/' | relative_url }}">CoPilot Mode</a></li>
-                <li><a href="{{ '/guides/troubleshooting/' | relative_url }}">Troubleshooting</a></li>
-                <li><a href="{{ '/guides/competitive-analysis/' | relative_url }}">Competitive Analysis</a></li>
+                <li><a href="{{ '/guides/module-signing-and-key-rotation/' | relative_url }}">Module Signing</a></li>
               </ul>
 
-              <p class="docs-nav-section">DevOps & Backlog Sync</p>
+              <p class="docs-nav-section">Architecture</p>
               <ul>
-                <li><a href="{{ '/guides/devops-adapter-integration/' | relative_url }}">DevOps Integration Guide</a></li>
-                <li><a href="{{ '/guides/backlog-refinement/' | relative_url }}">Backlog Refinement</a></li>
-                <li><a href="{{ '/getting-started/tutorial-backlog-quickstart-demo/' | relative_url }}">Backlog Quickstart Demo</a></li>
-                <li><a href="{{ '/reference/authentication/' | relative_url }}">Authentication</a></li>
-                <li><a href="{{ '/adapters/github/' | relative_url }}">GitHub Adapter</a></li>
-                <li><a href="{{ '/adapters/azuredevops/' | relative_url }}">Azure DevOps Adapter</a></li>
-                <li><a href="{{ '/adapters/backlog-adapter-patterns/' | relative_url }}">Backlog Adapter Patterns</a></li>
-                <li><a href="{{ '/guides/template-customization/' | relative_url }}">Template Customization</a></li>
+                <li><a href="{{ '/architecture/overview/' | relative_url }}">Architecture Overview</a></li>
+                <li><a href="{{ '/architecture/implementation-status/' | relative_url }}">Implementation Status</a></li>
+                <li><a href="{{ '/architecture/adr/' | relative_url }}">ADRs</a></li>
+                <li><a href="{{ '/reference/directory-structure/' | relative_url }}">Directory Structure</a></li>
               </ul>
 
               <p class="docs-nav-section">Reference</p>
               <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>
-                <li><a href="{{ '/architecture/implementation-status/' | relative_url }}">Architecture Implementation Status</a></li>
-                <li><a href="{{ '/architecture/adr/' | relative_url }}">Architecture ADRs</a></li>
-                <li><a href="{{ '/reference/modes/' | relative_url }}">Operational Modes</a></li>
-                <li><a href="{{ '/reference/directory-structure/' | relative_url }}">Directory Structure</a></li>
-                <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/bridge-registry/' | relative_url }}">Bridge Registry</a></li>
+                <li><a href="{{ '/reference/authentication/' | relative_url }}">Authentication</a></li>
+                <li><a href="{{ '/reference/projectbundle-schema/' | relative_url }}">ProjectBundle Schema</a></li>
                 <li><a href="{{ '/guides/integrations-overview/' | relative_url }}">Integrations Overview</a></li>
+                <li><a href="{{ '/examples/' | relative_url }}">Examples</a></li>
               </ul>
 
-              <p class="docs-nav-section">Examples</p>
+              <p class="docs-nav-section">Migration</p>
               <ul>
-                <li><a href="{{ '/examples/' | relative_url }}">All Examples</a></li>
-                <li><a href="{{ '/examples/quick-examples/' | relative_url }}">Quick Examples</a></li>
+                <li><a href="{{ '/migration/migration-guide/' | relative_url }}">Migration Guide</a></li>
+                <li><a href="{{ '/migration/migration-0.16-to-0.19/' | relative_url }}">0.16 to 0.19</a></li>
+                <li><a href="{{ '/migration/migration-cli-reorganization/' | relative_url }}">CLI Reorganization</a></li>
+                <li><a href="{{ '/migration/openspec-migration/' | relative_url }}">OpenSpec Migration</a></li>
               </ul>
             </nav>
           </div>

docs/adapters/azuredevops.md

@@ -201,7 +201,7 @@ adapter = AdoAdapter(
 
 ### Error diagnostics (PATCH failures)
 
-When a work item PATCH fails (e.g. HTTP 400 during backlog refine or status update), the CLI shows the ADO error message and a hint in the console. With `--debug`, the log includes the ADO response snippet and the JSON Patch paths attempted so you can identify the failing field. See [Debug Logging – Examining ADO API Errors](../reference/debug-logging.md#examining-ado-api-errors) and [Troubleshooting – Backlog refine or work item PATCH fails (400/422)](../guides/troubleshooting.md#backlog-refine-or-work-item-patch-fails-400422).
+When a work item PATCH fails (e.g. HTTP 400 during backlog refine or status update), the CLI shows the ADO error message and a hint in the console. With `--debug`, the log includes the ADO response snippet and the JSON Patch paths attempted so you can identify the failing field. See [Debug Logging – Examining ADO API Errors](../core-cli/debug-logging.md#examining-ado-api-errors) and [Troubleshooting – Backlog refine or work item PATCH fails (400/422)](../guides/troubleshooting.md#backlog-refine-or-work-item-patch-fails-400422).
 
 ## Usage Examples
 

docs/adapters/backlog-adapter-patterns.md

@@ -493,4 +493,4 @@ When implementing new backlog adapters:
 - **[Azure DevOps Adapter Documentation](./azuredevops.md)** - Azure DevOps adapter reference
 - **[DevOps Adapter Integration Guide](../guides/devops-adapter-integration.md)** - Complete integration guide for GitHub and ADO
 - **[Validation Integration](../validation-integration.md)** - Validation with change proposals
-- **[Bridge Adapter Interface](../reference/architecture.md#required-adapter-interface)** - Base adapter interface
+- **[Bridge Adapter Interface](../architecture/overview.md#required-adapter-interface)** - Base adapter interface

docs/architecture/README.md

@@ -29,7 +29,7 @@ Architecture documents in this folder describe the current implementation and cl
 
 ## Related Reference
 
-- [Main Architecture Reference](../reference/architecture.md)
+- [Main Architecture Reference](../architecture/overview.md)
 - [Bridge Registry](../reference/bridge-registry.md)
 - [Module Development Guide](../guides/module-development.md)
 - [Adapter Development Guide](../guides/adapter-development.md)

docs/architecture/implementation-status.md

@@ -31,6 +31,6 @@ This page tracks implemented vs planned architecture capabilities.
 
 ## References
 
-- [Architecture Reference](../reference/architecture.md)
+- [Architecture Reference](../architecture/overview.md)
 - [Architecture Docs Index](README.md)
 - [Discrepancies Report](discrepancies-report.md)

docs/reference/architecture.md → docs/architecture/overview.md

@@ -1,7 +1,9 @@
 ---
 layout: default
 title: Architecture
-permalink: /reference/architecture/
+permalink: /architecture/overview/
+redirect_from:
+  - /reference/architecture/
 ---
 
 # Architecture
@@ -61,8 +63,8 @@ Common manifest fields:
 
 See also:
 - [Module Development Guide](../guides/module-development.md)
-- [Module Contracts](module-contracts.md)
-- [Module Security](module-security.md)
+- [Module Contracts](../reference/module-contracts.md)
+- [Module Security](../reference/module-security.md)
 
 ### Core vs modules-repo ownership boundary
 
@@ -119,7 +121,7 @@ All adapters implement:
 
 See also:
 - [Adapter Development Guide](../guides/adapter-development.md)
-- [Bridge Registry](bridge-registry.md)
+- [Bridge Registry](../reference/bridge-registry.md)
 
 ## Change Tracking and Protocol Scope
 
@@ -171,4 +173,4 @@ Use `ProjectBundle` for current architecture descriptions unless explicitly disc
 
 - [Architecture Docs Index](../architecture/README.md)
 - [Implementation Status](../architecture/implementation-status.md)
-- [Directory Structure](directory-structure.md)
+- [Directory Structure](../reference/directory-structure.md)

docs/reference/debug-logging.md → docs/core-cli/debug-logging.md

@@ -1,9 +1,10 @@
 ---
 layout: default
 title: Debug Logging
-permalink: /reference/debug-logging/
+permalink: /core-cli/debug-logging/
 redirect_from:
   - /debug-logging/
+  - /reference/debug-logging/
 ---
 
 <!-- markdownlint-disable-next-line MD025 -->
@@ -216,4 +217,4 @@ Debug logs are **critical for anomaly analysis, unexpected errors/failures, repo
 
 ### Relation to Other Logging
 
-- **`~/.specfact/logs/`** is for the **global** `--debug` session log only (`specfact-debug.log`). It is **not** the same as bundle-specific `.specfact/projects/<bundle>/logs/` (used for other runtime/agent logs). See [Directory Structure](directory-structure.md).
+- **`~/.specfact/logs/`** is for the **global** `--debug` session log only (`specfact-debug.log`). It is **not** the same as bundle-specific `.specfact/projects/<bundle>/logs/` (used for other runtime/agent logs). See [Directory Structure](../reference/directory-structure.md).

docs/core-cli/init.md

@@ -0,0 +1,89 @@
+---
+layout: default
+title: specfact init
+permalink: /core-cli/init/
+description: Reference for the specfact init command - bootstrap SpecFact in a repository with profiles, IDE setup, and dependency installation.
+---
+
+# specfact init
+
+Bootstrap SpecFact CLI in a repository. Use `init ide` for IDE-specific setup; module lifecycle is under `specfact module`.
+
+## Usage
+
+```bash
+specfact init [OPTIONS]
+specfact init ide [OPTIONS]
+```
+
+## Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--repo` | DIRECTORY | Repository path (default: current directory) |
+| `--profile` | TEXT | First-run profile preset (see below) |
+| `--install` | TEXT | Comma-separated bundle names or `all` to install without prompting |
+| `--install-deps` | | Install required packages for contract enhancement |
+
+## Profiles
+
+Profiles select a default set of bundles appropriate for your team setup:
+
+| Profile | Description |
+|---------|-------------|
+| `solo-developer` | Minimal bundle set for individual projects |
+| `backlog-team` | Backlog sync and ceremony bundles for agile teams |
+| `api-first-team` | Spec validation and contract testing bundles |
+| `enterprise-full-stack` | All official bundles including governance and adapters |
+
+```bash
+# Bootstrap with the solo-developer preset
+specfact init --profile solo-developer
+
+# Install specific bundles during init
+specfact init --install backlog,code-review
+```
+
+## IDE Setup
+
+The `init ide` subcommand generates IDE-specific prompt templates and settings:
+
+```bash
+# Initialize Cursor IDE integration
+specfact init ide --ide cursor
+
+# Initialize with dependency installation
+specfact init ide --install-deps
+```
+
+This creates:
+
+- `.specfact/` directory structure
+- `.specfact/templates/backlog/field_mappings/` with default field mapping templates
+- IDE-specific command files for your AI assistant
+
+## Dependency Installation
+
+Use `--install-deps` to install optional packages required for contract enhancement (CrossHair, beartype, icontract):
+
+```bash
+specfact init --install-deps
+```
+
+Prefer `specfact init ide --install-deps` when setting up IDE integration at the same time.
+
+## Typical First-Run Sequence
+
+```bash
+# 1. Install SpecFact CLI
+pip install specfact-cli
+
+# 2. Bootstrap with a profile
+specfact init --profile solo-developer
+
+# 3. Set up IDE integration
+specfact init ide --ide cursor
+
+# 4. Verify modules are installed
+specfact module list
+```

docs/reference/modes.md → docs/core-cli/modes.md

@@ -1,9 +1,10 @@
 ---
 layout: default
 title: Operational Modes
-permalink: /reference/modes/
+permalink: /core-cli/modes/
 redirect_from:
   - /modes/
+  - /reference/modes/
 ---
 
 # Operational Modes