fix: GitHub Pages configuration and linting improvements

.github/workflows/pr-orchestrator.yml

@@ -344,64 +344,3 @@ jobs:
             fi
           } >> "$GITHUB_STEP_SUMMARY"
 
-  build-and-push-container:
-    name: Build and Push Container
-    runs-on: ubuntu-latest
-    needs: [package-validation]
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    permissions:
-      contents: read
-      packages: write
-      id-token: write
-    env:
-      REGISTRY: ghcr.io
-      IMAGE_NAME: ${{ github.repository }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Compute tags
-        id: vars
-        run: |
-          COMMIT_SHA="${{ github.sha }}"
-          SHORT_SHA="${COMMIT_SHA:0:8}"
-          TIMESTAMP=$(date -u +%Y%m%d-%H%M%S)
-          VERSION_TAG="$SHORT_SHA-$TIMESTAMP"
-
-          {
-            printf 'SHORT_SHA=%s\n' "$SHORT_SHA"
-            printf 'VERSION_TAG=%s\n' "$VERSION_TAG"
-          } >> "$GITHUB_ENV"
-
-      - name: Log in to ghcr.io
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Build & Push specfact-cli
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: ./dockerfile
-          push: true
-          tags: |
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.VERSION_TAG }}
-
-      - name: Summary
-        if: always()
-        run: |
-          {
-            echo "## Container Build Summary"
-            echo "| Parameter | Value |"
-            echo "|-----------|--------|"
-            echo "| Branch | main |"
-            echo "| Version Tag | $VERSION_TAG |"
-            echo "| Image | \`${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest\` |"
-            echo "| Tagged | \`${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:$VERSION_TAG\` |"
-          } >> "$GITHUB_STEP_SUMMARY"

_config.yml

@@ -3,9 +3,9 @@
 
 title: SpecFact CLI Documentation
 description: >-
-  Complete documentation for SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
-baseurl: "" # Set to "/specfact-cli" if using project pages, "" for user/organization pages
-url: "https://nold-ai.github.io" # Set to your GitHub Pages domain
+  Complete documentation for SpecFact CLI - Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts.
+baseurl: "/specfact-cli" # Project pages require baseurl
+url: "https://nold-ai.github.io" # GitHub Pages domain
 
 # Build settings
 markdown: kramdown
@@ -51,26 +51,35 @@ defaults:
     values:
       layout: default
       permalink: /:basename/
+  - scope:
+      path: "getting-started"
+    values:
+      layout: default
+  - scope:
+      path: "guides"
+    values:
+      layout: default
+  - scope:
+      path: "reference"
+    values:
+      layout: default
+  - scope:
+      path: "examples"
+    values:
+      layout: default
 
 # Theme settings (using minimal theme for clean look)
 theme: minima
 minima:
   social:
-    github: nold-ai/specfact-cli
+    github:
+      username: nold-ai
+      repository: specfact-cli
   author:
     name: NOLD AI
     email: [email protected]
-
-# Navigation
-navigation:
-  - title: Getting Started
-    url: /getting-started/
-  - title: Guides
-    url: /guides/
-  - title: Reference
-    url: /reference/
-  - title: Examples
-    url: /examples/
+  skin: dark # or light, auto
+  show_excerpts: true
 
 # Footer
 footer:

docs/index.md

@@ -1,61 +1,56 @@
 ---
 layout: default
 title: SpecFact CLI Documentation
-description: Everything you need to know about using SpecFact CLI
+description: Brownfield-first CLI for reverse engineering legacy Python code into specs with runtime contract enforcement
 ---
 
-> **Everything you need to know about using SpecFact CLI**
+# SpecFact CLI Documentation
+
+**Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts**
+
+SpecFact CLI helps you modernize legacy codebases by automatically extracting specifications from existing code and enforcing them at runtime to prevent regressions.
 
 ---
 
-## 📚 Documentation
+## 🚀 Quick Start
 
 ### New to SpecFact CLI?
 
 **Primary Use Case**: Modernizing legacy Python codebases
 
-Start here:
-
-1. **[Getting Started](getting-started/README.md)** - Install and run your first command
-2. **[Modernizing Legacy Code?](guides/brownfield-engineer.md)** ⭐ **PRIMARY** - Brownfield-first guide
-3. **[The Brownfield Journey](guides/brownfield-journey.md)** ⭐ - Complete modernization workflow
-4. **[Use Cases](guides/use-cases.md)** - See real-world examples
-5. **[Command Reference](reference/commands.md)** - Learn all available commands
+1. **[Installation](getting-started/installation.md)** - Get started in 60 seconds
+2. **[First Steps](getting-started/first-steps.md)** - Run your first command
+3. **[Modernizing Legacy Code](guides/brownfield-engineer.md)** ⭐ **PRIMARY** - Brownfield-first guide
+4. **[The Brownfield Journey](guides/brownfield-journey.md)** ⭐ - Complete modernization workflow
 
 ### Using GitHub Spec-Kit?
 
-**Secondary Use Case**: SpecFact CLI complements Spec-Kit by adding automated enforcement to Spec-Kit's interactive authoring:
+**Secondary Use Case**: Add automated enforcement to your Spec-Kit projects
 
-- **[The Journey: From Spec-Kit to SpecFact](guides/speckit-journey.md)** - Add automated enforcement to your Spec-Kit projects
+- **[From Spec-Kit to SpecFact](guides/speckit-journey.md)** - Add enforcement to Spec-Kit projects
 - **[Spec-Kit Comparison](guides/speckit-comparison.md)** - Understand when to use each tool
 
+## 📚 Documentation
+
 ### Guides
 
+- **[Use Cases](guides/use-cases.md)** - Real-world scenarios and workflows
 - **[IDE Integration](guides/ide-integration.md)** - Set up slash commands in your IDE
 - **[CoPilot Mode](guides/copilot-mode.md)** - Using `--mode copilot` on CLI
-- **[Use Cases](guides/use-cases.md)** - Real-world scenarios
+- **[Troubleshooting](guides/troubleshooting.md)** - Common issues and solutions
 - **[Competitive Analysis](guides/competitive-analysis.md)** - How SpecFact compares
 
-### Reference Documentation
+### Reference
 
 - **[Command Reference](reference/commands.md)** - Complete command documentation
 - **[Architecture](reference/architecture.md)** - Technical design and principles
 - **[Operational Modes](reference/modes.md)** - CI/CD vs CoPilot modes
 - **[Directory Structure](reference/directory-structure.md)** - Project structure
 
----
-
-## 🚀 Quick Links
-
-### Common Tasks
+### Examples
 
-- **[Install SpecFact CLI](getting-started/installation.md)**
-- **[Modernize Legacy Code](guides/brownfield-engineer.md)** ⭐ **PRIMARY** - Reverse engineer existing code into specs
-- **[The Brownfield Journey](guides/brownfield-journey.md)** ⭐ - Complete modernization workflow
-- **[Set Up IDE Integration](guides/ide-integration.md)** - Initialize slash commands in your IDE
-- **[Analyze existing code](guides/use-cases.md#use-case-1-brownfield-code-modernization)** ⭐ **PRIMARY**
-- **[Add enforcement to Spec-Kit projects](guides/use-cases.md#use-case-2-github-spec-kit-migration)** - Secondary use case
-- **[Start a new project](guides/use-cases.md#use-case-3-greenfield-spec-first-development)** - Alternative workflow
+- **[Brownfield Examples](examples/)** - Real-world modernization examples
+- **[Quick Examples](examples/quick-examples.md)** - Code snippets and patterns
 
 ---