Update to repositioning for brownfield first strategy

Author: Dominikus Nold

.markdownlint.json

@@ -0,0 +1,7 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD033": false,
+  "MD041": false
+}
+

README.md

@@ -1,6 +1,7 @@
 # SpecFact CLI
 
-> **Stop "vibe coding", start shipping quality code with contracts**
+> **Understand and Modernize Legacy Code with Confidence**  
+> Automatically extract specs from existing Python code, then enforce them as contracts
 
 [![License](https://img.shields.io/badge/license-Sustainable%20Use-blue.svg)](LICENSE.md)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
@@ -10,16 +11,16 @@
 
 ## What is SpecFact CLI?
 
-A command-line tool that helps you write better code by enforcing **contracts** - rules that catch bugs before they reach production.
+A brownfield-first CLI that **reverse engineers your legacy code** into documented specs, then prevents regressions with runtime contract enforcement.
 
-Think of it as a **quality gate** for your development workflow that:
+**Perfect for:** Teams modernizing legacy Python systems, data pipelines, DevOps scripts
 
-- ✅ Catches async bugs automatically
-- ✅ Validates your code matches your specs
-- ✅ Blocks bad code from merging
-- ✅ Works offline, no cloud required
+**Key capabilities:**
 
-**Perfect for:** Teams who want to ship faster without breaking things.
+- ✅ **Reverse engineer legacy code** → Extract specs automatically from existing code
+- ✅ **Runtime contract enforcement** → Prevent regressions during modernization
+- ✅ **Symbolic execution** → Discover hidden edge cases with CrossHair
+- ✅ **Works offline** → No cloud required, fully local
 
 ---
 
@@ -38,12 +39,12 @@ pip install specfact-cli
 ### Your first command (< 60 seconds)
 
 ```bash
+# Modernizing legacy code? (Recommended)
+specfact import from-code --repo . --name my-project
+
 # Starting a new project?
 specfact plan init --interactive
 
-# Have existing code?
-specfact import from-code --repo . --name my-project
-
 # Using GitHub Spec-Kit?
 specfact import from-spec-kit --repo ./my-project --dry-run
 ```

docs/README.md

@@ -8,23 +8,26 @@
 
 ### New to SpecFact?
 
-**Goal**: Get started in < 5 minutes
+**Primary Goal**: Modernize legacy Python codebases in < 5 minutes
 
 1. **[Getting Started](getting-started/README.md)** - Install and run your first command
-2. **[See It In Action](examples/dogfooding-specfact-cli.md)** - Real example (< 10 seconds)
-3. **[Use Cases](guides/use-cases.md)** - Common scenarios
+2. **[Modernizing Legacy Code?](guides/brownfield-engineer.md)** ⭐ **PRIMARY** - Brownfield-first guide
+3. **[The Brownfield Journey](guides/brownfield-journey.md)** ⭐ - Complete modernization workflow
+4. **[See It In Action](examples/dogfooding-specfact-cli.md)** - Real example (< 10 seconds)
+5. **[Use Cases](guides/use-cases.md)** - Common scenarios
 
-**Time**: < 10 minutes | **Result**: Running your first command
+**Time**: < 10 minutes | **Result**: Running your first brownfield analysis
 
 ---
 
 ### Using GitHub Spec-Kit?
 
-**Goal**: Level up from interactive authoring to automated enforcement
+**Secondary Goal**: Add automated enforcement to Spec-Kit's interactive authoring
 
-1. **[The Journey: From Spec-Kit to SpecFact](guides/speckit-journey.md)** ⭐ - Complete migration guide
-2. **[Migration Use Case](guides/use-cases.md#use-case-1-github-spec-kit-migration)** - Step-by-step
-3. **[Bidirectional Sync](guides/use-cases.md#use-case-1-github-spec-kit-migration)** - Keep both tools in sync
+1. **[The Journey: From Spec-Kit to SpecFact](guides/speckit-journey.md)** - Add enforcement to Spec-Kit projects
+2. **[Spec-Kit Comparison](guides/speckit-comparison.md)** - Understand when to use each tool
+3. **[Migration Use Case](guides/use-cases.md#use-case-2-github-spec-kit-migration)** - Step-by-step
+4. **[Bidirectional Sync](guides/use-cases.md#use-case-2-github-spec-kit-migration)** - Keep both tools in sync
 
 **Time**: 15-30 minutes | **Result**: Automated enforcement for your Spec-Kit project
 
@@ -65,8 +68,20 @@
 
 ### User Guides
 
-- [Spec-Kit Journey](guides/speckit-journey.md) ⭐ - Migration guide
-- [Use Cases](guides/use-cases.md) - Real-world scenarios
+#### Primary Use Case: Brownfield Modernization ⭐
+
+- [Brownfield Engineer Guide](guides/brownfield-engineer.md) ⭐ **PRIMARY** - Complete modernization guide
+- [The Brownfield Journey](guides/brownfield-journey.md) ⭐ **PRIMARY** - Step-by-step workflow
+- [Brownfield ROI](guides/brownfield-roi.md) ⭐ - Calculate savings
+- [Use Cases](guides/use-cases.md) ⭐ - Real-world scenarios (brownfield primary)
+
+#### Secondary Use Case: Spec-Kit Integration
+
+- [Spec-Kit Journey](guides/speckit-journey.md) - Add enforcement to Spec-Kit projects
+- [Spec-Kit Comparison](guides/speckit-comparison.md) - Understand when to use each tool
+
+#### General Guides
+
 - [Workflows](guides/workflows.md) - Common daily workflows
 - [IDE Integration](guides/ide-integration.md) - Slash commands
 - [CoPilot Mode](guides/copilot-mode.md) - Enhanced prompts