specweave 0.8.17 → 0.8.18

package/CLAUDE.md

@@ -939,39 +939,58 @@ When you run `specweave init`:
    - Success message: "✔ SpecWeave core plugin installed automatically!"
    - Graceful fallback: If CLI unavailable, shows manual install instructions
 
-3. ℹ️  **Optional Plugins Suggested**
-   - Based on project detection (Git, package.json, etc.)
-   - User can install now or later
+3. ✅ **Issue Tracker Plugin Auto-Installation** (NEW! v0.8.18+)
+   - Detects GitHub/Jira/Azure DevOps from project structure
+   - Prompts for credentials (API tokens, PATs)
+   - **Automatically installs** corresponding plugin (specweave-github, specweave-jira, specweave-ado)
+   - Happens AFTER marketplace registration (ensures plugin installation succeeds)
+   - Shows detailed error messages if auto-install fails
+   - Example: Jira detected → credentials saved → `specweave-jira` plugin installed automatically
+
+4. ℹ️  **Optional Plugins Available**
+   - Suggested based on project type (frontend, backend, infrastructure)
+   - User can install later via `/plugin install specweave-{name}`
 
 **Key Architectural Change**:
 - ❌ Old: Copied `.claude-plugin/` + `plugins/` to every project (~2MB bloat)
 - ✅ New: Reference GitHub marketplace (~2KB settings.json, always up-to-date)
 
-#### Phase 2: Increment Planning (On-Demand Loading)
+#### Phase 2: Increment Planning (Intelligent Plugin Detection)
 
 When you create increments (e.g., `/specweave:increment "Add Stripe billing"`):
 
-1. **Spec Analysis** (NEW! v0.6.0+)
+1. **Spec Analysis** (v0.6.0+, Enhanced v0.8.18+)
    - increment-planner skill scans spec.md content
    - Detects keywords: "Stripe", "GitHub", "Kubernetes", "React", etc.
    - Maps keywords → required plugins (see Step 6 in increment-planner/SKILL.md)
 
-2. **Plugin Suggestion** (Non-Blocking)
+2. **🚨 AUTOMATIC Plugin Recommendation** (Enhanced v0.8.18+)
    ```
-   🔌 This increment requires additional plugins:
+   🔌 Detected plugin requirements from spec content:
 
-   Required:
-   • specweave-payments - Stripe integration (detected: "billing", "Stripe")
+   REQUIRED (will significantly improve implementation):
+   • specweave-payments - Stripe integration
+     Detected: "billing", "Stripe", "subscriptions"
+     Provides: Stripe expert agent, payment flow validation, webhook handling
+     → Without this: Manual Stripe integration, no validation
 
-   📦 Install: /plugin install specweave-payments
+   📦 Install recommended plugins:
+     /plugin install specweave-payments
 
-   Or continue without it (can install later)
+   💡 Benefits:
+     • Plugins provide specialized AI agents (Stripe expert, etc.)
+     • Skills auto-activate based on context (zero manual invocation)
+     • 70%+ context reduction (only load what you need)
+     • Best practices built-in (from real-world experience)
+
+   Would you like me to wait while you install these plugins? (Recommended)
+   Or shall I continue without them? (Limited capabilities)
    ```
 
 3. **User Decision**
-   - Install now → Plugin activates immediately (after Claude Code restart)
-   - Install later → Skills won't be available until plugin installed
-   - Skip → Increment creation continues (not blocked)
+   - Install now → Plugin activates immediately (skills available during implementation)
+   - Install later → Skills won't be available until plugin installed (can add mid-work)
+   - Skip → Increment creation continues (not blocked, but capabilities limited)
 
 #### Phase 3: Implementation (Auto-Activation)
 
@@ -987,6 +1006,43 @@ When plugins are installed:
    - 70%+ reduction vs. monolithic approach
    - Real-time: Simple React app = 16K tokens (was 50K in v0.3.7)
 
+#### Phase 4: First Increment Completion (Documentation Preview)
+
+After completing your first increment:
+
+1. **🎉 Post-First-Increment Hook** (NEW! v0.8.18+)
+   - Automatically triggers when first increment is marked complete
+   - Suggests docs-preview plugin for beautiful documentation UI
+   - Shows clear benefits and install command
+
+2. **Suggestion Format**:
+   ```
+   🎉 Congratulations! You completed your first increment!
+
+   📚 Preview your documentation in a beautiful UI?
+
+   The specweave-docs-preview plugin can generate a Docusaurus site from
+   your .specweave/docs/ folder with:
+
+      ✓ Auto-generated sidebar from folder structure
+      ✓ Hot reload (edit markdown, see changes instantly)
+      ✓ Mermaid diagram rendering
+      ✓ Priority sorting (Strategy → Specs → Architecture → ...)
+
+   📦 Install with:
+      /plugin install specweave-docs-preview
+
+   🚀 Then launch:
+      /specweave:docs preview
+   ```
+
+3. **Benefits**:
+   - Beautiful, searchable documentation site (Docusaurus 3.x)
+   - Live preview with hot reload (see changes in real-time)
+   - Auto-generated navigation from folder structure
+   - Mermaid diagrams rendered automatically
+   - Share docs with stakeholders (export static site)
+
 ### Manual Plugin Management
 
 All plugin management happens through Claude Code's native commands:
@@ -2113,7 +2169,7 @@ vim .claude-plugin/marketplace.json
 
 # 5. Test locally
 /plugin marketplace add ./.claude-plugin
-/plugin install myplugin@marketplace
+/plugin install specweave-myplugin
 ```
 
 **See**: [.claude-plugin/README.md](/.claude-plugin/README.md) for marketplace documentation

package/README.md

@@ -149,10 +149,18 @@ Auto-updates after every task via Claude Code hooks - never outdated
 ### 🤖 Intelligent Agents
 PM Agent, Architect, test-aware-planner, Quality Judge - specialized AI agents guide you
 
-### 🌍 Multilingual Support
-Work in 9 languages (Russian, Spanish, Chinese, German, French, Japanese, Korean, Portuguese) with zero-cost LLM-native translation
 
-**[→ Explore All Features](https://spec-weave.com/docs/overview/features)**
+### 🌍 Multilingual Support ($0 Cost!)
+
+Work in 11 languages with **FREE zero-cost translation**:
+
+- **Primary Approach**: In-session translation (FREE, works with any model)
+- **Optional Approach**: Automated hooks (convenience, ~$0.003/increment)
+- **11 Languages**: English, Russian, Spanish, Chinese, German, French, Japanese, Korean, Portuguese, Arabic, Hebrew
+- **Any Model**: Claude, GPT-4, Gemini, DeepSeek, and more
+- **Any Tool**: Claude Code, Cursor, Copilot, ChatGPT
+
+**Zero API costs** - uses your current conversation context for translation!
 
 ---
 

package/README.md.bak

@@ -0,0 +1,304 @@
+# SpecWeave
+
+> **AI made us fast. SpecWeave makes us sustainable.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build](https://img.shields.io/github/actions/workflow/status/anton-abyzov/specweave/test.yml?branch=develop&label=Tests)](https://github.com/anton-abyzov/specweave/actions/workflows/test.yml)
+[![E2E](https://img.shields.io/github/actions/workflow/status/anton-abyzov/specweave/e2e-smoke-test.yml?branch=develop&label=E2E)](https://github.com/anton-abyzov/specweave/actions/workflows/e2e-smoke-test.yml)
+[![Discord](https://img.shields.io/badge/Discord-Join_Server-5865F2?logo=discord&logoColor=white)](https://discord.gg/UYg4BGJ65V)
+[![YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?logo=youtube&logoColor=white)](https://www.youtube.com/@antonabyzov)
+
+---
+
+## The Problem Everyone Feels But Nobody Talks About
+
+Your AI coding assistant writes features in 30 minutes.
+
+You spend 3 days updating documentation.
+
+By day 4, the code has changed again.
+
+**The docs? Already wrong.**
+
+---
+
+## The Dirty Secret of AI Coding
+
+AI coding assistants made us:
+- ✅ **10x faster at shipping**
+- ❌ **100x worse at maintaining**
+
+We're all "vibe coding" now. Fast. Fun. Chaotic.
+
+No structure. No boundaries. No memory of why we built it this way.
+
+New developers? Lost in 1 hour.
+
+**This is not sustainable.**
+
+---
+
+## The Fortune 500 Gap
+
+Big companies don't have this problem.
+
+They have systems:
+- **PRDs** (Product Requirements) - What and why
+- **HLDs** (High-Level Design) - Architecture decisions
+- **ADRs** (Architecture Decision Records) - Why we chose X over Y
+- **Runbooks** (Operations) - How to actually run this
+- **Glossaries** (Terms) - What these acronyms mean
+
+Their docs stay updated because there's a team, a process, a **discipline**.
+
+But for solo developers and small teams?
+
+**Impossible to maintain manually.**
+
+---
+
+## What is SpecWeave?
+
+**Fortune 500 discipline. Zero overhead. AI-native.**
+
+SpecWeave is a spec-driven development framework that brings enterprise-grade processes to developers of any size—without the bureaucracy.
+
+It's not just a tool. **It's a movement.**
+
+> *"Dad, AI writes your code but you update docs MANUALLY?"*
+> — My 14-year-old daughter (who was absolutely right)
+
+**The new way:**
+- Living docs that ACTUALLY stay synced (automatically)
+- Complete knowledge system (PRDs, HLDs, ADRs, glossaries, runbooks)
+- Tests embedded in tasks (BDD format, full traceability)
+- Enterprise structure without enterprise overhead
+- **Vibe coding... but with boundaries**
+
+---
+
+## What Changes
+
+**BEFORE (Vibe Coding):**
+- "I think we used JWT tokens?"
+- "Why did we choose PostgreSQL again?"
+- "What does this acronym mean?"
+- New developer: **Lost in 1 hour**
+
+**AFTER (SpecWeave):**
+- Check ADR-003: JWT vs Session Tokens (we chose JWT, here's why)
+- Check HLD: Database section (Postgres for ACID compliance)
+- Check Glossary: All technical terms defined
+- New developer: **Productive in 1 hour**
+
+---
+
+## 📊 Engineering Metrics (DORA)
+
+[![Deploy Frequency](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.deploymentFrequency.value&label=Deploy%20Frequency&suffix=/month&color=brightgreen)](https://spec-weave.com/docs/metrics)
+[![Lead Time](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.leadTime.value&label=Lead%20Time&suffix=h&color=brightgreen)](https://spec-weave.com/docs/metrics)
+[![Change Failure Rate](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.changeFailureRate.value&label=Change%20Failure%20Rate&suffix=%25&color=brightgreen)](https://spec-weave.com/docs/metrics)
+[![MTTR](https://img.shields.io/badge/dynamic/json?url=https://raw.githubusercontent.com/anton-abyzov/specweave/develop/metrics/dora-latest.json&query=$.metrics.mttr.value&label=MTTR&suffix=min&color=brightgreen)](https://spec-weave.com/docs/metrics)
+
+[View detailed metrics dashboard →](https://spec-weave.com/docs/metrics)
+
+---
+
+## 📖 Full Documentation
+
+**For complete guides, tutorials, and API reference:**
+
+### **[spec-weave.com](https://spec-weave.com)**
+
+---
+
+## Quick Start
+
+```bash
+# Install SpecWeave CLI
+npm install -g specweave
+
+# Initialize your project
+specweave init my-project
+cd my-project
+
+# Start building - SpecWeave guides you through the entire workflow
+/specweave:increment "User authentication"  # Plan increment
+/specweave:do                               # Implement tasks (auto-pauses if blocked, auto-resumes when ready)
+/specweave:done 0001                        # Complete increment
+```
+
+**New to SpecWeave?** → **[Getting Started Guide](https://spec-weave.com/docs/guides/getting-started/quickstart)**
+
+---
+
+## Key Features
+
+### 🧪 Test-Aware Planning
+Embedded test plans in every task with BDD format (Given/When/Then) for clarity
+
+### 🎯 Disciplined Progress
+Cannot start increment N+1 until N is DONE - enforces completion before moving forward
+
+### ⏸️ Intelligent Status Management
+Automatically detects when you're blocked (missing API keys, waiting for approval), pauses work with clear context, and resumes when ready - no manual intervention needed
+
+### 📚 Living Documentation
+Auto-updates after every task via Claude Code hooks - never outdated
+
+### 🤖 Intelligent Agents
+PM Agent, Architect, test-aware-planner, Quality Judge - specialized AI agents guide you
+
+### 🌍 Multilingual Support
+Work in 9 languages (Russian, Spanish, Chinese, German, French, Japanese, Korean, Portuguese) with zero-cost LLM-native translation
+
+**[→ Explore All Features](https://spec-weave.com/docs/overview/features)**
+
+---
+
+## Enterprise Features
+
+### 🏢 Multi-Project Support (v0.8.0+)
+
+Organize documentation by team, repo, or microservice:
+
+- **Team-Based Organization**: Frontend, Backend, Mobile, Platform teams with separate documentation
+- **Microservices Architecture**: Each service gets its own specs, modules, and team playbooks
+- **Per-Project Sync**: Link projects to different GitHub repos, JIRA projects, or ADO boards
+- **Unified Architecture**: Single project = multi-project with 1 project (NO special cases!)
+
+**Five Documentation Types Per Project**:
+1. **specs/** - Living documentation specs (user stories, AC)
+2. **modules/** - Module/component documentation (architecture, APIs)
+3. **team/** - Team playbooks (onboarding, conventions, workflows)
+4. **architecture/** - Project-specific ADRs (optional)
+5. **legacy/** - Brownfield imports (temporary)
+
+**[→ Multi-Project Setup Guide](https://spec-weave.com/docs/guides/multi-project-setup)**
+
+### 📦 Brownfield Import
+
+Import existing documentation from external sources:
+
+- **Automatic Classification**: AI-powered keyword detection (85%+ accuracy)
+- **Supported Sources**: Notion, Confluence, GitHub Wiki, custom markdown folders
+- **Smart Organization**: Classifies into specs, modules, team docs, or legacy
+- **Migration Reports**: Complete audit trail with confidence scores and manual review checklist
+
+**Example**:
+```bash
+# Import Notion export to web-app project
+/specweave:import-docs ~/Downloads/notion-export --source=notion --project=web-app
+
+# Result:
+# ✅ Classified 127 files
+#    - 37 specs → projects/web-app/specs/
+#    - 18 modules → projects/web-app/modules/
+#    - 12 team docs → projects/web-app/team/
+#    - 60 legacy → projects/web-app/legacy/notion/
+```
+
+**[→ Brownfield Integration Guide](https://spec-weave.com/docs/workflows/brownfield)**
+
+---
+
+## Documentation Hub
+
+**Learn SpecWeave:**
+- 📘 [What is SpecWeave?](https://spec-weave.com/docs/overview/introduction)
+- 🚀 [Quickstart Guide](https://spec-weave.com/docs/guides/getting-started/quickstart)
+- 🏗️ [Complete Workflow Journey](https://spec-weave.com/docs/workflows/overview)
+- ❓ [FAQ - Common Questions](https://spec-weave.com/docs/faq)
+
+**Commands & API:**
+- 📋 [Commands Reference](https://spec-weave.com/docs/commands/status-management)
+- 🔧 [API Documentation](https://spec-weave.com/docs/api)
+
+**Advanced Topics:**
+- 📊 [DORA Metrics Dashboard](https://spec-weave.com/docs/metrics)
+- 🏢 [Brownfield Integration](https://spec-weave.com/docs/workflows/brownfield)
+- 🌍 [Multilingual Support](https://spec-weave.com/docs/tutorial-extras/multilingual-support)
+- 🔗 [GitHub Actions Setup](https://spec-weave.com/docs/guides/github-action-setup)
+
+---
+
+## Community & Support
+
+**Join the Community:**
+
+- 💬 **[Discord Server](https://discord.gg/UYg4BGJ65V)** - Get help, share tips, discuss features
+- 🎥 **[YouTube Channel](https://www.youtube.com/@antonabyzov)** - Tutorials, demos, deep dives
+- 📖 **[Documentation](https://spec-weave.com)** - Complete guides and API reference
+- 🐛 **[GitHub Issues](https://github.com/anton-abyzov/specweave/issues)** - Bug reports and feature requests
+- 💡 **[GitHub Discussions](https://github.com/anton-abyzov/specweave/discussions)** - Q&A and community discussions
+
+**Need Help?**
+1. Check the **[FAQ](https://spec-weave.com/docs/faq)** first
+2. Ask in **[Discord](https://discord.gg/UYg4BGJ65V)** for quick answers
+3. Create a **[GitHub Discussion](https://github.com/anton-abyzov/specweave/discussions)** for detailed questions
+
+---
+
+## Contributing
+
+**Development Setup:**
+
+```bash
+# Clone and setup
+git clone https://github.com/anton-abyzov/specweave.git
+cd specweave
+npm install
+npm run build
+
+# Run tests
+npm test
+```
+
+**To Contribute:**
+1. Fork repository
+2. Create feature branch: `git checkout -b features/002-new-feature`
+3. Follow SpecWeave conventions (see CLAUDE.md)
+4. Add tests (minimum 3 test cases)
+5. Create PR to `develop` branch
+
+**[→ Contributor Guide](https://spec-weave.com/docs/guides/contributing)**
+
+---
+
+## Best Results with Claude Code
+
+SpecWeave gives **best results with Claude Code** due to unique capabilities:
+
+- ✅ **Native Plugin Marketplace** - Skills and agents auto-activate (no manual setup)
+- ✅ **Auto-Activating Skills** - Context-aware activation (no @ mentions)
+- ✅ **Isolated Agent Contexts** - True multi-agent role separation
+- ✅ **Pre/Post Lifecycle Hooks** - Automated living docs sync after every task
+- ✅ **MCP Protocol** - Industry standard for context management
+
+**Also works with**: Cursor, GitHub Copilot, ChatGPT (with manual workflow, reduced automation)
+
+**[→ Tool Comparison](https://spec-weave.com/docs/overview/features#claude-code-native)**
+
+---
+
+## Status & License
+
+**Status**: Beta - Ready for testing and contributions
+**License**: MIT
+**Repository**: [github.com/anton-abyzov/specweave](https://github.com/anton-abyzov/specweave)
+
+---
+
+## Acknowledgments
+
+SpecWeave is inspired by:
+- [spec-kit](https://github.com/github/spec-kit) - GitHub's specification toolkit
+- [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) - Agentic agile framework
+- [Claude Code](https://claude.com/claude-code) - Anthropic's native plugin system
+- [C4 Model](https://c4model.com/) - Software architecture diagrams
+
+---
+
+**SpecWeave** - AI made us fast. SpecWeave makes us sustainable.
+
+**Get started**: `npm install -g specweave` → `specweave init my-project` → **[Read the Docs](https://spec-weave.com)**

package/dist/cli/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAoBA,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,WAAW,CAC/B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAkoBf"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAoBA,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,WAAW,CAC/B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CA6qBf"}

package/dist/cli/commands/init.js

@@ -404,23 +404,6 @@ export async function initCommand(projectName, options = {}) {
             spinner.text = 'Using existing Git repository...';
         }
         spinner.succeed('SpecWeave project created successfully!');
-        // 10.5 Issue Tracker Integration (NEW!)
-        // Ask user to configure GitHub/Jira/ADO integration
-        try {
-            const { setupIssueTracker } = await import('../helpers/issue-tracker/index.js');
-            await setupIssueTracker({
-                projectPath: targetDir,
-                language: language,
-                maxRetries: 3
-            });
-        }
-        catch (error) {
-            // Non-critical error - log but continue
-            if (process.env.DEBUG) {
-                console.error(chalk.red(`\n❌ Issue tracker setup error: ${error.message}`));
-            }
-            console.log(chalk.yellow('\n⚠️  Issue tracker setup skipped (can configure later)'));
-        }
         // 11. Show tool-specific next steps
         if (toolName !== 'claude') {
             const adapter = adapterLoader.getAdapter(toolName);
@@ -433,8 +416,48 @@ export async function initCommand(projectName, options = {}) {
                 });
             }
         }
-        // 13. Create config.json with language setting
-        createConfigFile(targetDir, finalProjectName, toolName, language);
+        // 13. Documentation preview prompt (Claude Code only)
+        let enableDocsPreview = true; // Default: enabled
+        if (toolName === 'claude') {
+            try {
+                spinner.stop();
+                console.log('');
+                console.log(chalk.cyan('📚 Documentation Preview'));
+                console.log('');
+                console.log(chalk.white('   View your living documentation in a beautiful UI:'));
+                console.log(chalk.gray('   • Auto-generated sidebar from folder structure'));
+                console.log(chalk.gray('   • Hot reload (edit markdown, see changes instantly)'));
+                console.log(chalk.gray('   • Mermaid diagram rendering'));
+                console.log(chalk.gray('   • Installs dependencies on first use'));
+                console.log('');
+                const response = await inquirer.prompt([
+                    {
+                        type: 'confirm',
+                        name: 'enableDocsPreview',
+                        message: 'Enable documentation preview?',
+                        default: true
+                    }
+                ]);
+                enableDocsPreview = response.enableDocsPreview;
+                if (enableDocsPreview) {
+                    console.log(chalk.green('   ✔ Documentation preview enabled'));
+                    console.log(chalk.gray('   → Preview with: /specweave:docs preview'));
+                }
+                else {
+                    console.log(chalk.gray('   → Skipped (can enable later in .specweave/config.json)'));
+                }
+                console.log('');
+                spinner.start();
+            }
+            catch (error) {
+                // Non-critical - continue with default (enabled)
+                if (process.env.DEBUG) {
+                    console.error(chalk.red(`\n❌ Docs preview prompt error: ${error.message}`));
+                }
+            }
+        }
+        // 14. Create config.json with language setting and docs preview
+        createConfigFile(targetDir, finalProjectName, toolName, language, enableDocsPreview);
         // 14. Setup Claude Code plugin auto-registration (if Claude detected)
         let autoInstallSucceeded = false;
         if (toolName === 'claude') {
@@ -592,6 +615,24 @@ export async function initCommand(projectName, options = {}) {
                     autoInstallSucceeded = false;
                 }
             }
+            // 10.5 Issue Tracker Integration (NEW!)
+            // CRITICAL: Must happen AFTER marketplace registration and core plugin install
+            // Otherwise plugin installation will fail (marketplace not found)
+            try {
+                const { setupIssueTracker } = await import('../helpers/issue-tracker/index.js');
+                await setupIssueTracker({
+                    projectPath: targetDir,
+                    language: language,
+                    maxRetries: 3
+                });
+            }
+            catch (error) {
+                // Non-critical error - log but continue
+                if (process.env.DEBUG) {
+                    console.error(chalk.red(`\n❌ Issue tracker setup error: ${error.message}`));
+                }
+                console.log(chalk.yellow('\n⚠️  Issue tracker setup skipped (can configure later)'));
+            }
         }
         showNextSteps(finalProjectName, toolName, language, usedDotNotation, toolName === 'claude' ? autoInstallSucceeded : undefined);
     }
@@ -1045,7 +1086,7 @@ function copyHooks(hooksDir, targetHooksDir, language = 'en') {
 /**
  * Create .specweave/config.json with project settings
  */
-function createConfigFile(targetDir, projectName, adapter, language) {
+function createConfigFile(targetDir, projectName, adapter, language, enableDocsPreview = true) {
     const configPath = path.join(targetDir, '.specweave', 'config.json');
     const config = {
         project: {
@@ -1055,6 +1096,19 @@ function createConfigFile(targetDir, projectName, adapter, language) {
         adapters: {
             default: adapter,
         },
+        // Documentation preview settings (for Claude Code only)
+        ...(adapter === 'claude' && {
+            documentation: {
+                preview: {
+                    enabled: enableDocsPreview,
+                    autoInstall: false, // Lazy install on first use
+                    port: 3015, // Internal docs (avoid port 3000 - used by React/Next.js/Vite)
+                    openBrowser: true,
+                    theme: 'default',
+                    excludeFolders: ['legacy', 'node_modules']
+                }
+            }
+        }),
         // Only include language if non-English
         ...(language !== 'en' && {
             language,