@leanspec/ui 0.2.7-dev.20251126090633 → 0.2.7

package/.next/standalone/packages/ui/dist/standalone/specs/056-docs-site-accuracy-audit/README.md

@@ -0,0 +1,174 @@
+---
+status: complete
+created: '2025-11-06'
+tags:
+  - documentation
+  - quality
+  - launch
+  - v0.2.0
+priority: high
+related:
+  - '043'
+created_at: '2025-11-06T16:05:09.955Z'
+completed: '2025-11-06'
+updated_at: '2025-11-06T16:06:02.320Z'
+---
+
+# Documentation Site Accuracy Audit
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-06 · **Tags**: documentation, quality, launch, v0.2.0
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+**Goal**: Ensure documentation site is 100% accurate for v0.2.0 launch
+
+Pre-launch audit discovered critical inaccuracies in docs-site that would confuse users:
+- Wrong template names (referenced `solo-dev`, `team`, `api-first` that don't exist)
+- Incorrect default folder structure (showed date-grouped when default is flat)
+- Outdated tool references (VitePress instead of Docusaurus)
+- Build warnings (blog authors, truncation markers)
+
+**Why now**: Part of spec 043 (v0.2.0 launch) - "Documentation accuracy verified" is a success criterion. Can't launch with wrong examples.
+
+**Impact**: HIGH - Users following docs would encounter errors and confusion immediately after install.
+
+## Design
+
+### Approach
+
+Comprehensive audit of all documentation:
+1. **Structure audit** - Navigation, file organization
+2. **Content accuracy** - Examples match CLI behavior
+3. **Link validation** - No broken references
+4. **Build validation** - Clean builds with no warnings
+
+### Issues Found & Fixed
+
+#### 🔴 Critical (All Fixed)
+
+1. **Incorrect Template Names** (3 files)
+   - Docs: `solo-dev`, `team`, `api-first`
+   - Reality: `minimal`, `standard`, `enterprise`
+
+2. **Wrong Folder Structure** (15+ files)
+   - Docs showed: `specs/YYYYMMDD/NNN-name/` (date-grouped)
+   - Reality: `specs/NNN-name/` (flat is default)
+
+3. **Init Flow Mismatch** (2 files)
+   - Docs showed old prompts
+   - Updated to current flow
+
+4. **Blog Author Config Missing**
+   - Created `blog/authors.yml`
+
+#### ⚠️ Medium (All Fixed)
+
+5. **Blog Truncation Marker Missing**
+   - Added `<!-- truncate -->` to blog post
+
+6. **Outdated Tool References**
+   - Fixed `development.mdx` (VitePress → Docusaurus)
+
+7. **Broken Link** in development guide
+
+8. **Inaccurate Project Structure** documentation
+
+9. **Outdated Templates Documentation**
+   - `templates.mdx` referenced non-existent templates
+   - Updated to actual templates: minimal, standard, enterprise
+
+10. **Duplicate Content**
+    - Removed `quick-start.mdx` (duplicated getting-started)
+    - Updated navigation and links
+
+### Files Modified
+
+**Total: 19 files**
+
+**Content files (11):**
+- `docs/ai-integration/` - 4 files (setup, index, best-practices, examples)
+- `docs/guide/` - 6 files (getting-started, templates, custom-fields, frontmatter, development)
+- `docs/reference/` - 1 file (cli)
+
+**Configuration (2):**
+- `blog/authors.yml` - Created
+- `blog/2025-11-02-welcome.mdx` - Updated
+
+**Removed (1):**
+- `docs/guide/quick-start.mdx` - Removed (duplicated getting-started)
+
+**Structural:**
+- `sidebars.ts` - Updated navigation
+
+## Plan
+
+- [X] Audit navigation structure
+- [X] Check content accuracy across all sections
+- [X] Validate all examples match CLI
+- [X] Fix template name references
+- [X] Standardize folder structure examples
+- [X] Fix blog configuration
+- [X] Update development guide
+- [X] Verify clean build
+
+## Test
+
+### Success Criteria
+
+- [X] Build: `npm run build` succeeds with NO WARNINGS
+- [X] All template names match actual templates
+- [X] All folder examples show correct default (flat)
+- [X] All command examples work as shown
+- [X] No broken links
+- [X] Blog configuration clean
+
+### Validation
+
+```bash
+cd docs-site && npm run build
+# Result: [SUCCESS] Generated static files in "build".
+# NO WARNINGS ✅
+```
+
+All examples tested against actual CLI:
+- ✅ `lean-spec init` prompts match docs
+- ✅ `lean-spec create` output matches examples
+- ✅ `lean-spec list` format matches docs
+- ✅ Folder structure aligns with default config
+
+## Sub-Specs
+
+- **[AUDIT-RESULTS.md](./AUDIT-RESULTS.md)** - Detailed audit findings and corrections
+
+## Impact
+
+**Before**: Documentation had 20+ inaccuracies that would break user experience
+**After**: 100% accurate docs, clean builds, production-ready for launch
+
+**Launch readiness**: Documentation accuracy gate ✅ PASSED
+
+## Notes
+
+### Key Learnings
+
+1. **Documentation drift is real** - Code evolved faster than docs
+2. **Default matters** - Most examples showed optional config (date-grouped), not default (flat)
+3. **Template names changed** - Early templates renamed but docs not updated
+4. **Build warnings matter** - Even cosmetic warnings reduce confidence
+
+### For Future
+
+- Add automated tests for doc examples
+- Link checker in CI
+- Template name validation against actual templates
+- Regular doc audits before releases
+
+### Related
+
+- Spec 043: v0.2.0 launch (parent spec)
+- Spec 051: AGENTS.md and README updates
+- Accomplishes "Documentation accuracy verified" success criterion
+

package/.next/standalone/packages/ui/dist/standalone/specs/057-docs-validation-comprehensive/README.md

@@ -0,0 +1,295 @@
+---
+status: complete
+created: '2025-11-06'
+tags:
+  - documentation
+  - quality
+  - validation
+  - v0.2.0
+priority: high
+related:
+  - '043'
+  - '056'
+created_at: '2025-11-06T16:12:08.914Z'
+updated_at: '2025-11-06T16:29:38.311Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-06T16:21:03.384Z'
+  - status: complete
+    at: '2025-11-06T16:29:38.311Z'
+completed_at: '2025-11-06T16:29:38.311Z'
+completed: '2025-11-06'
+---
+
+# Comprehensive Documentation Validation
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-06 · **Tags**: documentation, quality, validation, v0.2.0
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+**📊 Results**: See [VALIDATION-RESULTS.md](./VALIDATION-RESULTS.md) for complete findings (11 issues documented)
+
+## Overview
+
+**Goal**: Deep validation that ALL documentation accurately reflects actual implementation and design
+
+Spec 056 fixed obvious inaccuracies (wrong template names, folder structures). This spec is a comprehensive validation pass to catch subtle mismatches between docs and reality.
+
+**Why now**: 
+- Part of v0.2.0 launch quality gate (spec 043)
+- Spec 056 was reactive (fixing known issues)
+- This is proactive (systematic validation)
+- Can't launch with docs that mislead users
+
+**Scope**: Every claim, example, and explanation in docs-site must match:
+1. Actual CLI behavior
+2. Source code implementation  
+3. Config file formats
+4. Template structures
+5. First principles (spec 049)
+
+## Design
+
+### Validation Approach
+
+**Method**: Systematic cross-reference check
+
+For each documentation page:
+1. **Extract claims** - What does the doc say the system does?
+2. **Verify against code** - Does the implementation match?
+3. **Test examples** - Do all code examples actually work?
+4. **Check consistency** - Do different pages tell the same story?
+
+### Areas to Validate
+
+#### 1. CLI Commands (`docs/reference/cli.mdx`)
+- [ ] Every command exists and works as documented
+- [ ] All flags and options are correct
+- [ ] Output examples match actual output format
+- [ ] Error messages match reality
+- [ ] Command aliases work as stated
+
+#### 2. Configuration (`docs/reference/config.mdx`)
+- [ ] All config fields exist and work
+- [ ] Default values are correct
+- [ ] Examples are valid JSON
+- [ ] Variable substitution works as documented
+- [ ] Custom fields behavior matches docs
+
+#### 3. Frontmatter (`docs/reference/frontmatter.mdx`, `docs/guide/frontmatter.mdx`)
+- [ ] Required fields match actual validation
+- [ ] Optional fields work as documented
+- [ ] Status values match StatusSchema
+- [ ] Priority values match PrioritySchema
+- [ ] Badge rendering matches examples
+
+#### 4. Templates (`docs/guide/templates.mdx`)
+- [ ] All three templates exist: minimal, standard, enterprise
+- [ ] Frontmatter examples match actual template files
+- [ ] Section descriptions match template content
+- [ ] Variable substitution works as shown
+
+#### 5. Init Flow (`docs/guide/getting-started.mdx`)
+- [ ] Prompts match actual init.ts implementation
+- [ ] Template selection options are correct
+- [ ] Pattern selection options exist
+- [ ] File creation matches docs
+- [ ] AGENTS.md handling works as described
+
+#### 6. Custom Fields (`docs/guide/custom-fields.mdx`)
+- [ ] Type validation works (string, number, boolean, array)
+- [ ] Filtering by custom fields works
+- [ ] Examples are valid
+- [ ] Config format is correct
+
+#### 7. Variables (`docs/guide/variables.mdx`)
+- [ ] All documented variables exist
+- [ ] Substitution syntax is correct
+- [ ] Built-in variables work: {date}, {name}, {project_name}, etc.
+- [ ] Custom variables work as documented
+
+#### 8. AI Integration (`docs/ai-integration/*.mdx`)
+- [ ] AGENTS.md template is current
+- [ ] MCP setup instructions work
+- [ ] Discovery commands exist and work
+- [ ] Examples match actual behavior
+- [ ] Best practices align with current design
+
+#### 9. Core Concepts
+- [ ] **Philosophy** - Aligns with actual design decisions
+- [ ] **First Principles** - Examples match reality
+- [ ] **Agile Principles** - Guidance is practical
+- [ ] **When to Use** - Decision framework is sound
+
+#### 10. Examples Throughout
+- [ ] All bash examples work when run
+- [ ] All YAML/JSON examples parse correctly
+- [ ] All file paths are valid
+- [ ] All command outputs are realistic
+
+### Common Issues to Check
+
+**Command mismatches:**
+- Flags that don't exist
+- Options that changed
+- Output format differences
+
+**Config mismatches:**
+- Field names that changed
+- Structure that evolved
+- Defaults that differ
+
+**Conceptual mismatches:**
+- Docs say X but code does Y
+- Philosophy contradicts implementation
+- Inconsistent terminology
+
+**Stale information:**
+- Old template names
+- Deprecated commands
+- Changed workflows
+
+## Plan
+
+### Preparation
+- [ ] Set up validation environment
+- [ ] Review spec 056 findings (don't duplicate)
+- [ ] Familiarize with current codebase
+
+### Validation (Page by Page)
+- [ ] `docs/guide/index.mdx` - Overview
+- [ ] `docs/guide/getting-started.mdx` - Installation & init
+- [ ] `docs/guide/philosophy.mdx` - Core philosophy
+- [ ] `docs/guide/first-principles.mdx` - First principles
+- [ ] `docs/guide/principles.mdx` - Agile principles  
+- [ ] `docs/guide/when-to-use.mdx` - Decision framework
+- [ ] `docs/guide/templates.mdx` - Template system
+- [ ] `docs/guide/frontmatter.mdx` - Frontmatter fields
+- [ ] `docs/guide/custom-fields.mdx` - Custom fields
+- [ ] `docs/guide/variables.mdx` - Variable substitution
+- [ ] `docs/guide/development.mdx` - Contributing
+- [ ] `docs/reference/cli.mdx` - CLI commands
+- [ ] `docs/reference/config.mdx` - Configuration
+- [ ] `docs/reference/frontmatter.mdx` - Frontmatter reference
+- [ ] `docs/ai-integration/index.mdx` - AI overview
+- [ ] `docs/ai-integration/setup.mdx` - AI setup
+- [ ] `docs/ai-integration/agents-md.mdx` - AGENTS.md template
+- [ ] `docs/ai-integration/best-practices.mdx` - AI best practices
+- [ ] `docs/ai-integration/examples.mdx` - AI examples
+
+### Documentation
+- [ ] Document all found issues
+- [ ] Categorize by severity (critical/medium/minor)
+- [ ] Create fix checklist
+- [ ] Update spec 056 if issues already partially fixed
+
+### Validation
+- [ ] All issues documented
+- [ ] Fix plan created
+- [ ] Ready for implementation
+
+## Test
+
+### Success Criteria
+
+**Completeness:**
+- [ ] Every doc page validated
+- [ ] Every code example tested
+- [ ] Every claim verified
+
+**Accuracy:**
+- [ ] All critical mismatches found
+- [ ] All medium mismatches found
+- [ ] Minor mismatches documented
+
+**Actionability:**
+- [ ] Clear list of issues with locations
+- [ ] Severity rating for each issue
+- [ ] Specific fix recommendations
+
+### Validation Checklist
+
+For each issue found, document:
+1. **Location**: File path and line/section
+2. **Issue**: What's wrong (docs say X, reality is Y)
+3. **Severity**: Critical / Medium / Minor
+4. **Fix**: What needs to change
+5. **Verification**: How to test the fix
+
+## Notes
+
+### Why This Matters
+
+Spec 056 caught obvious issues (wrong template names). But subtle issues are worse:
+- User follows docs, gets unexpected behavior
+- User loses trust in documentation
+- Support burden increases
+- Launch reputation suffers
+
+### Scope Boundaries
+
+**In scope:**
+- Technical accuracy (commands, configs, examples)
+- Conceptual alignment (philosophy matches design)
+- Example validity (code actually works)
+
+**Out of scope:**
+- Writing quality/grammar (not accuracy issue)
+- Missing documentation (not incorrect docs)
+- Feature requests (not validation)
+
+### For the Coding Agent
+
+**Instructions:**
+1. Read this spec thoroughly
+2. Go through each doc page systematically
+3. For each claim/example, verify against:
+   - `src/` source code
+   - `templates/` actual templates
+   - `lean-spec --help` actual CLI
+4. Document every mismatch found
+5. Use the validation checklist format
+6. Categorize by severity
+7. Create actionable fix list
+
+**Output format:**
+```markdown
+## Issue #N: [Short description]
+- **Location**: `docs/path/file.mdx` (line X or section "Y")
+- **Docs say**: "..."
+- **Reality is**: "..."
+- **Severity**: Critical/Medium/Minor
+- **Fix**: [Specific change needed]
+- **Verification**: [How to test]
+```
+
+**Create results in**: `specs/057-docs-validation-comprehensive/VALIDATION-RESULTS.md`
+
+### Related
+
+- Spec 043: v0.2.0 launch (parent)
+- Spec 056: Initial docs audit (predecessor)
+- Spec 049: First principles (validation reference)
+- Accomplishes "Documentation accuracy verified" quality gate
+
+---
+
+## Results Summary
+
+**Validation Status**: ✅ Complete
+
+**Issues Found**: 11 total
+- **Critical**: 5 issues
+- **Medium**: 5 issues
+- **Minor**: 1 issue
+
+**Key Findings**:
+1. Configuration documentation completely out of sync with implementation
+2. Invalid status values (`blocked`, `cancelled`) documented but don't exist
+3. Multiple CLI commands missing documented options
+4. Status icon inconsistencies between documentation and code
+
+**Deliverable**: Complete validation results in [VALIDATION-RESULTS.md](./VALIDATION-RESULTS.md)
+
+**Next Steps**: Issues documented and ready for fixing in a separate spec/PR