@leanspec/ui 0.2.5 → 0.2.6-dev.20251125010539

package/.next/standalone/packages/ui/dist/standalone/specs/058-docs-overview-polish/ANALYSIS.md

@@ -1,241 +0,0 @@
-# Analysis: Documentation Structure Issues
-
-This document contains the detailed problem analysis that informed the redesign.
-
-## Current State Analysis
-
-### Problem #1: AI Integration Structure is Wrong (Critical)
-
-**Current State**: Separate "AI Integration" tab in navigation
-
-**Why This is Wrong**:
-- LeanSpec is **fundamentally AI-native** - not an optional feature
-- Treating AI as separate contradicts our core identity
-- Users think: "I don't use AI, I can skip this" - Wrong mindset!
-- Should be integrated into Guide as "Working with AI" workflow
-
-**Evidence**:
-- README.md emphasizes "AI-native" in first paragraph
-- Spec 049 First Principles designed for human + AI collaboration
-- MCP server is a core tool, not an add-on
-- Every workflow assumes AI agents
-
-**Fix**: Move "AI Integration" into Guide section as "Working with AI"
-
-### Problem #2: Core Concepts Don't Reflect First Principles (Critical)
-
-**Current State**: Core Concepts has:
-- `philosophy.mdx` - Mentions first principles but doesn't deeply explain them
-- `principles.mdx` - "Agile Principles" (good but missing foundation)
-- Missing: **First Principles doc itself**
-
-**Why This is Wrong**:
-- Spec 049 established 5 First Principles (Context Economy, Signal-to-Noise, etc.)
-- These are the **foundation** - everything derives from them
-- Current docs don't show the derivation hierarchy
-- Philosophy appears arbitrary without showing it derives from principles
-
-**Fix**: Add First Principles doc, update Philosophy to show derivation
-
-### Problem #3: `docs/` Folder Content Not Integrated (High Priority)
-
-**Current State**: Valuable content exists in `docs/` but not in docs-site:
-- `docs/MCP-SERVER.md` - Comprehensive MCP setup (more detailed than docs-site)
-- `docs/MIGRATION.md` - Migration guides
-- `docs/examples/` - Custom fields examples and configs
-
-**Why This is Wrong**:
-- Duplicate content causes confusion ("which one is canonical?")
-- `docs/` folder has better detail (e.g., MCP troubleshooting, security)
-- Users may miss important content
-- Hard to maintain two documentation sources
-
-**Fix**: Migrate `docs/` content into docs-site, deprecate `docs/` folder
-
-### Problem #4: Navigation Doesn't Reflect Workflow (Medium Priority)
-
-**Current Structure**:
-```
-Guide/
-  - Introduction (Overview, Getting Started)
-  - Core Concepts (Philosophy, Principles, When to Use)
-  - Features (Templates, Frontmatter, Custom Fields, Variables)
-Reference/
-  - CLI, Config, Frontmatter
-AI Integration/ (separate tab)
-Roadmap
-```
-
-**Issues**:
-- No workflow section (board, stats, deps, validate are in CLI reference)
-- Features and workflow mixed together
-- No MCP reference (it's only in AI Integration)
-- Doesn't show progression: Concepts → Setup → Workflow → Reference
-
-**Fix**: Restructure navigation to match user journey
-
-## Original Issues (Minor Priority)
-
-### Issue #1: Feature Section Needs Restructuring
-
-**Location**: "How It Works" section in overview
-
-**Problem**: Section lists 5 CLI capabilities but:
-1. Missing **MCP server** - major feature for AI integration!
-2. Missing other key commands: `board`, `stats`, `deps`, `validate`, etc.
-3. These are CLI commands, but framed as "what LeanSpec provides" (confusing scope)
-4. No mention of roadmap/vision (VS Code extension, GitHub Action, PM integrations, etc.)
-
-**Proposed Solution**: Replace "How It Works" with "What You Get" section that groups by:
-- Core CLI (create, organize, search, board, stats, validate)
-- MCP Server (AI integration)
-- Templates & Customization (minimal/standard/enterprise, custom fields)
-
-### Issue #2: Example Structure vs Templates
-
-**Location**: "A Simple Example" section
-
-**Problem**: Example structure doesn't match actual templates:
-- **Minimal template**: Goal, Key Points, Non-Goals, Notes
-- **Standard template**: Overview, Design, Plan, Test, Notes
-- **Example**: Goal, Key Scenarios, Acceptance Criteria, Technical Contracts, Non-Goals
-
-**Fix**: Add clarifying note that example is illustrative, not prescriptive
-
-### Issue #3: Example Date
-
-**Location**: Same example
-
-**Problem**: Date is in the past (`created: 2025-11-02`)
-
-**Fix**: Change to `created: 2025-11-07` or use `{date}` variable
-
-## Comparative Analysis
-
-### Current vs Proposed Structure
-
-**Current (Problematic)**:
-- 3 top-level tabs (Guide, Reference, AI Integration)
-- AI treated as optional add-on
-- No First Principles documentation
-- Duplicate content in `docs/` folder
-- Workflow buried in CLI reference
-
-**Proposed (Aligned)**:
-- 2 top-level tabs (Guide, Reference)
-- AI integrated into Guide workflow
-- First Principles prominent in Core Concepts
-- Single source of truth (docs-site)
-- Dedicated Workflow section
-
-## User Journey Mapping
-
-### Current Journey (Confusing)
-1. Read Overview → "What is LeanSpec?"
-2. Core Concepts → Philosophy (but why these principles?)
-3. Features → Templates (how to start?)
-4. Stuck: Where's AI integration? Where's workflow?
-
-### Proposed Journey (Clear)
-1. Introduction → Overview, Getting Started, Examples
-2. Core Concepts → First Principles (foundation), Philosophy (application)
-3. Working with AI → Setup, Best Practices (integrated workflow)
-4. Features → Templates, Custom Fields (customization)
-5. Workflow → Board/Stats, Dependencies, Validation (daily usage)
-6. Reference → CLI, Config, Frontmatter, MCP API (technical details)
-
-## Content Migration Map
-
-### From `docs/` to docs-site
-
-| Source | Destination | Action |
-|--------|-------------|--------|
-| `docs/MCP-SERVER.md` | `docs-site/docs/reference/mcp-server.mdx` | Migrate + enhance |
-| `docs/MIGRATION.md` | `docs-site/docs/guide/migration.mdx` | Migrate |
-| `docs/examples/CUSTOM-FIELDS-GUIDE.md` | `docs-site/docs/guide/custom-fields.mdx` | Merge |
-| `docs/examples/*.json` | Inline in custom-fields.mdx | Include as examples |
-
-### Within docs-site
-
-| Source | Destination | Action |
-|--------|-------------|--------|
-| `ai-integration/index.mdx` | `guide/ai-setup.mdx` | Move + rename |
-| `ai-integration/setup.mdx` | Merge into `guide/ai-setup.mdx` | Merge |
-| `ai-integration/best-practices.mdx` | `guide/ai-best-practices.mdx` | Move |
-| `ai-integration/examples.mdx` | `guide/ai-examples.mdx` | Move |
-| `ai-integration/agents-md.mdx` | Incorporate into `guide/ai-setup.mdx` | Merge |
-
-## Impact Analysis
-
-### Breaking Changes
-- None (only documentation reorganization)
-- Old URLs redirect or show clear navigation
-
-### User Impact
-- **Positive**: Clearer structure, easier to find content
-- **Neutral**: Content is the same, just reorganized
-- **Negative**: None expected (all content remains accessible)
-
-### Maintenance Impact
-- **Reduced**: Single docs source (docs-site)
-- **Improved**: Clear structure for future additions
-- **Easier**: Less duplication, clearer ownership
-
-## Risk Assessment
-
-### Low Risk
-- ✅ No code changes
-- ✅ No API changes
-- ✅ Content reorganization only
-
-### Medium Risk
-- ⚠️ Broken internal links (mitigated by thorough testing)
-- ⚠️ User confusion during transition (mitigated by clear communication)
-
-### High Risk
-- None identified
-
-## Success Metrics
-
-### Quantitative
-- Zero broken links after migration
-- Build time remains <30 seconds
-- All internal references updated
-- Zero 404s after deployment
-
-### Qualitative
-- Navigation flows logically
-- First Principles clearly explained
-- AI integration feels core, not optional
-- Users can find content in <2 clicks
-
-## Validation Strategy
-
-### Automated
-1. Build docs-site without errors
-2. Check for broken links (link checker)
-3. Validate spec structure (`lean-spec validate`)
-4. Search functionality still works
-
-### Manual
-1. Review navigation flow
-2. Verify all content migrated
-3. Check mobile/desktop rendering
-4. Test search for common queries
-
-## Timeline Estimate
-
-| Phase | Estimated Time | Critical Path |
-|-------|----------------|---------------|
-| Navigation & Structure | 2-3 hours | Yes |
-| Core Concepts | 2-3 hours | Yes (foundation) |
-| AI Content Move | 3-4 hours | Yes (biggest change) |
-| Migrate `docs/` | 2-3 hours | No |
-| Workflow Section | 2-3 hours | No |
-| Overview Updates | 1-2 hours | No |
-| Testing | 1-2 hours | Yes |
-| Polish | 1 hour | No |
-
-**Total**: 8-12 hours over 1-2 days
-
-**Critical Path**: 7-9 hours (Navigation → Core Concepts → AI Move → Testing)

package/.next/standalone/packages/ui/dist/standalone/specs/058-docs-overview-polish/DESIGN.md

@@ -1,279 +0,0 @@
-# Design: Documentation Structure Redesign
-
-This document contains the architecture and key design decisions for the new documentation structure.
-
-## Navigation Restructure
-
-### New Sidebar Structure
-
-```typescript
-const sidebars: SidebarsConfig = {
-  guideSidebar: [
-    {
-      type: 'category',
-      label: 'Introduction',
-      items: ['guide/index', 'guide/getting-started', 'guide/examples'],
-    },
-    {
-      type: 'category',
-      label: 'Core Concepts',
-      items: ['guide/first-principles', 'guide/philosophy', 'guide/when-to-use'],
-    },
-    {
-      type: 'category',
-      label: 'Working with AI',
-      items: ['guide/ai-setup', 'guide/ai-best-practices', 'guide/ai-examples'],
-    },
-    {
-      type: 'category',
-      label: 'Features',
-      items: ['guide/templates', 'guide/custom-fields', 'guide/variables'],
-    },
-    {
-      type: 'category',
-      label: 'Workflow',
-      items: ['guide/board-stats', 'guide/dependencies', 'guide/validation'],
-    },
-    'guide/migration',
-    'roadmap',
-  ],
-  referenceSidebar: [
-    'reference/cli',
-    'reference/config',
-    'reference/frontmatter',
-    'reference/mcp-server',
-  ],
-};
-```
-
-**Key Changes**:
-1. Remove `aiSidebar` completely (content moved to guideSidebar)
-2. AI Integration → "Working with AI" in Guide
-3. Add First Principles to Core Concepts
-4. Add Workflow section
-5. Add MCP Server to Reference
-
-### Key Design Decisions
-
-**Decision #1: AI Integration → Working with AI**
-- **Rationale**: AI is core to LeanSpec, not optional
-- **Placement**: Within Guide (part of workflow)
-- **First Principle**: Bridge the Gap (align human + AI)
-
-**Decision #2: First Principles Prominent**
-- **Rationale**: Foundation for everything else
-- **Placement**: First item in Core Concepts
-- **First Principle**: Intent Over Implementation (capture why)
-
-**Decision #3: Workflow Section**
-- **Rationale**: Practical usage needs dedicated section
-- **Placement**: After Features (progression: learn → customize → use)
-- **First Principle**: Progressive Disclosure (add structure when useful)
-
-**Decision #4: MCP in Reference**
-- **Rationale**: Technical API documentation
-- **Placement**: Reference section (alongside CLI, Config)
-- **First Principle**: Context Economy (separate concerns)
-
-## Content Architecture
-
-### Documentation Hierarchy
-
-```
-Introduction (What & Why)
-  ├─ Overview: What is LeanSpec, why it exists
-  ├─ Getting Started: Install, init, first spec
-  └─ Examples: Real specs from this project
-
-Core Concepts (Foundation)
-  ├─ First Principles: 5 fundamental constraints
-  ├─ Philosophy: How to apply principles
-  └─ When to Use: Appropriate use cases
-
-Working with AI (Integration)
-  ├─ Setup: AGENTS.md, MCP, IDE integration
-  ├─ Best Practices: Writing specs for AI
-  └─ Examples: Real workflows
-
-Features (Customization)
-  ├─ Templates: Minimal, standard, enterprise
-  ├─ Custom Fields: Adapt to workflow
-  └─ Variables: Template variables
-
-Workflow (Daily Usage)
-  ├─ Board & Stats: Project visibility
-  ├─ Dependencies: Spec relationships
-  └─ Validation: Quality checks
-
-Reference (Technical)
-  ├─ CLI Commands: Complete reference
-  ├─ Configuration: config.json schema
-  ├─ Frontmatter: Schema and fields
-  └─ MCP Server: API reference
-
-Roadmap (Future)
-```
-
-### Content Flow
-
-**User Journey**:
-1. **Introduction** → Understand what LeanSpec is
-2. **Core Concepts** → Learn the foundation
-3. **Working with AI** → Set up tools
-4. **Features** → Customize to needs
-5. **Workflow** → Use daily
-6. **Reference** → Look up details
-
-## Content Changes
-
-**See [IMPLEMENTATION.md](./IMPLEMENTATION.md) for detailed content specifications.**
-
-### Summary of Changes
-
-**New Content**:
-- `guide/first-principles.mdx` (from spec 049)
-- `guide/board-stats.mdx` (new)
-- `guide/dependencies.mdx` (new)
-- `guide/validation.mdx` (new)
-- `reference/mcp-server.mdx` (enhanced from `docs/MCP-SERVER.md`)
-- `guide/migration.mdx` (from `docs/MIGRATION.md`)
-
-**Updated Content**:
-- `guide/philosophy.mdx` (add First Principles derivation)
-- `guide/ai-setup.mdx` (merge from ai-integration/)
-- `guide/custom-fields.mdx` (merge examples from `docs/examples/`)
-
-**Moved Content**:
-- `ai-integration/` → `guide/` (all AI content)
-
-**Deleted**:
-- `docs-site/docs/ai-integration/` directory (after migration)
-- `docs/` folder content (after integration, keep folder with redirect)
-
-## Migration Strategy
-
-### Phase-by-Phase Approach
-
-**Phase 1: Structure** (Non-breaking)
-- Update `sidebars.ts`
-- Create placeholder files
-- Test build
-
-**Phase 2: Content** (Content-heavy)
-- Create first-principles.mdx
-- Update philosophy.mdx
-- Migrate AI content
-
-**Phase 3: Consolidation** (Critical)
-- Migrate `docs/` content
-- Update all links
-- Delete old structure
-
-**Phase 4: Polish** (Quality)
-- Add examples
-- Improve formatting
-- Final testing
-
-### Backward Compatibility
-
-**Link Redirects**:
-```
-/docs/ai-integration/setup → /docs/guide/ai-setup
-/docs/ai-integration/best-practices → /docs/guide/ai-best-practices
-[etc.]
-```
-
-**Implementation**:
-- Use Docusaurus redirect plugin
-- Add redirect entries to `docusaurus.config.ts`
-
-## Design Validation
-
-### Alignment with First Principles
-
-**Context Economy**: ✅
-- Clear section boundaries
-- Logical grouping
-- Easy to navigate
-
-**Signal-to-Noise**: ✅
-- No duplicate content
-- Clear purpose for each section
-- Progressive depth
-
-**Intent Over Implementation**: ✅
-- Shows why (First Principles)
-- Shows how (Philosophy, Workflow)
-- References for details
-
-**Bridge the Gap**: ✅
-- Human-readable navigation
-- AI-friendly structure
-- Both audiences served
-
-**Progressive Disclosure**: ✅
-- Introduction → Concepts → Setup → Features → Workflow → Reference
-- Can start simple, go deep as needed
-
-### User Journey Validation
-
-**New Developer**:
-1. Introduction → Quick start
-2. Core Concepts → Understand foundation
-3. Working with AI → Set up tools
-4. Templates → First spec
-✅ Clear path
-
-**Experienced Developer**:
-1. Jump to Workflow → Daily usage
-2. Reference → Command details
-✅ Fast access
-
-**AI Agent**:
-1. Can parse structure
-2. Clear hierarchies
-3. Unambiguous references
-✅ Machine-friendly
-
-## Technical Considerations
-
-### Build Impact
-- No build time increase expected
-- Same number of pages (reorganized, not expanded)
-- Search index regenerated (automatic)
-
-### Performance
-- Navigation depth unchanged
-- Asset loading unchanged
-- No performance impact
-
-### SEO
-- Update sitemap (automatic)
-- Some URL changes (redirects handle)
-- Content quality improves (better structure)
-
-## Success Criteria
-
-### Structural
-- [x] Clear hierarchy (Introduction → Concepts → AI → Features → Workflow → Reference)
-- [x] No duplicate content
-- [x] Logical grouping
-- [x] Consistent depth
-
-### Content
-- [x] First Principles clearly explained
-- [x] Philosophy shows derivation
-- [x] AI integration feels core
-- [x] All `docs/` content integrated
-
-### Technical
-- [x] Builds without errors
-- [x] No broken links
-- [x] Redirects configured
-- [x] Search works
-
-### User Experience
-- [x] Can find content in <2 clicks
-- [x] Navigation flows logically
-- [x] Mobile-friendly
-- [x] Accessible